SpectroChemPy OMNIC reader mapping#
The OMNIC format references (OMNIC SPA file format, OMNIC SPG file format,
OMNIC SRS file format) describe the file formats independently of any software.
This page records how the SpectroChemPy reader
(src/spectrochempy/core/readers/read_omnic.py) maps the documented
structures onto NDDataset objects. It is implementation context for
SpectroChemPy contributors: the reader does not define the binary semantics,
and its behavior may lag behind the format references. The reader, its tests,
and the format references are reconciled through separate reader audits and
implementation changes.
SPA files#
The reader’s internal
firstxandlastxnames describe storage order (payload element 0 and the final element), not OMNIC’s First X / Last X display terminology:firstxis header+16(OMNIC Last X) andlastxis header+20(OMNIC First X).The interferogram optical-path-difference step
sample_spacing / (2 * reference_frequency)(header+84and+80) is implemented for native interferograms.The offset-296 timestamp is exposed as
dataset.acquisition_date. Library/retrieved files can store a counter or default-like value there, so the field should not be promoted to an acquisition date without checking the variant.Subtype-
0x79Experiment Information is decoded with the fixed-slot anchors+10,+90,+154and+413and exposed asomnic_*metadata; the+670text and the other0x82subtypes are not read. Only the first decoded block of a file is used.Some variant-specific metadata, including the Raman distinction between header
+80(reference frequency) and+96(excitation frequency), may not yet be surfaced with native semantics. This metadata limitation does not affect the stored Raman X axis.The optical velocity is taken from the
0x6ablock when it is parsed, with header-relative+188as a fallback (see Offsets beyond the 140-byte block).
SPG files#
The reader:
parses the key table, the per-spectrum
0x02data headers,0x03payloads,0x6btitle/timestamp blocks, and0x82blocks (using the first decoded subtype-0x79block of the file);sets
dataset.namefrom the filesystem filename stem, while the embedded group/title text (offset 30) is stored separately in the dataset description;exposes the per-spectrum
0x6btimestamps as the y coordinate (Unix-seconds values with datetime and title label rows) and asdataset.acquisition_date = minimum member timestamp— a reader convention on a heterogeneous container, not a format-level group acquisition property;sorts the spectra chronologically by those timestamps by default (
sortbydate=True), which changes the original SPG group order;sortbydate=Falsepreserves the stored order;reduces the per-spectrum acquisition parameters (collection length, reference/laser frequency, optical velocity) to a single global metadata value taken from the last parsed spectrum’s header; the optical velocity is read at header-relative
+188(and an internal, unexposed text value at+208), i.e. beyond the0x02block (see SPG header offsets);does not currently expose the
0x1bhistory blocks (including their background references), the0x6aparameter blocks, the0x69blocks, the interferogram-related0x64–0x67structures, or per-spectrum Experiment Information;rejects spectra with inconsistent X-axis definitions unless
allow_inconsistent_x=Trueis used, in which case it returns one dataset per spectrum.
SRS files#
spectrochempy.read_srs is the public entry point for .srs
files; it delegates to the OMNIC importer with the .srs file-type
constraint.
Spectral series are presented with a descending wavenumber X axis (high to low), matching the convention used by
read_spa, whereas the raw storage order is ascending (see Spectral sample order). The normalization is applied per spectrum from each record’s own endpoints.Spectral backgrounds are normalized per record to the same descending wavenumber grid as the series. Only a subset of background layouts is currently decoded: the
return_bgpath returns no data for some background record shapes.Rapid-scan interferograms retain the raw ascending data-points coordinate. These records are flagged internally (
meta.interferogram); their ZPD index is the data-derived peak index, and the laser frequency is set to the reader’s standard default rather than derived from these records’ coordinate or data.The reader distinguishes three X-axis cases: a known spectral axis (X-unit codes 1/3/4/32), an explicit data-points interferogram (X-unit code 2), and an unknown X-axis type (unrecognized code), which is left in raw storage orientation with an informational message and is neither treated as an interferogram nor spectral-normalized.
The series name (series-header
+938) is split on the first newline.The Y coordinate is relative series time in minutes (
time_minto the last time, rounded to 3 decimal places; title “Time”, units “minute”). Earlier reader versions misread header+1002as a collection length and header+1010(then namedfirsty) as the series minimum.The native
Collectedtimestamp (file offset 296) is accepted only when it matches one of its header-relative copies at the documented locations (see Time representation). It is then exposed throughdataset.acquisition_date, and the Y coordinate gains a second label column with the per-spectrum absolute datetimesCollected + timedelta(minutes=time_min + i * step), computed in full precision from the native float32 fields rather than from the rounded public Y coordinate.Variants without a valid absolute anchor (GC, reprocessed RapidScan), or whose copy locations differ from the documented ones, leave
acquisition_dateunset and keep single-column names-only Y labels.The public
collection_lengthmetadata attribute is derived from series-header+1006(series last time × 60), not from the general-header field at+68.The historical
reverse_xkeyword is a deprecated no-op: spectral orientation is handled automatically and supplying the keyword emits aDeprecationWarning.