OnDiscImzMLExperiment Class Reference

Random-access, on-disc reader for imzML mass spectrometry imaging datasets. More...

#include <OpenMS/KERNEL/OnDiscImzMLExperiment.h>

Public Member Functions
	OnDiscImzMLExperiment ()
	~OnDiscImzMLExperiment ()
	OnDiscImzMLExperiment (const OnDiscImzMLExperiment &)=delete
OnDiscImzMLExperiment &	operator= (const OnDiscImzMLExperiment &)=delete
	OnDiscImzMLExperiment (OnDiscImzMLExperiment &&)
OnDiscImzMLExperiment &	operator= (OnDiscImzMLExperiment &&)
void	open (const std::string &imzml_path, const std::string &ibd_path="")
	Open an imzML dataset: parse the XML index, build the imaging geometry, and open the .ibd.
void	close () noexcept
	Close the companion .ibd file and release on-disc resources.
bool	isOpen () const noexcept
std::size_t	getNrSpectra () const noexcept
std::size_t	size () const noexcept
const ImzMLSpectrumIndex &	getIndex (std::size_t i) const
	Return the index entry for spectrum i.
MSSpectrum	getSpectrum (std::size_t i) const
	Decode and return spectrum i from the .ibd file.
MSSpectrum	operator[] (std::size_t i) const
	Sugar for getSpectrum(i).
MSSpectrum	getSpectrumAtCoord (uint32_t x, uint32_t y, uint32_t z=1) const
	Return the spectrum at imzML pixel coordinate (x, y[, z]).
IonImage	extractIonImage (double mz, double tolerance_ppm) const
	Extract an ion image over the whole dataset by summing peak intensities inside [mz - dm, mz + dm], with dm = mz * tolerance_ppm * 1e-6.
IonImage	extractIonImage (double mz, double tolerance_ppm, Size region_id) const
	Extract an ion image for a single region only.
const ImzMLMeta &	getImzMLMeta () const noexcept
	Returns imaging metadata parsed during open() — no IBD reads.
const MSImagingGeometry &	getGeometry () const
	The standard 2D imaging geometry (pixel grid + (x,y)->spectrum map).
MSImagingGeometry &	getGeometry ()
	Mutable access to the imaging geometry.
uint32_t	gridWidth () const noexcept
	Shorthand for getImzMLMeta().max_count_x.
uint32_t	gridHeight () const noexcept
	Shorthand for getImzMLMeta().max_count_y.

Private Attributes
std::unique_ptr< Impl >	pimpl_

Detailed Description

Random-access, on-disc reader for imzML mass spectrometry imaging datasets.

Analogous to OnDiscMSExperiment for indexed mzML files, but designed specifically for imzML's two-file layout (.imzML + .ibd).

Workflow:

OnDiscImzMLExperiment exp;
exp.open("tissue.imzML");           // parse XML index only — no peak I/O
 
std::cout << exp.getNrSpectra();    // instant, no IBD peak reads
const auto& meta = exp.getImzMLMeta();
 
MSSpectrum s = exp.getSpectrum(42);              // one fseek + fread per array
MSSpectrum s = exp.getSpectrumAtCoord(3, 7);    // pixel lookup (1-based coords)
const ImzMLSpectrumIndex& e = exp.getIndex(42); // IBD offsets, no read

Design. The PIMPL idiom hides all implementation details (IBD FILE*, index vector, coordinate map) so that this header has no dependency on expat, Xerces, or the native imzml:: parser library. The index is built by running ImzMLFile::loadSpectraIndex() during open() — no peak arrays are decoded until getSpectrum() is called.

Note

getSpectrum() returns m/z, intensity, and any indexed auxiliary external arrays (e.g. MS:1003006 ion mobility) as FloatDataArray entries — the same contract as in-memory ImzMLFile::load — so viewers can call containsIMData() / rasterize without a separate code path. Auxiliary arrays whose length differs from the peak count, or which declare no supported binary data type, are skipped with a warning in both loaders.

