Skip to content

Waters MassLynx .raw directories

Waters MassLynx writes each acquisition (Xevo, SYNAPT, ACQUITY and other instruments) as a directory ending in .raw. OpenReadout returns MRM and SIR data as tables and traces, full-scan spectra, the drift bins of ion-mobility and SONAR acquisitions, PDA traces and analog channels. Lock-mass correction is off by default and applied on request (see Lock-mass correction below).

Derived from public MetaboLights and PRIDE acquisitions compared with the depositors’ mzML conversions, and from rainbow’s public documentation pages for the binary files (rainbow, LGPL-3.0, run as a reference reader). Spectra are also checked against ProteoWizard conversions, made with Waters’ own library, of acquisitions from ProteoWizard’s test data (crates/openreadout-corpus-tests/tests/mz_agreement.rs). See docs/provenance/waters-raw.md. Format id: waters-raw; crate openreadout-waters. Confidence (computed by the evidence rubric, docs/assurance.md): high.

A MassLynx acquisition is a directory ending in .raw. Detection: a directory holding _HEADER.TXT or a _FUNCnnn.IDX (definite with the .raw extension, likely without).

Text files

  • _HEADER.TXT: lines $$ Key: value (parse_header_txt). Mapped into extra (traces and spectra[0]): Acquired Name → sample_name, Sample Description → description, SampleID → sample_id, User Name → operator, Instrument → instrument (XEVO-TQXS#WBA0260; the part before # is the model, the part after the serial unless NotSet), Job Code → job_code, Bottle Number → vial, MS Method → method, Inlet Method → inlet_method, Tune Method → tune_method, Version → header_version (also format_version); Acquired Date + Acquired Time (16-Jun-2021, 22:01:20) → acquired_at (header_datetime).
  • Cal Function n: c0,c1,…,Tk lines (Calibration, coefficients, kind, parse, apply, is_identity): the m/z calibration of function n. T0 (CalibrationKind::Linear): m = Σ cᵢ mᵢ with m the stored mass (rainbow’s pages). T1 (CalibrationKind::SquareRoot): √m = Σ cᵢ (√stored)ⁱ — inferred: bit-exact against the MTBLS7290 export after rounding to single precision. Other Cal … lines are kept verbatim in info --view full.
  • _extern.inf (parse_extern, ExternInfo, ExternFunction): Function Parameters - Function N - TYPE sections give each function’s type (kind: TOF MS FUNCTION, TOF MSMS FUNCTION, REFERENCE, …), Data Format (data_format) and its other key<TAB>value lines (parameters); Instrument Parameters - Function N: sections (MRM files) and a Polarity ES+/ES- line give polarity per function, or for the whole acquisition (ExternInfo::polarity) when it appears outside any function section; Created by Masslynx v4.1 → software_version; Lock Mass → lock_mass. Maps: functions.
  • _INLET.INF: inlet (LC) method text; copied into info --view full.

Binary files

file layout (little-endian) source
_FUNCnnn.IDX one record per scan (ScanIndex, parse_idx, idx_record_len, idx_record_len_for): u32 byte offset of the scan in _FUNCnnn.DAT (offset); u32 whose low 22 bits are the number of stored values (count) and high 10 bits a flag field (flags: 32 in the MRM files and MTBLS7290, 288 in PXD059722); f32 at +8 = the scan’s stored total ion current (stored_tic); f32 at +12 = retention time in minutes (rt_min); 6 bytes not interpreted. 22-byte records (IDX_RECORD) normally; 30-byte records (IDX_RECORD_WIDE): the u32 offset is then 0 and a u64 at +22 holds the offset. The record length is the one whose records tile the file and whose offsets step by count × bytes per value through the whole DAT (idx_record_len_for); 30-byte records occur with flags 0x120 (bit 0x100, FLAG_WIDE_CALIBRATED) and 0x60 (a continuum SYNAPT G2-Si file), so the flag decides only when both lengths fit offset/count/time: rainbow docs; TIC, 30-byte records: inferred
_FUNCnnn.DAT, 12-byte values per value: u32 intensity: 22-bit mantissa × 2^(e − 21) with e the low 6 bits of the top 10 (decode_intensity12); bits 6 and 7 of that 10-bit field are point flags (value12_flags): 0x40 (FLAG_LOCK_MASS_PEAK) marks the lock-mass peak of each lock-spray reference scan, 0x80 a few analyte peaks (meaning unknown); u32 mass word with a 5-bit exponent (top bits) and 27-bit mantissa: stored mass = mantissa × 2^(exponent − 27) (decode_mass27, decode_value12); a third u32 not interpreted. Centroids, ascending in m/z inferred; validated bit for bit (below)
_FUNCnnn.DAT, 8-byte values from the most significant bit: 5 bits x, a 31-bit fixed-point mass with x integer bits; 6 bits y, one bit not interpreted, 21 bits intensity × 2^(y − 21) (decode_value8): continuum (profile) and SQD scans rainbow docs; validated on 7 files (MSe, continuum DDA, drift-summed HD data, SQD)
_FUNCnnn.DAT, 6-byte values 48 bits: 23-bit mass base, 5-bit mass power (mass = base × 2^(power − 23)), 4-bit intensity power, signed 16-bit intensity base (intensity = base × 4^power) (decode_value6): quadrupole product-ion scans, and (wavelength nm, absorbance count) in photodiode-array functions rainbow docs; validated on the Xevo TQ-MS product-ion scans and the SQD PDA function
_FUNCnnn.DAT, 4-byte values one u32 per MRM transition: low 22 bits mantissa, high 10 bits exponent, value = mantissa × 2^(exponent − 21) (decode_packed32) inferred: every scan’s values sum to the stored TIC (2,561 scans); rainbow’s output is exactly twice these values
_FUNCnnn.DAT, 2-byte values one u16 per MRM transition or SIR mass: base in the high 13 bits × 4^(low 3 bits) (decode_packed16) rainbow docs; validated: all 16,548 values of MTBLS225 equal the depositor export
_FUNCTNS.INF 416-byte blocks (FUNCTION_BLOCK, FunctionBlock, parse_functions), one per function: u16 code at 0 (code; its low 5 bits the function type, function_type: FUNCTION_TOF_MS 0x12, FUNCTION_TOF_MSMS 0x10, FUNCTION_DAUGHTER 0x06 (quadrupole product-ion scan), FUNCTION_MRM 0x09, FUNCTION_PDA 0x0C, 0x00 quadrupole full scan; bit 0x20 set in negative-ion functions; bit 0x8000 the lock-spray reference function, is_reference_code); f32 at 0x18 (set_mass): a product-ion scan’s precursor; f32 start and end time in minutes at 10 and 14 (start_min, end_min); up to 32 f32 at 0xA0 (set_mz: MRM precursors / SIR masses, or the start mass of a scanning function) and 32 at 0x120 (second_mz: MRM products, or the end mass of a scanning function) 0xA0: rainbow docs; the rest inferred (scan windows equal the exports’)
_FUNCnnn.STS per-scan statistics, self-describing (StatsLayout, parse_stats_layout, header_len, record_len, fields, record_count, field, value): u16 header length, u16 (1), u16 record length, u16 field count; from byte 32 (STATS_PREFIX) one 48-byte descriptor per field (STATS_FIELD, StatField: u16 id, u16 kind — 0 byte, 1 i16, 2 i32, 3 f32 — u16 offset in the record, NUL-terminated name); then one record per scan. The fields named Set Mass (MS/MS precursor; descriptor id 77, STAT_SET_MASS, field_by_id, which is also the only, unnamed, field of files the MassLynx SDK writes), Collision Energy, Collision Energy2 and Cone are read inferred (self-describing; Set Mass equals the export’s precursor)
_CHROnnn.DAT 0x80-byte header (CHRO_HEADER) holding the axis labels, then (f32 time in minutes, f32 value) pairs rainbow docs
_CHROMS.INF u16 header length (0x80), u16 channel count, u16 record length; per channel: 4 bytes, the NUL-terminated description, $CC$,1.000000,3,0,0,bar whose last field is the unit (parse_chroms) inferred
_funcNNN.ind drift index (DriftIndex, parse_drift_index): a 36-byte header (DRIFT_INDEX_HEADER; u32 at 4 = drift bins per scan, bins, at most MAX_DRIFT_BINS), then per scan (DriftScan) three u32 byte lengths of the scan’s sections in the .cdt (sections: positions, intensities, point flags) and five arrays of one u32 per bin: the bytes of long-step records (long_steps), unknown (zero, except in the lock-spray function of a SYNAPT XS SONAR run, where two bins per scan hold multiples of 8), the retention time in seconds as f32 (rt_s), the number of points (points), unknown (zero; either unknown array non-zero sets unknown_nonzero). The scans tile the .cdt in order (offset, byte_len, point_count); bytes after the last whole block are trailing inferred; validated (below)
_funcNNN.cdt per scan: the position section, the long-step records, the intensity section, the flag section. Each section is one LZRW3 block (lzrw3_decompress; a public-domain algorithm: u32 flag 0 or 1 for a stored block, then 16-bit control words, lowest bit first, for 16 items each; a literal byte or a two-byte copy item whose first byte’s low nibble is the length − 3 and whose other 12 bits index a table of earlier item starts hashed from their first three bytes, lzrw3_hash, LZRW3_START). Decompressed (decode_drift_scan, DriftBin): positions are one u16 per point, a bin’s first time-of-flight index and then the step from the previous point (tof); a long-step record (u32 point number within the bin, u32 step) replaces a step that does not fit 16 bits; intensities are one i16 per point, the bin’s first intensity and then differences (intensity); the flag section is one byte per point, not interpreted. The .DAT of such a function holds the drift-summed spectrum: its non-zero points are the bins’ points summed at each time-of-flight index, in the same order, so each index takes the m/z of the DAT point of the same rank inferred; validated: 2,000 drift-bin spectra of four acquisitions equal the vendor library’s conversions point for point
.EE, .CMP, _history.inf not interpreted; listed by info --view structure –

The bytes per value of a function are inferred as DAT length / Σ counts (bytes_per_value).

Calibration

A scanning function’s stored masses are calibrated with its Cal Function n line unless the index flag 0x100 is set: PXD059722 (centroided after acquisition, _history.inf present) stores masses equal to its export’s m/z bit for bit, while applying its Cal Function would move them by 1e-4. The calibrated 12-byte masses are rounded to single precision (all 132,053 MTBLS7290 export m/z are f32 values and match exactly that way); 6- and 8-byte masses keep double precision.

Mapping

  • spectra[0] (only when a function holds 12-, 8- or 6-byte values and is not a PDA/UV function, is_spectral): every scan of every scanning function, merged by retention time (ties by function number), as the exports list them. native_id function=F process=0 scan=S (S counted per function from 1); scan_number = S; ms_level from the block’s function type (0x10 TOF MS/MS and 0x06 product-ion scans are 2; an MSe high-energy TOF MS function — its _extern.inf section, subsections included, ramps a high collision energy (high_energy) — is 2 with isolation_window_mz = the scan window and precursor_mz its centre, extra.mse_high_energy), falling back to the _extern.inf type text (MSMS → 2); the lock-spray reference function is MS1 with extra.lock_mass_reference: true and each scan’s flagged lock-mass peak in extra.lock_mass_peak_mz; drift-resolved functions (drift_resolved) say extra.drift_bins; centroided for the 12-byte layout; precursor_mz = STS Set Mass (TOF MS/MS) or the block’s set mass (product-ion scans); collision_energy = STS Collision Energy (MS/MS only); activation HCD (beam-type CID, as the exports record for Waters TOF cells); scan_window_mz = the function block’s start/end mass; total_ion_current = the sum of the decoded intensities; extra: function, function_kind, stored_tic, calibration, cone_v, collision_energy2. Run extra: functions (per scanning function: number, kind, MS level, scans, bytes per value, lock_mass_reference, scan window), polarities, lock_mass, instrument_serial, stored_spectra, method_summary.
  • tables[]: one per function (FUNCnnn): columns rt_min, tic_stored, then one per MRM transition named precursor > product (583.4 > 209.2, shortest f32 text) or SIR mass, dtype uint32/uint16 (the packed storage word), unit counts; extra.function, polarity, bytes_per_value, function_kind.
  • traces[]: the functions whose scan times are evenly spaced within 1 % (channels TIC (stored) + transitions), one trace per photodiode-array function (PDA (FUNCnnn): time in s, then one channel per wavelength with extra.wavelength_nm, the stored signed absorbance counts), one trace per analog channel (_CHROnnn.DAT, e.g. System Pressure in bar) when its times are evenly spaced, then — when there are spectra — TIC (the stored TIC of every spectrum) and BPC (the most intense decoded value of every spectrum), both irregularly sampled (channels time in s, intensity).
  • spectra[1] (only when a scanning function has a _funcNNN.cdt and a readable _funcNNN.ind), named drift bins: every drift-resolved scan of run 0, in the same order, split into its bins, empty bins included. Spectrum k of a function’s scan S and bin B has scan_number and native id scan (S − 1) × bins + B + 1 (function=F process=0 scan=…, the vendor library’s numbering), the run-0 scan’s metadata, extra.scan = S and either extra.drift_bin = B with extra.drift_time_ms = B × ADC Pushes Per IMS Increment (pushes_per_drift_bin) × 1000 / the scan’s Pusher Frequency statistic (Hz), or, in a SONAR acquisition (a function section says UseSONARMode TRUE, sonar), extra.sonar_bin = B and no drift time. Points: the bin’s non-zero points (profile). A scan whose bins do not decompress, or do not sum to its stored drift-summed spectrum, is refused (exit 6) and its run-0 spectrum stays readable. Run extra: drift_resolved (ion mobility drift time or SONAR quadrupole steps), functions (number, kind, MS level, scans, bins_per_scan).
  • find_spectrum resolves a scan number in the lowest-numbered scanning function (run 1: the per-bin number in the lowest-numbered drift-resolved function).

check finding codes

truncated (IDX not whole records, DAT shorter than the index needs, CHRO pairs incomplete, a drift index with a partial block), missing_file, undecodable (a spectrum that fails to decode), drift_undecodable (the first or last drift-resolved scan of a function does not decode, or its bins do not sum to the stored spectrum) (errors); missing_header, bad_functions_inf, function_count_mismatch, time_not_monotonic, tic_mismatch, statistics_count_mismatch (warnings).

Lock-mass correction

Off by default: m/z are as stored (calibrated with the Cal Function lines). set_lock_mass (CLI spectrum/chromatogram --lock-mass MZ|auto) corrects them with the lock-spray REFERENCE function: in each of its scans the lock peak is measured (measure_lock_peak: the point flagged 0x40 when there is one; else, of the local maxima within 500 ppm of the reference and at least a tenth of the largest there, the one nearest the reference, as the intensity-weighted centroid of the points above half its height), a scan without it is skipped, and every m/z of every scan is multiplied by the mean of reference / measured over the lock-spray scans within 60 s of it, or the nearest one’s when none is that close (LockCorrection::factor). The reference is the given m/z, or with auto the Lock Mass of _extern.inf. Each corrected spectrum carries extra.lock_mass_correction (reference_mz, factor, ppm, rule). Drift-bin spectra (run 1) and precursor m/z are not corrected.

Evidence (docs/provenance/waters-raw.md, 2026-10-12): MassLynx’s corrected copies multiply every m/z of a scan by one factor; against them our corrected profile peaks lie 1.2 and 1.9 ppm (medians) from MassLynx’s centroids in the ProteoWizard SYNAPT G2-Si pair (corpus test waters_lock_mass), and −0.6 ppm (per-scan RMS 1.2 ppm) in a Xevo G2-XS run from MassIVE MSV000098857 that was 140.7 ppm off uncorrected. How MassLynx smooths the lock-spray measurements is not established; within these runs averaging rules differ by less than the 1–2 ppm by which our centroids differ from MassLynx’s.

Vocabulary (every public identifier in crates/openreadout-waters must appear here)

identifier meaning
WatersRawReader, WatersRawDataset, WATERS_ID, is_waters_dir, is_waters_dir_in, open, open_input, functions format reader, opened directory, the id waters-raw, directory test (on the local disk, or in a byte-source namespace), open (a local path, or an input held in memory or by the host), the functions of an opened directory
IDX_RECORD, IDX_RECORD_WIDE, FLAG_WIDE_CALIBRATED, FUNCTION_BLOCK, CHRO_HEADER, STATS_PREFIX, STATS_FIELD record/block/header sizes (22, 30, 416, 0x80, 32, 48 bytes) and the index flag bit 0x100
le_u16, le_i16, le_u32, le_i32, le_u64, le_f32 bounds-checked little-endian readers
ScanIndex, offset, count, flags, stored_tic, rt_min, parse_idx, idx_record_len one _FUNCnnn.IDX record, its parser and the record-length test
decode_packed32, decode_packed16, decode_mass27, decode_value12, decode_value8, decode_value6 DAT value decoders
FunctionBlock, code, start_min, end_min, set_mz, second_mz, parse_functions one _FUNCTNS.INF block and its parser
parse_header_txt, header_datetime $$ Key: value lines; date + time → ISO-8601
Calibration, CalibrationKind, Linear, SquareRoot, coefficients, kind, parse, apply, is_identity a Cal Function n line: coefficients and form (T0, T1)
StatsLayout, StatField, header_len, record_len, fields, id, name, record_count, field, value, parse_stats_layout the self-describing .STS layout
ExternInfo, ExternFunction, parse_extern, polarity, data_format, parameters, software_version, lock_mass what _extern.inf says, per function and for the acquisition
parse_chroms _CHROMS.INF channel descriptions
AnalogChannel, number, file, description, unit, conversion, points, trailing an analog channel: its number, DAT file, _CHROMS.INF description, unit, $CC$ string, (time, value) pairs, leftover bytes
decode_intensity12, value12_flags, FLAG_LOCK_MASS_PEAK 12-byte intensity word without its flag bits; the flags; the lock-mass-peak flag (0x40)
function_type, is_reference_code, set_mass, FUNCTION_TOF_MS, FUNCTION_TOF_MSMS, FUNCTION_DAUGHTER, FUNCTION_MRM, FUNCTION_PDA function block type (low 5 bits of the code) and its values, reference bit, product-ion precursor
field_by_id, STAT_SET_MASS .STS field by descriptor id; id 77 = Set Mass
WatersFunction, scans, idx_len, idx_record_len, dat_len, bytes_per_value, block, calibration, stats_layout, stats, high_energy, drift_resolved, drift one function: scan index, file sizes, index record length, value width, function block, polarity, kind, data format, calibration, statistics layout and bytes, drift index and .cdt name
pushes_per_drift_bin, sonar ADC Pushes Per IMS Increment; an acquisition with UseSONARMode TRUE
DRIFT_INDEX_HEADER, MAX_DRIFT_BINS, DriftIndex, DriftScan, bins, scans, trailing, offset, sections, long_steps, points, rt_s, unknown_nonzero, byte_len, point_count, parse_drift_index the drift index (_funcNNN.ind) and one scan’s entry
LZRW3_START, lzrw3_hash, lzrw3_decompress the LZRW3 block decoder of the .cdt sections
DriftBin, tof, intensity, decode_drift_scan one decoded drift bin: time-of-flight indices and intensities

How this reader was derived, file by file: provenance log.