OnDiscImzMLExperiment Class Reference

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

#include <OpenMS/KERNEL/OnDiscImzMLExperiment.h>

Collaboration diagram for OnDiscImzMLExperiment:

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

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 spectrum from the .ibd on demand (one fseek + fread per pixel), so the full dataset never needs to be held in memory. This makes it suitable for visualizing single-mass ion images of large datasets.

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 error 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.

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 a structurally broken coordinate grid is rejected at open() rather than later.

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

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.
Exception::InvalidValue	if the dataset has duplicate pixel coordinates.

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