This class is not thread-safe. If concurrent reads are needed, construct one instance per thread.

See also

ImzMLFile, ImzMLMeta, ImzMLSpectrumIndex, OnDiscMSExperiment

Constructor & Destructor Documentation

OnDiscImzMLExperiment() [1/3]

OnDiscImzMLExperiment

(

)

~OnDiscImzMLExperiment()

~OnDiscImzMLExperiment

(

)

OnDiscImzMLExperiment() [2/3]

OnDiscImzMLExperiment ( const OnDiscImzMLExperiment &  )

delete

OnDiscImzMLExperiment() [3/3]

OnDiscImzMLExperiment

(

OnDiscImzMLExperiment &&

)

Member Function Documentation

close()

void close ( )

noexcept

Close the companion .ibd file and release on-disc resources.

After close(), isOpen() returns false and spectrum decode calls fail until open() is invoked again.

extractIonImage() [1/2]

IonImage extractIonImage	(	double	mz,
		double	tolerance_ppm
	)		const

Extract an ion image over the whole dataset by summing peak intensities inside [mz - dm, mz + dm], with dm = mz * tolerance_ppm * 1e-6.

This is the on-disc counterpart of MSImagingExperiment::extractIonImage: it walks the shared 2D geometry and decodes each pixel's peaks from the .ibd on demand, so the full dataset never needs to be held in memory. This makes it suitable for visualizing single-mass ion images of large datasets. Only m/z and intensity are decoded — auxiliary arrays do not contribute to the summed intensity, so a compressed auxiliary array is not reported here (unlike getSpectrum()).

Pixels absent from the geometry stay invalid in the returned image. Pixels with a spectrum but no peaks in the window are marked valid with intensity 0. The returned image's m/z range is set to [mz - dm, mz + dm].

Parameters

[in]	mz	m/z center of the extraction window (>= 0).
[in]	tolerance_ppm	Half-window width in ppm (>= 0).

Returns

Image with the same dimensions as the geometry.

Exceptions

Exception::InvalidValue	if mz or tolerance_ppm is negative or non-finite.
Exception::FileNotFound	if the .ibd is not open.

extractIonImage() [2/2]

IonImage extractIonImage	(	double	mz,
		double	tolerance_ppm,
		Size	region_id
	)		const

Extract an ion image for a single region only.

Same summation and window semantics as the whole-dataset overload, but limited to the acquired pixels belonging to region_id (decoded lazily from the .ibd).

Parameters

[in]	mz	m/z center of the extraction window (>= 0).
[in]	tolerance_ppm	Half-window width in ppm (>= 0).
[in]	region_id	Region of pixels to extract.

Returns

Image with the same dimensions as the geometry.

Exceptions

Exception::InvalidValue	if mz or tolerance_ppm is negative or non-finite.
Exception::FileNotFound	if the .ibd is not open.
Exception::ElementNotFound	if region_id is unknown.

getGeometry() [1/2]

MSImagingGeometry & getGeometry

(

)

Mutable access to the imaging geometry.

The geometry is built eagerly during open(). Use this accessor to annotate the dataset with user-defined regions after loading, e.g.:

exp.getGeometry().addRegion(MSImagingRegion::rectangle(1, "roi", 0, 0, 3, 3));

getGeometry() [2/2]

const MSImagingGeometry & getGeometry

(

)

const

The standard 2D imaging geometry (pixel grid + (x,y)->spectrum map).

Returns the shared MSImagingGeometry abstraction (the same type populated by ImzMLFile::load(filename, MSImagingExperiment&)), so on-disc and in-memory access expose pixel coordinates the same way. Coordinates are 0-based; imzML's 1-based coordinates are normalized here, and only the z == 1 plane is represented. Built during open() from the parsed index (no IBD reads); this is a const, O(1) accessor (any duplicate/invalid-coordinate warning already surfaced at open()).

getImzMLMeta()

const ImzMLMeta & getImzMLMeta ( ) const

