Skip to main content

openreadout_thermo/
lib.rs

1//! Clean-room reader for Thermo Fisher `.raw` mass-spectrometry files.
2//!
3//! Derived from public corpus files (MetaboLights, PRIDE) compared against the depositors' own
4//! mzML/mzXML conversions, plus the permissively licensed or public format notes listed in
5//! `docs/provenance/thermo-raw.md`. No vendor library is used, linked or consulted.
6//!
7//! Layout and vocabulary: `docs/formats/thermo-raw.md`.
8//!
9//! # Example
10//!
11//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
12//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
13//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
14//! access.
15//!
16//! ```
17//! use openreadout_core::FormatReader;
18//! use openreadout_thermo::ThermoRawReader;
19//!
20//! let format = ThermoRawReader.descriptor();
21//! assert_eq!(format.id, openreadout_thermo::FORMAT_ID);
22//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
23//! ```
24//!
25//! Reading a file:
26//!
27//! ```no_run
28//! use std::path::Path;
29//!
30//! use openreadout_core::FormatReader;
31//! use openreadout_thermo::ThermoRawReader;
32//!
33//! let mut dataset = ThermoRawReader.open(Path::new("run.raw"))?;
34//! let info = dataset.info()?; // headers only
35//! let run = &info.spectra[0];
36//! println!("{} spectra, MS levels {:?}", run.scan_count, run.ms_levels);
37//! // Spectrum 0 of run 0: parallel m/z and intensity arrays.
38//! let spectrum = dataset.read_spectrum(0, 0)?;
39//! println!("MS{} at {:?} s: {} points", spectrum.ms_level, spectrum.rt_s, spectrum.mz.len());
40//! # Ok::<(), openreadout_core::Error>(())
41//! ```
42//!
43//! Applications that accept any instrument file usually register every reader in an
44//! [`openreadout_core::Registry`] and let it detect the format; that is what the
45//! `openreadout` command-line tool does.
46//!
47//! # API stability
48//!
49//! The supported API is what this page documents. The parser modules are public only so that
50//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
51//! in any release.
52#![forbid(unsafe_code)]
53#![warn(missing_docs)]
54
55mod assurance;
56#[doc(hidden)]
57pub mod bytes;
58#[doc(hidden)]
59pub mod dataset;
60#[doc(hidden)]
61pub mod detectors;
62#[doc(hidden)]
63pub mod event;
64mod gradient;
65#[doc(hidden)]
66pub mod layout;
67#[doc(hidden)]
68pub mod packet;
69
70use std::path::Path;
71
72use openreadout_core::Result;
73use openreadout_core::model::{DetectConfidence, FormatDescriptor};
74use openreadout_core::reader::{Dataset, Detection, FormatReader};
75use openreadout_core::source::Input;
76
77#[doc(hidden)]
78pub use bytes::adler32;
79#[doc(hidden)]
80pub use dataset::{MethodDocument, ScanSummary, ThermoDataset};
81#[doc(hidden)]
82pub use event::{Activation, Analyzer, Ionization, Polarity};
83#[doc(hidden)]
84pub use layout::{
85    AuditStamp, AutosamplerInfo, CHECKSUM_OFFSET, CHECKSUM_SPAN, ControllerRef, ErrorLogEntry,
86    FILE_HEADER_LEN, FileHeader, FileInfoBlock, GenericField, GenericHeader, InjectionRecord,
87    InstrumentId, MethodTable, Reaction, RunHeader, SUPPORTED_VERSIONS, ScanEvent, ScanIndexEntry,
88    ScanTemplate, SequenceRow, StreamAddresses,
89};
90#[doc(hidden)]
91pub use packet::{
92    AcquisitionWindow, Centroid, FLAG_EXCLUDED, MAX_PEAK_LIST_PEAKS, MAX_WINDOWS, MONOTONIC_NUDGE,
93    MzScale, PEAK_LIST_KIND, PEAK_LIST_PEAK_LEN, PROFILE_PAD_BINS, Packet, PacketHeader,
94    PeakDescriptor, Profile, ProfileChunk, WINDOW_LEN, WINDOW_PEAK_LEN, WINDOW_RECORD_KIND,
95    WindowRecord,
96};
97
98/// Format id used on the command line and in JSON.
99pub const FORMAT_ID: &str = "thermo-raw";
100
101/// First 18 bytes of every `.raw` file: `01 A1` then `Finnigan` in UTF-16LE.
102pub const SIGNATURE: [u8; 18] = [
103    0x01, 0xA1, b'F', 0, b'i', 0, b'n', 0, b'n', 0, b'i', 0, b'g', 0, b'a', 0, b'n', 0,
104];
105
106/// The Thermo `.raw` format reader.
107#[derive(Debug, Default, Clone, Copy)]
108pub struct ThermoRawReader;
109
110impl FormatReader for ThermoRawReader {
111    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
112        Some(&assurance::THERMO_RAW)
113    }
114
115    fn descriptor(&self) -> FormatDescriptor {
116        FormatDescriptor {
117            id: FORMAT_ID.into(),
118            name: "Thermo RAW".into(),
119            vendor: "Thermo Fisher Scientific".into(),
120            extensions: vec!["raw".into()],
121            family: "mass-spectrometry".into(),
122            can_read: true,
123            can_write: false,
124            confidence: assurance::THERMO_RAW.confidence,
125            known_gaps: vec![
126                "Validated file versions: 57, 60, 61, 62, 63, 64, 66 (current instruments, Orbitrap Astral and TSQ Altis Plus included, write 66); versions 58, 59 and 65 open with a note and may misparse (no public file of them with a conversion was found)".into(),
127                "Detector controllers (UV/DAD channels, PDA field, analog pressure/temperature/A-D) are traces. An Accela PDA file (v63) is validated against an independent conversion (GNPS/MassIVE msconvert mzML of MTBLS773): all 10,501 PDA spectra × 401 wavelengths and their times exact, channel A equal to its `UV 1` chromatogram (that conversion times it one 0.1 s sample later; our grid lines up with the PDA field). Analog channels (v66) are validated against the pump-pressure chromatograms of five depositor mzMLs (every exported point equal, bar in the file, pascal in the export); the Vanquish DAD/CAD (v66) by internal consistency only (DAD channels equal the PDA field at their wavelength; stored per-scan values equal the samples). Units are inferred (mAU; no unit is stored) or taken from the method text; file versions before 63 expose only the mass spectrometer".into(),
128                "SRM scans (TSQ Vantage window records, TSQ Altis Plus runs whose scans take their events from the method table) are validated through the depositors' chromatograms, rebuilt from our spectra; their per-peak flag bytes are not interpreted. GC full scans of a TSQ 9610 and of an ISQ single quadrupole are validated against spectra; LC triple-quadrupole full scans (Q1MS/Q3MS) have no corpus file".into(),
129                "Scan filter text covers analyzer (ITMS, FTMS, ASTMS), polarity, data kind, ionization, in-source CID (sid=), FAIMS compensation voltage (cv=), turbo and rapid scan rates (t, r), dependent flag, supplemental activation (sa), multiplexing (msx), scan type, MS level, precursors with activation (CID, HCD, ETD) and energy, MSn stages, and scan ranges (SRM product windows included); multi-range SIM scans list every range. No corpus file has in-source CID and FAIMS together, or FAIMS on an ion-trap scan with a rate token, so those orders are assumed and such files are unvalidated".into(),
130                "Ion-trap (m/z-grid) profiles are validated against vendor-library conversions (LTQ Velos, Orbitrap ion-trap MS2/MS3 of ProteoWizard's test data); four-coefficient ion-cyclotron profiles are validated at single precision on one LTQ FT Ultra file".into(),
131                "The embedded instrument-method container is read for its stream list and the per-device method text; binary method data and the tune block are not decoded".into(),
132                "Centroid lists keep the peaks the file flags as reference/background ions, as conversions with the current vendor library do; conversions made before October 2020 (ProteoWizard up to 3.0.20239) left them out, so their peak counts are lower".into(),
133                "Orbitrap Exploris and Astral packets end in a per-peak annotation block (isotope-cluster marks, inferred) that is skipped. Orbitrap Astral (Astral-analyzer DIA), Ascend, Eclipse, IQ-X, ID-X and Elite files are validated against their depositors' conversions; Stellar only on three scans of a test file, and no Astral Zoom, Exploris with FAIMS, TSQ Quantis or TSQ Altis (only an Altis Plus) file is in the corpus".into(),
134                "Precursor charge is what the file records (`Charge State`); ion-trap (LTQ) and triple-quadrupole SRM scans record none, so none is reported".into(),
135                "ITQ 900 GC ion-trap scans are bare peak lists (scan-index kind 15) whose events state no polarity, data kind or MS level: they are read as MS1 centroids, with polarity and scan type from the method text, and validated on one file (5,184 scans); other GC ion traps (PolarisQ, ITQ 700/1100) have no corpus file".into(),
136            ],
137        }
138    }
139
140    fn sniff(&self, head: &[u8], _path: &Path) -> Option<Detection> {
141        layout::has_signature(head).then_some(Detection {
142            format_id: FORMAT_ID,
143            confidence: DetectConfidence::Definite,
144            note: None,
145        })
146    }
147
148    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
149        Ok(Box::new(ThermoDataset::open(path)?))
150    }
151
152    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
153        Ok(Box::new(ThermoDataset::open_input(input)?))
154    }
155
156    fn reads_any_source(&self) -> bool {
157        true
158    }
159}