Skip to main content

openreadout_mzml/
lib.rs

1//! Readers for the open mass-spectrometry exchange formats mzML 1.1 (HUPO-PSI) and
2//! mzXML 2.x/3.x (ISB).
3//!
4//! Both are XML with base64 binary arrays; files run to many gigabytes, so nothing is loaded
5//! whole: the trailing offset index (`indexedmzML`, mzXML `index`) is read and spot-checked at
6//! open, and each spectrum is parsed from its byte offset on demand. Without a usable index
7//! the file is scanned once to locate every spectrum. Layout and vocabulary:
8//! `docs/formats/mzml.md`. Provenance: `docs/provenance/mzml.md`.
9//!
10//! # Example
11//!
12//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
13//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
14//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
15//! access.
16//!
17//! ```
18//! use openreadout_core::FormatReader;
19//! use openreadout_mzml::MzmlReader;
20//!
21//! let format = MzmlReader.descriptor();
22//! assert_eq!(format.id, openreadout_mzml::MZML_FORMAT_ID);
23//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
24//! ```
25//!
26//! Reading a file:
27//!
28//! ```no_run
29//! use std::path::Path;
30//!
31//! use openreadout_core::FormatReader;
32//! use openreadout_mzml::MzmlReader;
33//!
34//! let mut dataset = MzmlReader.open(Path::new("run.mzML"))?;
35//! let info = dataset.info()?; // headers only
36//! let run = &info.spectra[0];
37//! println!("{} spectra, MS levels {:?}", run.scan_count, run.ms_levels);
38//! // Spectrum 0 of run 0: parallel m/z and intensity arrays.
39//! let spectrum = dataset.read_spectrum(0, 0)?;
40//! println!("MS{} at {:?} s: {} points", spectrum.ms_level, spectrum.rt_s, spectrum.mz.len());
41//! # Ok::<(), openreadout_core::Error>(())
42//! ```
43//!
44//! Applications that accept any instrument file usually register every reader in an
45//! [`openreadout_core::Registry`] and let it detect the format; that is what the
46//! `openreadout` command-line tool does.
47//!
48//! # API stability
49//!
50//! The supported API is what this page documents. The parser modules are public only so that
51//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
52//! in any release.
53#![forbid(unsafe_code)]
54#![warn(missing_docs)]
55
56mod assurance;
57#[doc(hidden)]
58pub mod binary;
59mod cv;
60mod experiment;
61#[doc(hidden)]
62pub mod gz;
63#[doc(hidden)]
64pub mod mzml;
65#[doc(hidden)]
66pub mod mzmlb;
67#[doc(hidden)]
68pub mod mzxml;
69#[doc(hidden)]
70pub mod numpress;
71mod scan;
72mod xml;
73
74use std::path::Path;
75
76use openreadout_core::Result;
77use openreadout_core::model::{DetectConfidence, FormatDescriptor};
78use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
79use openreadout_core::source::Input;
80
81#[doc(hidden)]
82pub use binary::{
83    ArrayEncoding, ArrayError, Compression, Outer, ValueType, decode_array, decode_base64,
84    decode_values,
85};
86#[doc(hidden)]
87pub use mzml::MzmlDataset;
88#[doc(hidden)]
89pub use mzxml::{MzxmlDataset, parse_duration};
90#[doc(hidden)]
91pub use numpress::{NumpressError, decode_linear, decode_pic, decode_slof};
92
93/// Format id of mzML on the command line and in JSON.
94pub const MZML_FORMAT_ID: &str = mzml::FMT;
95/// Format id of imzML on the command line and in JSON.
96pub const IMZML_FORMAT_ID: &str = "imzml";
97/// Format id of mzXML on the command line and in JSON.
98pub const MZXML_FORMAT_ID: &str = mzxml::FMT;
99
100/// Does the head of the file look like the XML root `root` (after the prolog)?
101fn root_is(head: &[u8], roots: &[&str]) -> bool {
102    let text = String::from_utf8_lossy(&head[..head.len().min(8192)]);
103    let mut rest = text.trim_start_matches('\u{feff}');
104    // skip the XML declaration, processing instructions and comments
105    loop {
106        rest = rest.trim_start();
107        if let Some(r) = rest.strip_prefix("<?") {
108            match r.find("?>") {
109                Some(i) => rest = &r[i + 2..],
110                None => return false,
111            }
112        } else if let Some(r) = rest.strip_prefix("<!--") {
113            match r.find("-->") {
114                Some(i) => rest = &r[i + 3..],
115                None => return false,
116            }
117        } else {
118            break;
119        }
120    }
121    let Some(tag) = rest.strip_prefix('<') else {
122        return false;
123    };
124    let name: String = tag
125        .chars()
126        .take_while(|c| !c.is_whitespace() && *c != '>' && *c != '/')
127        .collect();
128    let local = name.rsplit(':').next().unwrap_or(&name);
129    roots.contains(&local)
130}
131
132/// Detection of a gzip-compressed file from its decompressed head `inner`: definite when the
133/// document root matches, extension-only when only the name (`.<ext>.gz`) does.
134fn sniff_gz(
135    inner: &[u8],
136    path: &Path,
137    roots: &[&str],
138    ext: &str,
139    format_id: &'static str,
140) -> Option<Detection> {
141    if root_is(inner, roots) {
142        return Some(Detection {
143            format_id,
144            confidence: DetectConfidence::Definite,
145            note: Some("gzip-compressed".into()),
146        });
147    }
148    if gz::has_gz_extension(path, ext) {
149        return Some(Detection {
150            format_id,
151            confidence: DetectConfidence::ExtensionOnly,
152            note: Some(format!(
153                "gzip-compressed .{ext}.gz, but the decompressed start is not the expected root element"
154            )),
155        });
156    }
157    None
158}
159
160/// The mzML reader.
161#[derive(Debug, Default, Clone, Copy)]
162pub struct MzmlReader;
163
164impl FormatReader for MzmlReader {
165    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
166        Some(&assurance::MZML)
167    }
168
169    fn descriptor(&self) -> FormatDescriptor {
170        mzml::descriptor()
171    }
172
173    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
174        if has_extension(path, &["imzml"]) {
175            return None; // the imzML reader's
176        }
177        if let Some(inner) = gz::peek(head) {
178            return sniff_gz(
179                &inner,
180                path,
181                &["mzML", "indexedmzML"],
182                "mzml",
183                MZML_FORMAT_ID,
184            );
185        }
186        if root_is(head, &["mzML", "indexedmzML"]) {
187            return Some(Detection {
188                format_id: MZML_FORMAT_ID,
189                confidence: DetectConfidence::Definite,
190                note: None,
191            });
192        }
193        if has_extension(path, &["mzml"]) && !head.is_empty() {
194            return Some(Detection {
195                format_id: MZML_FORMAT_ID,
196                confidence: DetectConfidence::ExtensionOnly,
197                note: Some(
198                    "mzML extension but the root element is not <mzML>/<indexedmzML>".into(),
199                ),
200            });
201        }
202        None
203    }
204
205    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
206        self.open_input(&Input::local(path))
207    }
208
209    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
210        if gz::input_is_gzip(input) {
211            return gz::open_gz(input, MZML_FORMAT_ID, |fs, p| {
212                Ok(Box::new(MzmlDataset::open_in(fs, p)?))
213            });
214        }
215        Ok(Box::new(MzmlDataset::open_in(input.fs(), input.path())?))
216    }
217
218    fn reads_any_source(&self) -> bool {
219        true
220    }
221}
222
223/// The imzML reader (mass spectrometry imaging: mzML metadata, arrays in a `.ibd` file).
224#[derive(Debug, Default, Clone, Copy)]
225pub struct ImzmlReader;
226
227impl FormatReader for ImzmlReader {
228    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
229        Some(&assurance::IMZML)
230    }
231
232    fn descriptor(&self) -> FormatDescriptor {
233        mzml::imzml_descriptor()
234    }
235
236    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
237        if !has_extension(path, &["imzml"]) || head.is_empty() {
238            return None;
239        }
240        Some(Detection {
241            format_id: IMZML_FORMAT_ID,
242            confidence: if root_is(head, &["mzML", "indexedmzML"]) {
243                DetectConfidence::Definite
244            } else {
245                DetectConfidence::ExtensionOnly
246            },
247            note: None,
248        })
249    }
250
251    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
252        self.open_input(&Input::local(path))
253    }
254
255    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
256        Ok(Box::new(MzmlDataset::open_imzml_in(
257            input.fs(),
258            input.path(),
259        )?))
260    }
261
262    fn reads_any_source(&self) -> bool {
263        true
264    }
265}
266
267/// The mzXML reader.
268#[derive(Debug, Default, Clone, Copy)]
269pub struct MzxmlReader;
270
271impl FormatReader for MzxmlReader {
272    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
273        Some(&assurance::MZXML)
274    }
275
276    fn descriptor(&self) -> FormatDescriptor {
277        mzxml::descriptor()
278    }
279
280    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
281        if let Some(inner) = gz::peek(head) {
282            return sniff_gz(&inner, path, &["mzXML"], "mzxml", MZXML_FORMAT_ID);
283        }
284        if root_is(head, &["mzXML"]) {
285            return Some(Detection {
286                format_id: MZXML_FORMAT_ID,
287                confidence: DetectConfidence::Definite,
288                note: None,
289            });
290        }
291        if has_extension(path, &["mzxml"]) && !head.is_empty() {
292            return Some(Detection {
293                format_id: MZXML_FORMAT_ID,
294                confidence: DetectConfidence::ExtensionOnly,
295                note: Some("mzXML extension but the root element is not <mzXML>".into()),
296            });
297        }
298        None
299    }
300
301    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
302        self.open_input(&Input::local(path))
303    }
304
305    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
306        if gz::input_is_gzip(input) {
307            return gz::open_gz(input, MZXML_FORMAT_ID, |fs, p| {
308                Ok(Box::new(MzxmlDataset::open_in(fs, p)?))
309            });
310        }
311        Ok(Box::new(MzxmlDataset::open_in(input.fs(), input.path())?))
312    }
313
314    fn reads_any_source(&self) -> bool {
315        true
316    }
317}
318
319/// Format id of mzMLb on the command line and in JSON.
320pub const MZMLB_FORMAT_ID: &str = mzmlb::FMT;
321
322/// The mzMLb reader (mzML with its arrays in HDF5 datasets).
323#[derive(Debug, Default, Clone, Copy)]
324pub struct MzmlbReader;
325
326impl FormatReader for MzmlbReader {
327    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
328        Some(&assurance::MZMLB)
329    }
330
331    fn descriptor(&self) -> FormatDescriptor {
332        mzmlb::descriptor()
333    }
334
335    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
336        let named = mzmlb::sniff(head, path)?;
337        Some(Detection {
338            format_id: MZMLB_FORMAT_ID,
339            confidence: DetectConfidence::Definite,
340            note: (!named).then(|| {
341                "HDF5 file named .mzMLb; mzMLb dataset names not seen in the first 64 KiB".into()
342            }),
343        })
344    }
345
346    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
347        self.open_input(&Input::local(path))
348    }
349
350    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
351        let size_bytes = input.metadata()?.len();
352        let (ds, container) = mzmlb::open(input)?;
353        Ok(Box::new(gz::ContainerDataset {
354            inner: Box::new(ds),
355            path: input.path().to_path_buf(),
356            size_bytes,
357            format: Some(mzmlb::descriptor()),
358            key: "container",
359            facts: container.facts,
360            notes: vec![
361                "mzMLb: the mzML document is the HDF5 dataset `mzML`; its binary arrays are slices of HDF5 datasets (byte offsets in this output refer to the `mzML` dataset)".into(),
362            ],
363            performed: vec![
364                "opened the HDF5 container and read the mzML document and the index from its datasets".into(),
365            ],
366            findings: Vec::new(),
367        }))
368    }
369
370    fn reads_any_source(&self) -> bool {
371        true
372    }
373}
374
375#[cfg(test)]
376mod tests {
377    use super::root_is;
378
379    #[test]
380    fn sniff_roots() {
381        assert!(root_is(
382            b"<?xml version=\"1.0\"?>\n<indexedmzML xmlns=\"x\">",
383            &["mzML", "indexedmzML"]
384        ));
385        assert!(root_is(b"\xef\xbb\xbf<mzML>", &["mzML"]));
386        assert!(root_is(b"<!-- c --><mzXML a='1'>", &["mzXML"]));
387        assert!(!root_is(b"<html>", &["mzML"]));
388        assert!(!root_is(b"", &["mzML"]));
389    }
390}