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

#include <OpenMS/FORMAT/ImzMLFile.h>

Inheritance diagram for ImzMLFile:

Public Member Functions
Constructors and destructor
	ImzMLFile ()
	Default constructor.

	~ImzMLFile () override=default
	Destructor.

Options
PeakFileOptions &	getOptions ()
	Mutable access to the options for loading/storing.

const PeakFileOptions &	getOptions () const
	Non-mutable access to the options for loading/storing.

void	setOptions (const PeakFileOptions &options)
	Set options for loading/storing.

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, MSExperiment &spectra, const std::string &ibd_path="")
	Parse the XML into a per-spectrum .ibd index and the spectrum metadata, 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, bool namespace_aware=false)
	Parse the XML file at `filename` through `handler`.

void	parseBuffer_ (const std::string &buffer, XMLHandler *handler, bool namespace_aware=false)
	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, intensity, and optional auxiliary arrays (e.g. PSI-MS MS:1003006 ion mobility → FloatDataArray)

After load, spectra that carry per-peak ion mobility expose it via MSSpectrum::containsIMData() / getFloatDataArrays() — the same contract used by mzML ion-mobility data and by viewers. Aux arrays must match the peak count; mismatched lengths are skipped with a warning, as are aux arrays without a supported binary data type.

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, derives MSImagingGeometry directly from the parsed per-spectrum coordinate index, and provides zero-based (x, y) random access in RAM (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 together with every spectrum's metadata (without peaks; data arrays empty, with their metadata), so on-disc spectra carry the same metadata as in-memory ones.
Metadata only (PeakFileOptions::setMetadataOnly, or setFillData(false)): every spectrum is returned with its metadata and pixel coordinates but without peaks; its data arrays are empty and keep their metadata. The .ibd is not opened, so it need not exist (and its UUID is not checked). (For mzML, metadata-only skips the spectra entirely; an imaging dataset needs them for its geometry.)

Retention time imzML spectra are pixels, not chromatographic scans. A scan start time (MS:1000016) is kept, in seconds, as the spectrum MetaValue imzml:scan_start_time (not set when the file has none or a negative placeholder such as -1), and RT is set to -1 on every load path (in-memory, streaming, metadata-only and on-disc). store() writes scan start time from RT when the caller set it (>= 0), otherwise from a numeric imzml:scan_start_time, and omits it when neither exists; an RT range in the store options filters on that same value and, as on load, keeps spectra without a time. MzMLFile::store writes the same value as scan start time, so the time survives an export to mzML (see ImzMLSpectrumRules::scanStartTime).

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.

IBD integrity check Every load path verifies that the first 16 bytes of the companion .ibd match the UUID declared via IMS:1000080 in the .imzML XML. A mismatch (or a missing / unparsable UUID in the XML) is reported as a warning rather than a hard error, so that legacy and non-conformant datasets still load. Callers that require strict conformance should inspect the warning log.

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

Constructor & Destructor Documentation

◆ ImzMLFile()

ImzMLFile ( )

Default constructor.

◆ ~ImzMLFile()

~ImzMLFile ( )

overridedefault

Destructor.

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. Out-of-grid or < 1 coordinates are warned and skipped. Duplicate coordinates are likewise warned and dropped from the geometry (only the first spectrum per pixel is mapped; every spectrum stays reachable by index), matching what the loaders accept for the same dataset.

Prefer the index-based overload when a spectrum index is available (used by the loaders). This MetaValue-based path is for experiments already loaded into an MSExperiment (e.g. via FileHandler).

Parameters

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

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

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). Duplicate pixel coordinates are warned about; only the first spectrum per pixel enters the geometry, and all spectra stay reachable by linear index.

◆ getOptions() [1/2]

PeakFileOptions & getOptions ( )

Mutable access to the options for loading/storing.

◆ getOptions() [2/2]

const PeakFileOptions & getOptions ( ) const

Non-mutable access to the options for loading/storing.

◆ 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 and derives MSImagingGeometry directly from the parsed per-spectrum coordinate index — the same path used by loadSpectraIndex and OnDiscImzMLExperiment. Coordinates are converted from imzML's 1-based convention to zero-based pixel indices; only spectra with z = 1 are indexed (2-D datasets). Out-of-grid or < 1 coordinates are skipped with a warning, and so are duplicate coordinates (only the first spectrum per pixel enters the geometry).

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.

◆ 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,
		MSExperiment &	spectra,
		const std::string &	ibd_path = `""`
	)

Parse the XML into a per-spectrum .ibd index and the spectrum metadata, without loading peaks.

Populates meta, index and spectra for use with OnDiscImzMLExperiment. spectra receives one spectrum per index entry, in the same order, with all metadata the in-memory load() gives it (native ID, MS level, polarity, scan and instrument settings, MetaValues incl. imzml:x/y/z and imzml:scan_start_time) but no peaks. Its data arrays are present but empty, keeping their metadata (they receive the .ibd values in OnDiscImzMLExperiment::getSpectrum()). spectra also receives the dataset-level ExperimentalSettings and imzml:* MetaValues. 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).
[out]	spectra	Spectrum metadata without peaks (replaced).
[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 )

Set options for loading/storing.

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

Spectra sharing a pixel coordinate are written out as-is with a warning, matching what load accepts for the same dataset.

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.
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 if pixel coordinates are invalid.
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_