File adapter for imzML 1.1.0 mass spectrometry imaging data. More...

#include <OpenMS/FORMAT/ImzMLFile.h>

Inheritance diagram for ImzMLFile:

Collaboration diagram for ImzMLFile:

Public Member Functions
Constructors and destructor
	ImzMLFile ()

	~ImzMLFile () override=default

Options
PeakFileOptions &	getOptions ()

const PeakFileOptions &	getOptions () const

void	setOptions (const PeakFileOptions &options)

Public Member Functions inherited from XMLFile
	XMLFile ()
	Construct an XMLFile without schema info; `schema_location_` remains unset, so isValid cannot be used until derived-class logic initializes `schema_location_` before calling isValid.

	XMLFile (const std::string &schema_location, const std::string &version)
	Construct with a schema location for later isValid calls.

virtual	~XMLFile ()
	Virtual destructor — defaulted; allows safe deletion through a base-class pointer.

bool	isValid (const std::string &filename, std::ostream &os)
	Check if `filename` validates against the bound XML schema.

const std::string &	getVersion () const
	Return the schema version string passed to the parameterised constructor; empty for default-constructed instances.

Public Member Functions inherited from ProgressLogger
	ProgressLogger ()
	Constructor.

virtual	~ProgressLogger ()
	Destructor.

	ProgressLogger (const ProgressLogger &other)
	Copy constructor.

ProgressLogger &	operator= (const ProgressLogger &other)
	Assignment Operator.

void	setLogType (LogType type) const
	Sets the progress log that should be used. The default type is NONE!

LogType	getLogType () const
	Returns the type of progress log being used.

void	setLogger (ProgressLoggerImpl *logger)
	Sets the logger to be used for progress logging.

void	startProgress (SignedSize begin, SignedSize end, const std::string &label) const
	Initializes the progress display.

void	setProgress (SignedSize value) const
	Sets the current progress.

void	endProgress (UInt64 bytes_processed=0) const

void	nextProgress () const
	increment progress by 1 (according to range begin-end)

Validation and storage
PeakFileOptions	options_

bool	isValid (const std::string &filename, std::ostream &os)
	Validate an imzML file against the mzML 1.1.0 XML schema.

void	store (const std::string &filename, const MSExperiment &exp) const
	Store an experiment as imzML (XML + companion .ibd).

void	store (const std::string &filename, const MSImagingExperiment &exp) const
	Store an MSImagingExperiment as imzML, taking pixel coordinates and grid dimensions from its MSImagingGeometry (the source of truth).

void	loadImpl_ (const std::string &filename, Interfaces::IMSDataConsumer consumer, MSExperiment &meta_exp, ImzMLMeta out_meta, std::vector< ImzMLSpectrumIndex > *out_index, bool index_only, const std::string &ibd_path_override="")

static std::string	inferIbdPath_ (const std::string &imzml_path)

Load
void	load (const std::string &filename, MSImagingExperiment &exp)
	Load an imzML file into an MSImagingExperiment for in-memory random access.

void	load (const std::string &filename, Interfaces::IMSDataConsumer &consumer)
	Stream-load an imzML file into a consumer.

void	loadSpectraIndex (const std::string &filename, ImzMLMeta &meta, std::vector< ImzMLSpectrumIndex > &index, const std::string &ibd_path="")
	Parse XML and build a per-spectrum .ibd index without loading peaks.

static void	buildImagingGeometry (const MSExperiment &exp, MSImagingGeometry &geom)
	Build `MSImagingGeometry` from a loaded imzML `MSExperiment`.

static void	buildImagingGeometry (const std::vector< ImzMLSpectrumIndex > &index, const ImzMLMeta &meta, MSImagingGeometry &geom)
	Build `MSImagingGeometry` directly from a parsed imzML spectrum index.

Additional Inherited Members
Public Types inherited from ProgressLogger
enum	LogType { CMD , GUI , NONE }
	Possible log types. More...

Protected Member Functions inherited from XMLFile
void	parse_ (const std::string &filename, XMLHandler *handler)
	Parse the XML file at `filename` through `handler`.

void	parseBuffer_ (const std::string &buffer, XMLHandler *handler)
	Parse an in-memory XML buffer through `handler`.

void	save_ (const std::string &filename, XMLHandler *handler) const
	Stores the contents of the XML handler given by `handler` in the file given by `filename`.

void	enforceEncoding_ (const std::string &encoding)
	Set or clear the XML-encoding override applied to subsequent parse_ / parseBuffer_ calls.

Protected Attributes inherited from XMLFile
std::string	schema_location_
	Path of the XML schema for validation; empty when the default constructor was used (isValid then throws `NotImplemented`).

std::string	schema_version_
	Schema version string returned by getVersion.

std::string	enforced_encoding_
	Optional XML encoding override applied to the `InputSource` in parse_ and parseBuffer_; empty disables the override. Used as a workaround for XTandem output XML which carries an encoding the parser otherwise stumbles on.

Protected Attributes inherited from ProgressLogger
LogType	type_

