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 intoextra(traces andspectra[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 unlessNotSet),Job Code→job_code,Bottle Number→vial,MS Method→method,Inlet Method→inlet_method,Tune Method→tune_method,Version→header_version(alsoformat_version);Acquired Date+Acquired Time(16-Jun-2021,22:01:20) →acquired_at(header_datetime).Cal Function n: c0,c1,…,Tklines (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. OtherCal …lines are kept verbatim ininfo --view full._extern.inf(parse_extern,ExternInfo,ExternFunction):Function Parameters - Function N - TYPEsections give each function’s type (kind:TOF MS FUNCTION,TOF MSMS FUNCTION,REFERENCE, …),Data Format(data_format) and its otherkey<TAB>valuelines (parameters);Instrument Parameters - Function N:sections (MRM files) and aPolarity ES+/ES-line givepolarityper 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 intoinfo --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_idfunction=F process=0 scan=S(S counted per function from 1);scan_number= S;ms_levelfrom 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.infsection, subsections included, ramps a high collision energy (high_energy) — is 2 withisolation_window_mz= the scan window andprecursor_mzits centre,extra.mse_high_energy), falling back to the_extern.inftype text (MSMS→ 2); the lock-spray reference function is MS1 withextra.lock_mass_reference: trueand each scan’s flagged lock-mass peak inextra.lock_mass_peak_mz; drift-resolved functions (drift_resolved) sayextra.drift_bins;centroidedfor the 12-byte layout;precursor_mz= STSSet Mass(TOF MS/MS) or the block’s set mass (product-ion scans);collision_energy= STSCollision Energy(MS/MS only);activationHCD(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. Runextra: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): columnsrt_min,tic_stored, then one per MRM transition namedprecursor > product(583.4 > 209.2, shortest f32 text) or SIR mass, dtypeuint32/uint16(the packed storage word), unitcounts;extra.function,polarity,bytes_per_value,function_kind.traces[]: the functions whose scan times are evenly spaced within 1 % (channelsTIC (stored)+ transitions), one trace per photodiode-array function (PDA (FUNCnnn):timein s, then one channel per wavelength withextra.wavelength_nm, the stored signed absorbance counts), one trace per analog channel (_CHROnnn.DAT, e.g.System Pressureinbar) when its times are evenly spaced, then — when there are spectra —TIC(the stored TIC of every spectrum) andBPC(the most intense decoded value of every spectrum), both irregularly sampled (channelstimein s,intensity).spectra[1](only when a scanning function has a_funcNNN.cdtand a readable_funcNNN.ind), nameddrift 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 hasscan_numberand 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 eitherextra.drift_bin= B withextra.drift_time_ms= B ×ADC Pushes Per IMS Increment(pushes_per_drift_bin) × 1000 / the scan’sPusher Frequencystatistic (Hz), or, in a SONAR acquisition (a function section saysUseSONARMode 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 timeorSONAR quadrupole steps),functions(number, kind, MS level, scans,bins_per_scan).find_spectrumresolves 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.