Bruker BAF (analysis.baf in a .d directory)
Bruker’s TOF and Q-TOF instruments outside the timsTOF line (micrOTOF, micrOTOF-Q, maXis, impact, compact) and its FT-ICR instruments (apex, solariX) write each run as analysis.baf in a .d directory, with analysis.baf_idx, analysis.baf_xtr and, once processing software has opened the run, analysis.sqlite and Calibrator.ami. OpenReadout reads the spectra (centroid lists and profiles) with their retention times, MS levels, precursors and m/z. Derived from public files compared with the depositors’ vendor-library conversions; no specification or prior reader exists. Provenance: docs/provenance/bruker-baf.md. Reader: crate openreadout-bruker-tims, module baf, format id bruker-baf. (timsTOF TDF/TSF directories: docs/formats/bruker-tdf.md.)
Detection (locate, looks_like): a directory holding analysis.baf, or that file itself; the file starts with the pointer record. Only analysis.baf and Calibrator.ami are read.
Records
The file is a chain of records, each a u32 length (the whole record), a u32 tag 0xBFA0xxxx (TAG_BASE) and a payload; several records hold a header and a chain of sub-records with the same framing (walk, RecordRef { offset, len, tag }). Little-endian unless stated.
| tag | constant | content |
|---|---|---|
BFA00009 |
TAG_POINTERS |
first record: u32 0xBFA00005, then u64 offsets of the acquisition header, the summary table and the trailer index (parse_pointers, Pointers { acquisition, summary, trailer }) |
BFA04001 |
TAG_WRITER |
32-byte writer id (AIDA6.4.0.1, BCC4_3_72_0): format_version |
BFA04003 |
TAG_COMPRESSOR |
a GUID and the compressor’s name (Variable VLI2 based compressor) |
BFA03001 |
TAG_ACQUISITION |
acquisition header (below) |
BFA02001 |
TAG_SEGMENT |
an acquisition segment: u32 header size, u32 0, u32 segment number, then one sub-record BFA0000D (TAG_SEGMENT_VARIABLES) per scan type: u32 header size, u32 count, 4 scan-type bytes, then (u16 variable id, 8-byte value) pairs (parse_segment, Segment { number, lists }, SegmentList { scan_type, values }) |
BFA02002 |
TAG_SPECTRUM |
a spectrum (below) |
BFA01001 |
TAG_PROFILE |
a profile block (below) |
BFA01002 |
TAG_LINES |
a centroid block (below) |
BFA00008 |
TAG_SUMMARY |
one entry per spectrum: retention time, segment, id, block flags, five line statistics, scan-type bytes and (MS1) the calibration (parse_summary, SummaryEntry { id, segment, rt_ms, flags, stats, scan_type }) |
BFA0000A |
TAG_TRAILER |
(u32 id, u64 offset) pairs after a 64-byte header for every segment, spectrum, profile, centroid and end-of-spectrum record (parse_trailer) |
The reader takes record offsets from the trailer index (each checked to be a record) and walks the chain one record at a time when the pointer record or the trailer index is missing (an acquisition that did not finish); info → extra.index_source says which.
Acquisition header
parse_acquisition → AcquisitionHeader { started_utc, analysis_name, strings, variables, reference_calibrations } (string, variable_id, variables_json): a date block 40 bytes into the body (44 in the 2008 file): u8 day, u8 month, u16 year, i16 UTC offset in minutes, u16 milliseconds, u8 second, minute, hour in UTC; the analysis name; then sub-records. The string table (TAG_STRINGS, parse_strings): u32 header size, u32 offsets of strings 2 to n up to the first 0, string 1 at the header size; in order the source path, instrument, operator (left out of info), acquisition software, its version, method, a dotted version, a role and the sample name. Variable definitions (TAG_VARIABLE_DEFS, parse_variable_defs, VariableDef { name, group, label, value_text, format, unit, kind }, decode, text_of): u16 header size, u16 count, entries of u16 length, u16 id, u8 type (10 double; 0, 1, 3, 4, 5 64-bit integer), u8 0xFF and seven u16 offsets of strings. Calibration sub-records (TAG_CALIBRATION) hold the reference calibrations.
Spectra
A spectrum record (parse_spectrum, SpectrumRecord { segment, id, flags, rt_ms, scan_type, variables, precursors, calibration }): u32 header size (40), segment, id (1-based, the scan number; native id scan=<id>), block flags (3 profile and centroids, 2 centroids), retention time in milliseconds, 0, the scan-type bytes (polarity 0 positive, 1 negative; scan mode in byte 2), then sub-records: the variable list (TAG_VARIABLES, parse_variable_list), the precursor list (TAG_PRECURSORS: u32, u32 n, n × f32 isolation m/z) and the calibration (TAG_CALIBRATION, payload after 12 bytes). MS level (ms_level) = 1 + the number of precursors; the precursor m/z is the last one (all of them in extra.precursors for MS³ and above); the isolation window is ± half of Quadrupole_IsolationResolution_Act, or ± 1 when that is 0; the collision energy is Collision_Energy_Act; the activation is the value text of MSMS_FragmentationMode_Act (0:CID;1:ETD); the precursor charge is MSMS_PreCursorChargeState when it is not 0 (as the vendor library reports it; values such as 13 occur). The scan window is Mode_ScanBegin/Mode_ScanEnd of the segment’s list for the spectrum’s scan type; TIC and base-peak intensity are the summary table’s line sum and maximum.
A centroid block (parse_lines, LineBlock { id, element_code, stats, position, intensity, width }): u32 header size (52), id, id, element code, line count, u32, five f32 statistics; then u32 count and eight u32 array offsets; each array’s element size (4 or 8) is its length divided by the count. Positions are fractional sample indices, converted to m/z by the calibration; the third array (element codes 1 and 3) is kept unread as widths.
A profile block (parse_profile): u32 header size (44), id, id, four coding bytes, u32 A, u32 B. Coding 09 04 FF 00: A float32 samples. Coding 02 01 06 00: A packed bytes (decode_packed, PACKED_MARKER, MAX_SAMPLES): u32 marker 0xEE77, u32 sample count, u32 big-endian table length (26), the table (nine class widths 0, 4, 5, 6, 7, 9, 10, 11, 32; code lengths 1 to 9; one extra symbol of length 10), then a bit stream read most significant bit first: a class code of c zero bits and a one; class 0 repeats the current value; classes 1 to 7 read width + 1 bits u, magnitude (u >> 1) + base (1, 17, 49, 113, 241, 753, 1777), negative when u is odd; class 8 a 32-bit two’s-complement delta; class 9 a 32-bit run of the current value. Coding 02 01 09 00 (ZLIB_CODING, the solariX XR file): A zlib-compressed bytes that inflate to float32 samples. Other tables, markers or codings exit 6. Sample i is at sample index i. The spectrum’s primary view is the profile when one is stored, the centroids otherwise; --view centroid gives the centroids.
Calibration
parse_payload → Calibration { Tof, Ft } (mz, name); CalibrationIssue { Unknown, Damaged }.
- Time of flight, kind 3 (
TofCalibration{kind,delay_ns,timebase_ns,t0_ns,k,q,poly,poly_range,shift,temperatures}): t = delay + timebase · index; k1 = 10⁶ / √K; √(m/z) = (−k1 + √(k1² − 4Q(t0 − t))) / 2Q (or (t − t0) / k1 when Q = 0); then m/z −= p(clamp(m, lo, hi)) · exp(−d²) with d the distance outside [lo, hi] in Da. The detector temperatures follow the polynomial. - Kind 10 (maXis): the same quadratic, then m/z −= a mass shift; a non-zero sixth constant exits 6.
- FT-ICR (u32 type 4) (
FtCalibration{c2,c3,n_fft,f_high}): f = f_high · (1 − index / N), m/z = c3 / (f + c2). - Drift compensation (
DriftSettings{reference,gradient,enabled,one_sensor},factor;ReferenceCalibration{t0_ns,k,q,reference,gradient},parse_reference): the header’s reference calibration with the spectra’s t0 gives K and Q at the reference temperatures and the gradients; at a spectrum’s temperatures T, f = 1 − 10⁻⁶ (g1 (T1 − r1) + g2 (T2 − r2)) (the second term left out whenTOF_UseOnlyOneTemperatureis set, no compensation whenTOF_SwitchTempCompensationis 0), K = K_ref · f, Q = Q_ref / f. The reader recomputes them rather than taking the stored values, a few of which are stale. - Recalibration (
find_recalibration): when the directory holdsCalibrator.ami, the first payload in it of the first spectrum’s kind, delay and time base replaces each spectrum’s, with K multiplied and Q divided by f(T spectrum) / f(T recalibration) (or by the ratio of the spectra’s stored K when temperatures are missing). Vendor exports of such runs use it;info→extra.mz_calibration_sourcesays which calibration applies.
Integrity checks (check)
index (warnings found while opening), missing_blocks (spectra without a centroid block), gaps (spectrum ids not consecutive), summary_mismatch (summary table and spectrum records disagree), calibration (spectra whose calibration is not read), bad_block (a block that does not decode; full check).
Vocabulary (every public identifier of the baf module must appear here)
| identifier | meaning |
|---|---|
BrukerBafReader, BafDataset, FORMAT_ID, open, locate, looks_like |
reader, detection and opened dataset |
TAG_BASE, TAG_POINTERS, TAG_SUMMARY, TAG_TRAILER, TAG_ACQUISITION, TAG_VARIABLE_DEFS, TAG_STRINGS, TAG_SEGMENT, TAG_SPECTRUM, TAG_PROFILE, TAG_LINES, TAG_WRITER, TAG_COMPRESSOR, TAG_VARIABLES, TAG_PRECURSORS, TAG_CALIBRATION, TAG_SEGMENT_VARIABLES |
record tags |
RecordRef { offset, len, tag }, walk, cstr, Pointers { acquisition, summary, trailer }, parse_pointers, parse_trailer |
record chain |
AcquisitionHeader { started_utc, analysis_name, strings, variables, reference_calibrations }, string, variable_id, variables_json, parse_acquisition, parse_strings |
acquisition header |
VariableDef { name, group, label, value_text, format, unit, kind }, decode, text_of, parse_variable_defs, parse_variable_list, variable |
variables |
Segment { number, lists }, SegmentList { scan_type, values }, parse_segment |
segments |
SummaryEntry { id, segment, rt_ms, flags, stats, scan_type }, parse_summary |
summary table |
SpectrumRecord { segment, id, flags, rt_ms, scan_type, variables, precursors, calibration }, ms_level, parse_spectrum, SpectrumEntry { record, offset, lines, profile, summary } |
spectra |
LineBlock { id, element_code, stats, position, intensity, width }, parse_lines, parse_profile, decode_packed, PACKED_MARKER, ZLIB_CODING, MAX_SAMPLES |
centroid and profile blocks |
Calibration { Tof, Ft }, TofCalibration { kind, delay_ns, timebase_ns, t0_ns, k, q, poly, poly_range, shift, temperatures }, FtCalibration { c2, c3, n_fft, f_high }, CalibrationIssue { Unknown, Damaged }, parse_payload, mz, name |
calibrations |
DriftSettings { reference, gradient, enabled, one_sensor }, factor, ReferenceCalibration { t0_ns, k, q, reference, gradient }, parse_reference, find_recalibration |
drift compensation and recalibration |
baf, calibration, dataset, records, spectrum |
modules |
info → spectra[0].extra: acquired_utc, utc_offset_minutes, method, sample_name, analysis_name, writer, compressor, segments, profile_spectra, calibration, mz_calibration_source, index_source, analysis_sqlite, profile_coding, centroid_element_code, polarities. Per spectrum extra: segment, scan_mode_code, precursors.
Oracle mapping (corpus harness)
oracle/gen.py (bruker_baf): the depositor’s mzML (ProteoWizard with the vendor library, or CompassXport), read with pyteomics like the other vendor-export oracles; scans by scan number.
Known gaps
Calibrator.ami’s container is not decoded: its payload is found by scanning. Without the file, m/z are the acquisition calibration’s.analysis.baf_xtr(where the vendor library finds a refined precursor m/z for some instruments), the integer and real list sub-records and the third centroid array are not decoded.- Calibration kinds, profile codings and code tables other than the ones above exit 6.
How this reader was derived, file by file: provenance log.