time_t	last_invoke_

ProgressLoggerImpl *	current_logger_

Static Protected Attributes inherited from ProgressLogger
static int	recursion_depth_

Detailed Description

File adapter for imzML 1.1.0 mass spectrometry imaging data.

imzML extends mzML with a companion binary file and IMS ontology terms. Data are split across two files on disk:

.imzML — XML metadata (mzML 1.1.0 schema + IMS CV terms)
.ibd — external m/z and intensity arrays

The .ibd path is derived from the .imzML path (same basename, extension replaced with .ibd, case-insensitive).

Parsing reuses MzMLHandler via Internal::ImzMLHandler, which decodes IMS-specific terms and reads peak data from the .ibd file.

Loading modes

In-memory: load(filename, MSImagingExperiment&) decodes the spectra and builds MSImagingGeometry for random access by (x, y) in RAM (zero-based coordinates; imzML file coordinates are 1-based). Use MSImagingExperiment::getMSExperiment() for the flat spectra.
Streaming: load(filename, IMSDataConsumer&) forwards decoded spectra to the consumer without retaining them in ImzMLFile. Delivery is batched after the spectrumList XML section is parsed (same as MzMLHandler), not on a per-startElement basis.
Index only: loadSpectraIndex() builds a byte-offset index for OnDiscImzMLExperiment.

Imaging metadata on MSExperiment After load(), dataset fields are stored as MetaValues, e.g. imzml:imaging_mode, imzml:ibd_path, imzml:uuid, checksums, imzml:max_count_x/y/z, pixel sizes, scan geometry, polarity, and array data types when present in the file. Per-spectrum pixel coordinates use imzml:x, imzml:y, imzml:z.

See also: MzMLFile, OnDiscImzMLExperiment, MSImagingExperiment, ImzMLMeta, ImzMLSpectrumIndex

Constructor & Destructor Documentation

◆ ImzMLFile()

ImzMLFile ( )

◆ ~ImzMLFile()

~ImzMLFile ( )

overridedefault

Member Function Documentation

◆ buildImagingGeometry() [1/2]

static void buildImagingGeometry	(	const MSExperiment &	exp,
		MSImagingGeometry &	geom
	)

static

Build MSImagingGeometry from a loaded imzML MSExperiment.

Reads dataset dimensions from imzml:max_count_x/y MetaValues when present and registers each spectrum that carries imzml:x/y (and imzml:z = 1). Coordinates are converted from imzML's 1-based convention to zero-based geometry indices.

Parameters

[in]	exp	Experiment previously loaded from imzML (e.g. via `load` or `FileHandler`).
[out]	geom	Geometry to populate (cleared first).

Exceptions

Exception::InvalidValue on invalid or duplicate pixel coordinates.

◆ buildImagingGeometry() [2/2]

static void buildImagingGeometry	(	const std::vector< ImzMLSpectrumIndex > &	index,
		const ImzMLMeta &	meta,
		MSImagingGeometry &	geom
	)

static

Build MSImagingGeometry directly from a parsed imzML spectrum index.

This is the source-of-truth path used by the loaders: it derives the pixel grid straight from the per-spectrum coordinates captured during parsing (no reliance on imzml:x/y MetaValues), mirroring how BrukerTimsImagingFile populates its geometry. Each index entry's 1-based (x, y) with z = 1 is registered as a zero-based pixel bound to that spectrum; dimensions and pixel size come from meta. Out-of-grid or < 1 coordinates are warned and skipped; duplicates raise Exception::InvalidValue.

Parameters

[in]	index	Per-spectrum index entries (e.g. from `loadSpectraIndex` or the loader).
[in]	meta	Dataset metadata (grid dimensions, pixel size).
[out]	geom	Geometry to populate (cleared first).

Exceptions

Exception::InvalidValue on duplicate pixel coordinates.

◆ getOptions() [1/2]

PeakFileOptions & getOptions ( )

◆ getOptions() [2/2]

const PeakFileOptions & getOptions ( ) const

◆ inferIbdPath_()

static std::string inferIbdPath_ ( const std::string & imzml_path )

staticprivate

◆ isValid()

bool isValid	(	const std::string &	filename,
		std::ostream &	os
	)

Validate an imzML file against the mzML 1.1.0 XML schema.

Parameters

[in]	filename	Path to the .imzML file.
[out]	os	Stream receiving validation messages.

Returns: true if the file passes schema validation.

◆ load() [1/2]

void load	(	const std::string &	filename,
		Interfaces::IMSDataConsumer &	consumer
	)

Stream-load an imzML file into a consumer.

Decoded spectra are passed to consumer.consumeSpectrum() after the spectrumList section has been parsed (batched delivery via MzMLHandler). Peak data are not retained in ImzMLFile itself.

Parameters

[in]	filename	Path to the .imzML file.
[in]	consumer	Receiver for spectra and experimental settings.

Exceptions

Exception::FileNotFound	if the .imzML or .ibd cannot be opened.
Exception::ParseError	if the XML is malformed.

◆ load() [2/2]

