Skip to main content

openreadout_nmr/
lib.rs

1//! Readers for NMR data.
2//!
3//! - **Bruker TopSpin / XWIN-NMR experiment directories** (`bruker-nmr`): a directory `<expno>/`
4//!   with JCAMP-DX-style parameter files (`acqus`, `acqu2s`, …), the time-domain samples (`fid`
5//!   or `ser`) and processed spectra under `pdata/<procno>/`. Notes and vocabulary:
6//!   `docs/formats/bruker-nmr.md`; provenance: `docs/provenance/bruker-nmr.md`.
7//! - **Varian/Agilent VnmrJ data directories** (`varian-nmr`): a `<name>.fid/` directory with
8//!   the binary `fid` (file header, block headers, int16/int32/float32 samples) and the
9//!   `procpar` parameter text. Notes and vocabulary: `docs/formats/varian-nmr.md`; provenance:
10//!   `docs/provenance/varian-nmr.md`.
11//! - **JEOL Delta `.jdf` files** (`jeol-jdf`): a binary header, a parameter section and 1D or 2D
12//!   data sections. Notes and vocabulary: `docs/formats/jeol-jdf.md`; provenance:
13//!   `docs/provenance/jeol-jdf.md`.
14//! - **Magritek Spinsolve benchtop NMR experiment directories** (`magritek-spinsolve`):
15//!   `acqu.par`/`proc.par` parameter text and Prospa `.1d`/`.2d` data files (FID first). Notes
16//!   and vocabulary: `docs/formats/magritek-spinsolve.md`; provenance:
17//!   `docs/provenance/magritek-spinsolve.md`.
18//! - **JCAMP-DX** (`jcamp-dx`): the IUPAC text format for spectra (NMR, IR, UV-Vis, MS), with
19//!   ASDF-compressed tables, NTUPLES and compound (LINK) files. Notes and vocabulary:
20//!   `docs/formats/jcamp-dx.md`; provenance: `docs/provenance/jcamp-dx.md`.
21//!
22//! All five expose sampled data as core traces (`TraceInfo` / `Dataset::read_trace`).
23//!
24//! [`export_jcamp`] writes any evenly sampled trace (an NMR FID or spectrum, a JCAMP-DX
25//! spectrum, a chromatogram) as JCAMP-DX 5.01: `##XYDATA=(X++(Y..Y))` in DIFDUP (with Y-value
26//! checks) or AFFN, NTUPLES pages for complex or multi-sweep data. The file is re-read with the
27//! JCAMP-DX reader and verified before it is renamed into place.
28//!
29//! # Example
30//!
31//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
32//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
33//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
34//! access.
35//!
36//! ```
37//! use openreadout_core::FormatReader;
38//! use openreadout_nmr::BrukerReader;
39//!
40//! let format = BrukerReader.descriptor();
41//! assert_eq!(format.id, openreadout_nmr::BRUKER_FORMAT_ID);
42//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
43//! ```
44//!
45//! Reading a file:
46//!
47//! ```no_run
48//! use std::path::Path;
49//!
50//! use openreadout_core::FormatReader;
51//! use openreadout_nmr::BrukerReader;
52//!
53//! let mut dataset = BrukerReader.open(Path::new("experiment/1"))?;
54//! let info = dataset.info()?; // headers only
55//! let trace = &info.traces[0];
56//! println!("{} sweep(s) at {} Hz, {} channel(s)", trace.sweep_count, trace.sample_rate_hz, trace.channels.len());
57//! // The first 1000 samples of sweep 0, every channel, scaled to physical units.
58//! let samples = dataset.read_trace(0, 0, 0, 1000)?;
59//! for (channel, values) in trace.channels.iter().zip(&samples.channels) {
60//!     println!("{} ({}): {:?}", channel.name, channel.unit.as_deref().unwrap_or("?"), values.first());
61//! }
62//! # Ok::<(), openreadout_core::Error>(())
63//! ```
64//!
65//! Applications that accept any instrument file usually register every reader in an
66//! [`openreadout_core::Registry`] and let it detect the format; that is what the
67//! `openreadout` command-line tool does.
68//!
69//! # API stability
70//!
71//! The supported API is what this page documents. The parser modules are public only so that
72//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
73//! in any release.
74#![forbid(unsafe_code)]
75#![warn(missing_docs)]
76
77mod assurance;
78#[doc(hidden)]
79pub mod bruker_dataset;
80mod bruker_experiment;
81#[doc(hidden)]
82pub mod bruker_layout;
83#[doc(hidden)]
84pub mod bruker_params;
85#[doc(hidden)]
86pub mod jcamp_asdf;
87#[doc(hidden)]
88pub mod jcamp_dataset;
89#[doc(hidden)]
90pub mod jcamp_parse;
91#[doc(hidden)]
92pub mod jcamp_write;
93#[doc(hidden)]
94pub mod jeol_dataset;
95#[doc(hidden)]
96pub mod jeol_header;
97#[doc(hidden)]
98pub mod spinsolve;
99#[doc(hidden)]
100pub mod text;
101#[doc(hidden)]
102pub mod varian_dataset;
103#[doc(hidden)]
104pub mod varian_layout;
105#[doc(hidden)]
106pub mod varian_procpar;
107
108use std::path::Path;
109
110use openreadout_core::Result;
111use openreadout_core::model::{DetectConfidence, FormatDescriptor};
112use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
113use openreadout_core::source::Input;
114
115#[doc(hidden)]
116pub use bruker_dataset::{BrukerDataset, group_delay};
117#[doc(hidden)]
118pub use bruker_layout::{
119    ByteOrder, DSP_GROUP_DELAY, Experiment, ProcLayout, Processing, RawLayout, SampleType,
120    decode_samples, find_experiments, resolve_experiment_dir,
121};
122#[doc(hidden)]
123pub use bruker_params::{ParamFile, ParamValue, parse_param_file};
124#[doc(hidden)]
125pub use jcamp_asdf::{AsdfLine, AsdfTable, YToken, decode_asdf, decode_groups, lex_asdf_line};
126#[doc(hidden)]
127pub use jcamp_dataset::JcampDataset;
128#[doc(hidden)]
129pub use jcamp_parse::{Block, JcampFile, Ldr, normalize_label, parse_affn, parse_jcamp};
130#[doc(hidden)]
131pub use jeol_dataset::{JeolDataset, jeol_nucleus};
132#[doc(hidden)]
133pub use jeol_header::{JdfAxisType, JdfHeader, JdfParam, JdfUnit, JdfValue, parse_jdf_params};
134#[doc(hidden)]
135pub use spinsolve::{
136    ParFile, ProspaHeader, SpinsolveDataset, find_spinsolve_experiments_in, parse_par,
137    resolve_spinsolve_dir_in,
138};
139#[doc(hidden)]
140pub use text::decode_text;
141#[doc(hidden)]
142pub use varian_dataset::VarianDataset;
143#[doc(hidden)]
144pub use varian_layout::{
145    BlockHeader, FidHeader, VarianSampleType, decode_varian, find_varian_experiments,
146    read_fid_header, resolve_varian_dir,
147};
148#[doc(hidden)]
149pub use varian_procpar::{Procpar, ProcparParam, ProcparValues, parse_procpar};
150
151pub use jcamp_write::{
152    JcampEncoding, JcampExportOptions, JcampExportReport, default_jcamp_output, export_jcamp,
153};
154
155/// Format id of Bruker TopSpin experiment directories.
156pub const BRUKER_FORMAT_ID: &str = "bruker-nmr";
157/// Format id of JCAMP-DX files.
158pub const JCAMP_FORMAT_ID: &str = "jcamp-dx";
159/// Format id of Varian/Agilent VnmrJ data directories.
160pub const VARIAN_FORMAT_ID: &str = "varian-nmr";
161/// Format id of JEOL Delta `.jdf` files.
162pub const JEOL_FORMAT_ID: &str = "jeol-jdf";
163/// Format id of Magritek Spinsolve experiment directories.
164pub const SPINSOLVE_FORMAT_ID: &str = "magritek-spinsolve";
165
166/// The Bruker TopSpin reader.
167#[derive(Debug, Default, Clone, Copy)]
168pub struct BrukerReader;
169
170impl FormatReader for BrukerReader {
171    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
172        Some(&assurance::BRUKER_NMR)
173    }
174
175    fn descriptor(&self) -> FormatDescriptor {
176        FormatDescriptor {
177            id: BRUKER_FORMAT_ID.into(),
178            name: "Bruker TopSpin NMR".into(),
179            vendor: "Bruker".into(),
180            extensions: Vec::new(),
181            family: "nmr".into(),
182            can_read: true,
183            can_write: false,
184            confidence: assurance::BRUKER_NMR.confidence,
185            known_gaps: vec![
186                "Input is an experiment directory (or its acqus/fid/ser, or a pdata/<n> directory), not a single file".into(),
187                "Processed data: 1D, 2D and 3D components are read; 4D+ processing is not decoded".into(),
188                "Time-domain values are scaled by 2^NC by analogy with nmrglue's NC_proc rule (inferred); the digital-filter group delay is reported, and removed only when the FID is processed (`analyze nmr-peaks`, `trace --process`; 1-D rows only)".into(),
189                "Non-uniformly sampled ser files are returned as acquired rows; nuslist indices are available as a table; NUS reconstruction is out of scope".into(),
190                "DTYPA/DTYPP values other than 0 (int32) and 2 (float64) are not decoded".into(),
191            ],
192        }
193    }
194
195    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
196        self.sniff_input(head, &Input::local(path))
197    }
198
199    /// Experiment directories are recognised by their parameter and data files, looked up
200    /// through the namespace.
201    fn sniff_input(&self, _head: &[u8], input: &Input) -> Option<Detection> {
202        let (path, fs) = (input.path(), input.fs());
203        if bruker_layout::resolve_experiment_dir_in(fs, path).is_some() {
204            return Some(Detection {
205                format_id: BRUKER_FORMAT_ID,
206                confidence: DetectConfidence::Definite,
207                note: None,
208            });
209        }
210        if fs.is_dir(path) {
211            let exps = bruker_layout::find_experiments_in(fs, path);
212            if !exps.is_empty() {
213                return Some(Detection {
214                    format_id: BRUKER_FORMAT_ID,
215                    confidence: DetectConfidence::Likely,
216                    note: Some(format!(
217                        "directory holds {} Bruker experiment directories; open one of them (e.g. {})",
218                        exps.len(),
219                        exps[0].display()
220                    )),
221                });
222            }
223        }
224        None
225    }
226
227    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
228        Ok(Box::new(BrukerDataset::open(path)?))
229    }
230
231    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
232        Ok(Box::new(BrukerDataset::open_input(input)?))
233    }
234
235    fn reads_any_source(&self) -> bool {
236        true
237    }
238}
239
240/// The JCAMP-DX reader.
241#[derive(Debug, Default, Clone, Copy)]
242pub struct JcampReader;
243
244impl FormatReader for JcampReader {
245    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
246        Some(&assurance::JCAMP_DX)
247    }
248
249    fn descriptor(&self) -> FormatDescriptor {
250        FormatDescriptor {
251            id: JCAMP_FORMAT_ID.into(),
252            name: "JCAMP-DX".into(),
253            vendor: "IUPAC open standard (NMR, IR, UV-Vis, MS spectra)".into(),
254            extensions: vec!["jdx".into(), "dx".into(), "jcamp".into(), "jcm".into()],
255            family: "spectroscopy".into(),
256            can_read: true,
257            can_write: true,
258            confidence: assurance::JCAMP_DX.confidence,
259            known_gaps: vec![
260                "##PEAK ASSIGNMENTS= tables and JCAMP-CS structure blocks are listed, not decoded"
261                    .into(),
262                "ASDF compression inside (XY..XY) peak tables is not decoded (AFFN only)".into(),
263                "##RADATA= (interferograms) is listed, not decoded".into(),
264            ],
265        }
266    }
267
268    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
269        if jcamp_parse::looks_like_jcamp(head) {
270            return Some(Detection {
271                format_id: JCAMP_FORMAT_ID,
272                confidence: DetectConfidence::Definite,
273                note: None,
274            });
275        }
276        if has_extension(path, &["jdx", "dx", "jcamp", "jcm"]) {
277            return Some(Detection {
278                format_id: JCAMP_FORMAT_ID,
279                confidence: DetectConfidence::ExtensionOnly,
280                note: Some("JCAMP-DX extension but the file does not start with ##TITLE=".into()),
281            });
282        }
283        None
284    }
285
286    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
287        Ok(Box::new(JcampDataset::open(path)?))
288    }
289
290    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
291        Ok(Box::new(JcampDataset::open_input(input)?))
292    }
293
294    fn reads_any_source(&self) -> bool {
295        true
296    }
297}
298
299/// The Varian/Agilent VnmrJ reader (`<name>.fid/` directories with `fid` and `procpar`).
300#[derive(Debug, Default, Clone, Copy)]
301pub struct VarianReader;
302
303impl FormatReader for VarianReader {
304    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
305        Some(&assurance::VARIAN_NMR)
306    }
307
308    fn descriptor(&self) -> FormatDescriptor {
309        FormatDescriptor {
310            id: VARIAN_FORMAT_ID.into(),
311            name: "Varian/Agilent VnmrJ NMR".into(),
312            vendor: "Agilent (Varian)".into(),
313            extensions: Vec::new(),
314            family: "nmr".into(),
315            can_read: true,
316            can_write: false,
317            confidence: assurance::VARIAN_NMR.confidence,
318            known_gaps: vec![
319                "Input is a data directory (`<name>.fid/` with fid and procpar), or its fid/procpar/text/log".into(),
320                "Sweeps are the fid's traces in disk order: arrayed and multidimensional data are not reordered by phase or array parameters (nmrglue's as_2d order)".into(),
321                "Block scale factors and drift corrections are reported, not applied (as nmrglue)".into(),
322                "Processed data (datdir/phasefile, datdir/data) are listed, not decoded: no public file or permissive prior art".into(),
323                "int16 samples (dp='n') are decoded from the header flags but covered by synthetic tests only".into(),
324            ],
325        }
326    }
327
328    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
329        self.sniff_input(head, &Input::local(path))
330    }
331
332    /// Data directories are recognised by their `fid` header, read through the namespace.
333    fn sniff_input(&self, _head: &[u8], input: &Input) -> Option<Detection> {
334        let (path, fs) = (input.path(), input.fs());
335        if varian_layout::resolve_varian_dir_in(fs, path).is_some() {
336            return Some(Detection {
337                format_id: VARIAN_FORMAT_ID,
338                confidence: DetectConfidence::Definite,
339                note: None,
340            });
341        }
342        if fs.is_dir(path) {
343            let exps = varian_layout::find_varian_experiments_in(fs, path);
344            if !exps.is_empty() {
345                return Some(Detection {
346                    format_id: VARIAN_FORMAT_ID,
347                    confidence: DetectConfidence::Likely,
348                    note: Some(format!(
349                        "directory holds {} VnmrJ data directories; open one of them (e.g. {})",
350                        exps.len(),
351                        exps[0].display()
352                    )),
353                });
354            }
355        }
356        None
357    }
358
359    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
360        Ok(Box::new(VarianDataset::open(path)?))
361    }
362
363    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
364        Ok(Box::new(VarianDataset::open_input(input)?))
365    }
366
367    fn reads_any_source(&self) -> bool {
368        true
369    }
370}
371
372/// The JEOL Delta `.jdf` reader.
373#[derive(Debug, Default, Clone, Copy)]
374pub struct JeolReader;
375
376impl FormatReader for JeolReader {
377    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
378        Some(&assurance::JEOL_JDF)
379    }
380
381    fn descriptor(&self) -> FormatDescriptor {
382        FormatDescriptor {
383            id: JEOL_FORMAT_ID.into(),
384            name: "JEOL Delta NMR".into(),
385            vendor: "JEOL".into(),
386            extensions: vec!["jdf".into()],
387            family: "nmr".into(),
388            can_read: true,
389            can_write: false,
390            confidence: assurance::JEOL_JDF.confidence,
391            known_gaps: vec![
392                "1D and 2D (32-point submatrix) data with real/complex axes are decoded; 3D+ and small-submatrix layouts, TPPI and envelope axes are unsupported (exit 6)".into(),
393                "Values are returned as stored; nmrglue returns the complex conjugate".into(),
394                "String parameters hold at most 16 characters (longer values are cut in the file)".into(),
395                "Acquisition start (ACTUAL_START_TIME, seconds since 1990-01-01 UTC) and header dates are inferred from corpus files".into(),
396                "Context, annotation and history sections are not decoded".into(),
397            ],
398        }
399    }
400
401    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
402        if head.starts_with(b"JEOL.NMR") {
403            return Some(Detection {
404                format_id: JEOL_FORMAT_ID,
405                confidence: DetectConfidence::Definite,
406                note: None,
407            });
408        }
409        // a longer file without the signature is another kind of file (exit 3)
410        if has_extension(path, &["jdf"]) && head.len() < 8 {
411            return Some(Detection {
412                format_id: JEOL_FORMAT_ID,
413                confidence: DetectConfidence::ExtensionOnly,
414                note: Some("JEOL extension but the file does not start with JEOL.NMR".into()),
415            });
416        }
417        None
418    }
419
420    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
421        Ok(Box::new(JeolDataset::open(path)?))
422    }
423
424    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
425        Ok(Box::new(JeolDataset::open_input(input)?))
426    }
427
428    fn reads_any_source(&self) -> bool {
429        true
430    }
431}
432
433/// The Magritek Spinsolve reader (experiment directories with `acqu.par` and Prospa `.1d`/`.2d`
434/// data files).
435#[derive(Debug, Default, Clone, Copy)]
436pub struct SpinsolveReader;
437
438impl FormatReader for SpinsolveReader {
439    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
440        Some(&assurance::MAGRITEK_SPINSOLVE)
441    }
442
443    fn descriptor(&self) -> FormatDescriptor {
444        FormatDescriptor {
445            id: SPINSOLVE_FORMAT_ID.into(),
446            name: "Magritek Spinsolve benchtop NMR".into(),
447            vendor: "Magritek".into(),
448            extensions: vec!["1d".into(), "2d".into()],
449            family: "nmr".into(),
450            can_read: true,
451            can_write: false,
452            confidence: assurance::MAGRITEK_SPINSOLVE.confidence,
453            known_gaps: vec![
454                "Input is an experiment directory (acqu.par and data.1d/data.2d), or any file in it; a folder of experiments lists them".into(),
455                "Prospa data types 501 (complex), 503 (x + real) and 504 (x + complex) are decoded; other type codes and multi-row files with an x block are listed, not decoded".into(),
456                "Plot files (.pt1/.pt2), MestReNova documents and nmr_fid.dx are listed, not decoded (open nmr_fid.dx with the JCAMP-DX reader)".into(),
457                "The x block's unit is not stored: it is named (ms or ppm) only when its spacing matches the dwell time or the spectral width".into(),
458                "Sub-experiment folders (e.g. 1D_T1IRT2/0000/) are opened one by one".into(),
459            ],
460        }
461    }
462
463    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
464        self.sniff_input(head, &Input::local(path))
465    }
466
467    /// Prospa data files by their magic; directories and parameter files through the namespace.
468    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
469        let (path, fs) = (input.path(), input.fs());
470        if head.starts_with(spinsolve::DATA_MAGIC)
471            || spinsolve::resolve_spinsolve_dir_in(fs, path).is_some()
472        {
473            return Some(Detection {
474                format_id: SPINSOLVE_FORMAT_ID,
475                confidence: DetectConfidence::Definite,
476                note: None,
477            });
478        }
479        if fs.is_dir(path) {
480            let exps = spinsolve::find_spinsolve_experiments_in(fs, path);
481            if !exps.is_empty() {
482                return Some(Detection {
483                    format_id: SPINSOLVE_FORMAT_ID,
484                    confidence: DetectConfidence::Likely,
485                    note: Some(format!(
486                        "directory holds {} Spinsolve experiments; open one of them (e.g. {})",
487                        exps.len(),
488                        exps[0].display()
489                    )),
490                });
491            }
492        }
493        None
494    }
495
496    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
497        Ok(Box::new(SpinsolveDataset::open(path)?))
498    }
499
500    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
501        Ok(Box::new(SpinsolveDataset::open_input(input)?))
502    }
503
504    fn reads_any_source(&self) -> bool {
505        true
506    }
507}