noexcept

Returns imaging metadata parsed during open() — no IBD reads.

getIndex()

const ImzMLSpectrumIndex & getIndex

(

std::size_t

i

)

const

Return the index entry for spectrum i.

Contains pixel coordinates and byte offsets — no IBD read performed.

Parameters

i	0-based spectrum index.

Exceptions

Exception::IndexOverflow

if i >= getNrSpectra().

getNrSpectra()

std::size_t getNrSpectra ( ) const

noexcept

getSpectrum()

MSSpectrum getSpectrum

(

std::size_t

i

)

const

Decode and return spectrum i from the .ibd file.

The returned MSSpectrum contains peak arrays decoded from the .ibd file and pixel coordinates as MetaValues (imzml:x, imzml:y, imzml:z). mzML scan metadata (RT, MS level, etc.) is not loaded in on-disc mode.

Parameters

i	0-based spectrum index.

Exceptions

Exception::IndexOverflow	if i >= getNrSpectra().
Exception::FileNotFound	if the .ibd is not open.
Exception::ParseError	if m/z, intensity, or auxiliary arrays are compressed (MS:1000572 other than MS:1000576), or if m/z and intensity array lengths mismatch.

getSpectrumAtCoord()

MSSpectrum getSpectrumAtCoord	(	uint32_t	x,
		uint32_t	y,
		uint32_t	z = 1
	)		const

Return the spectrum at imzML pixel coordinate (x, y[, z]).

Coordinates are imzML-native 1-based, matching ImzMLSpectrumIndex::x/y/z. The lookup is served by the shared MSImagingGeometry (see getGeometry()), which is 0-based and 2-dimensional; this method converts (x, y) to 0-based and only the z == 1 plane is addressable (consistent with the in-memory ImzMLFile loader, which likewise builds a 2D geometry). The geometry is built once during open(), so this is an O(1) lookup plus one peak-decode read.

Parameters

x	Pixel column (1-based).
y	Pixel row (1-based).
z	Depth slice (1-based, default 1; only z == 1 is supported).

Exceptions

Exception::ElementNotFound

if no spectrum exists at (x, y, z).

gridHeight()

uint32_t gridHeight ( ) const

noexcept

Shorthand for getImzMLMeta().max_count_y.

gridWidth()

uint32_t gridWidth ( ) const

noexcept

Shorthand for getImzMLMeta().max_count_x.

isOpen()

bool isOpen ( ) const

noexcept

open()

void open	(	const std::string &	imzml_path,
		const std::string &	ibd_path = ""
	)

Open an imzML dataset: parse the XML index, build the imaging geometry, and open the .ibd.

The .ibd path is inferred from imzml_path unless ibd_path is provided explicitly. No peak data is read — peak arrays are decoded lazily per getSpectrum() call. The 2D pixel geometry (see getGeometry()) is built eagerly here from the parsed index (an in-memory pass, no .ibd reads), so any problem with the coordinate grid is reported at open() rather than on the first pixel query.

A UUID-header mismatch between the .ibd and the XML's IMS:1000080, an out-of-grid pixel, a <1 coordinate, or a duplicate pixel coordinate are reported as warnings (the dataset still loads; of duplicates, only the first spectrum per pixel enters the geometry).

Parameters

imzml_path	Path to the .imzML file.
ibd_path	Optional override for the .ibd path.

Exceptions

Exception::FileNotFound	if either file cannot be opened.
Exception::ParseError	on malformed XML.

operator=() [1/2]

OnDiscImzMLExperiment & operator= ( const OnDiscImzMLExperiment &  )

delete

operator=() [2/2]

OnDiscImzMLExperiment & operator=

(

OnDiscImzMLExperiment &&

)

operator[]()

MSSpectrum operator[] ( std::size_t  i ) const

inline

Sugar for getSpectrum(i).

size()

std::size_t size ( ) const

inlinenoexcept

Member Data Documentation

pimpl_

std::unique_ptr<Impl> pimpl_

private