void load	(	const std::string &	filename,
		MSImagingExperiment &	exp
	)

Load an imzML file into an MSImagingExperiment for in-memory random access.

Performs a full load, then builds MSImagingGeometry from imzml:x/y MetaValues on each spectrum (imzML 1-based coordinates are mapped to zero-based pixel indices). Only spectra with imzml:z = 1 are indexed (2-D datasets).

Use MSImagingExperiment::getSpectrum(x, y) to fetch spectra by pixel without re-reading the .ibd file.

Parameters

[in]	filename	Path to the .imzML file.
[out]	exp	Target imaging experiment (replaced on success).

Exceptions

Exception::FileNotFound	if the .imzML or .ibd cannot be opened.
Exception::ParseError	if the XML is malformed.
Exception::InvalidValue	if pixel coordinates are invalid or duplicate.

◆ loadImpl_()

void loadImpl_	(	const std::string &	filename,
		Interfaces::IMSDataConsumer *	consumer,
		MSExperiment &	meta_exp,
		ImzMLMeta *	out_meta,
		std::vector< ImzMLSpectrumIndex > *	out_index,
		bool	index_only,
		const std::string &	ibd_path_override = `""`
	)

private

◆ loadSpectraIndex()

void loadSpectraIndex	(	const std::string &	filename,
		ImzMLMeta &	meta,
		std::vector< ImzMLSpectrumIndex > &	index,
		const std::string &	ibd_path = `""`
	)

Parse XML and build a per-spectrum .ibd index without loading peaks.

Populates meta and index for use with OnDiscImzMLExperiment. Opens the companion .ibd and records its path in meta.ibd_file_path.

Parameters

[in]	filename	Path to the .imzML file.
[out]	meta	Dataset-level imaging metadata.
[out]	index	Per-spectrum index entries (offsets into .ibd).
[in]	ibd_path	Optional explicit path to the companion .ibd; inferred from `filename` when empty.

Exceptions

Exception::FileNotFound	if the .imzML or .ibd cannot be opened.
Exception::ParseError	if the XML is malformed.

◆ setOptions()

void setOptions ( const PeakFileOptions & options )

◆ store() [1/2]

void store	(	const std::string &	filename,
		const MSExperiment &	exp
	)		const

Store an experiment as imzML (XML + companion .ibd).

Writes external binary arrays (float32 or float64 via PeakFileOptions) with a 16-byte UUID header in the .ibd file linked to IMS:1000080 in the XML. Continuous mode is selected when imzml:imaging_mode is continuous or all spectra share an identical m/z axis; otherwise processed mode is used.

Each spectrum must carry imzml:x and imzml:y MetaValues (1-based imzML pixel coordinates). Dataset imaging metadata (imzml:scan_pattern, imzml:polarity, grid dimensions, etc.) and per-spectrum RT/MS level are written when present. PeakFileOptions control binary precision and optional spectrum/peak filtering during export.

Parameters

[in]	filename	Path to the output .imzML file.
[in]	exp	Experiment with spectra and optional imzML MetaValues.

Exceptions

Exception::MissingInformation	if `exp` has no spectra or lacks imzml:x/y.
Exception::InvalidValue	if pixel coordinates are invalid or duplicate.
Exception::InvalidParameter	if continuous export is requested but spectra are incompatible.
Exception::UnableToCreateFile	if output files cannot be written.
Exception::ParseError	if binary array serialization fails.

◆ store() [2/2]

void store	(	const std::string &	filename,
		const MSImagingExperiment &	exp
	)		const

Store an MSImagingExperiment as imzML, taking pixel coordinates and grid dimensions from its MSImagingGeometry (the source of truth).

Unlike the MSExperiment overload, this does not require imzml:x/y MetaValues on the spectra: the spatial information is read from exp.getGeometry(), so any MSImagingExperiment can be written — including ones built without those MetaValues (e.g. from BrukerTimsImagingFile). Dataset-level imzML metadata already present on the wrapped experiment (imaging mode, data types, scan geometry, ...) is preserved; grid dimensions and pixel size are taken from the geometry.

Parameters

[in]	filename	Path to the output .imzML file.
[in]	exp	Imaging experiment to store.

Exceptions

Exception::InvalidValue	if a geometry pixel references a spectrum index outside the experiment, or pixel coordinates are invalid or duplicate.
Exception::UnableToCreateFile	if output files cannot be written.

Member Data Documentation

◆ options_

PeakFileOptions options_

private

Public Member Functions

Validation and storage

Load

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ImzMLFile()

◆ ~ImzMLFile()

Member Function Documentation

◆ buildImagingGeometry() [1/2]

◆ buildImagingGeometry() [2/2]

◆ getOptions() [1/2]

◆ getOptions() [2/2]

◆ inferIbdPath_()

◆ isValid()

◆ load() [1/2]

◆ load() [2/2]

◆ loadImpl_()

◆ loadSpectraIndex()

◆ setOptions()

◆ store() [1/2]

◆ store() [2/2]

Member Data Documentation

◆ options_