This class converts PeakMaps and MSSpectra from/to different IM/FAIMS storage models. More...

#include <OpenMS/IONMOBILITY/IMDataConverter.h>

Static Public Member Functions
static std::vector< PeakMap >	splitByFAIMSCV (PeakMap &&exp)
	Splits a PeakMap into one PeakMap per FAIMS compensation voltage (CV) More...

static MSExperiment	reshapeIMFrameToMany (MSSpectrum im_frame)
	Split a (TimsTOF) ion mobility frame (i.e. a spectrum concatenated from multiple spectra with different IM values) into separate spectra. More...

static std::tuple< std::vector< MSExperiment >, Math::BinContainer >	splitExperimentByIonMobility (MSExperiment &&in, UInt number_of_IM_bins, double bin_extension_abs, double mz_binning_width, MZ_UNITS mz_binning_width_unit)
	Bins the ion mobility range into discrete bins and creates a new MSExperiment for each IM bin. More...

static MSExperiment	reshapeIMFrameToSingle (const MSExperiment &in)
	Collapses multiple MS spectra (each with its own drift time) from the same IM-frame into a single MSSpectrum (with an IM-float data array) More...

static void	setIMUnit (DataArrays::FloatDataArray &fda, const DriftTimeUnit unit)
	Convert from a Unit to a CV term and annotate is as the FDA's name. This is not very accurate (since we cannot decide if its 'raw' or 'binned' IM data), but it allows to reconstruct the unit from the IM float-data array which is annotated with this term. More...

static bool	getIMUnit (const DataArrays::FloatDataArray &fda, DriftTimeUnit &unit)
	Checks if the `fda` is an ion-mobility array and if so, returns the unit (either MILLISECOND or VSSC, or NONE) More...

Detailed Description

This class converts PeakMaps and MSSpectra from/to different IM/FAIMS storage models.

Member Function Documentation

◆ getIMUnit()

static bool getIMUnit	(	const DataArrays::FloatDataArray &	fda,
		DriftTimeUnit &	unit
	)

static

Checks if the fda is an ion-mobility array and if so, returns the unit (either MILLISECOND or VSSC, or NONE)

The name of the fda should correspond to a value set by setIMUnit(), but all CV names of child terms of 'MS:1002893 ! ion mobility array' are accepted.

This is the current mapping (all of which return true)
CV term	Unit
MS:1002816 ! mean ion mobility array	DriftTimeUnit::MILLISECOND
MS:1003008 ! raw inverse reduced ion mobility array	DriftTimeUnit::VSSC
MS:1002893 ! ion mobility array **	DriftTimeUnit::NONE

**) or a child term, which is not one of the terms used above.

Parameters

[in]	fda	Input array, which is tested for its name
[out]	unit	If `fda` is an IM array, the `unit` will contain the IM unit (undefined otherwise)

Returns: True if fda is an IM array, false otherwise

◆ reshapeIMFrameToMany()

static MSExperiment reshapeIMFrameToMany ( MSSpectrum im_frame )

static

Split a (TimsTOF) ion mobility frame (i.e. a spectrum concatenated from multiple spectra with different IM values) into separate spectra.

The input im_frame must have a floatDataArray where IM values are annotated. If not, an exception is thrown.

For the output spectra, the IM value is annotated once in spec.getDriftTime() (there is no metadata array which contains IM values, since they are all the same).

Output spectra are sorted by m/z. Ranges of the experiment are updated.

The reverse operation is reshapeIMFrameToSingle().

Parameters

im_frame Concatenated spectrum representing an IM frame

Returns: IM frame split into spectra (one per distinct IM value), sorted by m/z, with updated ranges

Exceptions

Exception::MissingInformation if im_frame does not have IM data in floatDataArrays

Referenced by TOPPViewBase::showCurrentPeaksAsIonMobility().

◆ reshapeIMFrameToSingle()

static MSExperiment reshapeIMFrameToSingle ( const MSExperiment & in )

static

Collapses multiple MS spectra (each with its own drift time) from the same IM-frame into a single MSSpectrum (with an IM-float data array)

Frames are recognized by having the same RT for subsequent spectra. The IM information is taken from each input spectrum's .getDriftTime(). Multiple frames are allowed. If the input already contains IM-frames, they are simply copied.

If a spectrum does not have drift time (spec.getDriftTime()), it is simply copied to the output and ignored during the collapsing process.

Parameters

in	The input experiment with multiple spectra per frame

Returns: result The output spectra collapsed to a single spectrum per frame

Note: This requires that spectra from the same frame have the same RT ("scan start time")

The reverse operation is reshapeIMFrameToMany().

Exceptions

Exception::InvalidValue if any spectrum has both a single drift time AND a IM-float data array (see IMTypes::determineIMFormat(), or MSSpectrum::containsIMData())

◆ setIMUnit()

static void setIMUnit	(	DataArrays::FloatDataArray &	fda,
		const DriftTimeUnit	unit
	)

static

Convert from a Unit to a CV term and annotate is as the FDA's name. This is not very accurate (since we cannot decide if its 'raw' or 'binned' IM data), but it allows to reconstruct the unit from the IM float-data array which is annotated with this term.

This is the mapping
Unit	CV term
DriftTimeUnit::MILLISECOND	MS:1002816 ! mean ion mobility array
DriftTimeUnit::VSSC	MS:1003008 ! raw inverse reduced ion mobility array

For any other unit (e.g. FAIMS-Compensation voltage) we throw, since the PSI CV does not (and should not?) have CV terms for other IM units in ion mobility arrays.

Parameters

[out]	fda	The FDA to be annotated as an IM array
[in]	unit	The unit of the IM measurement

Exceptions

Exception::InvalidValue for unsupported units

◆ splitByFAIMSCV()

static std::vector<PeakMap> splitByFAIMSCV ( PeakMap && exp )

static

Splits a PeakMap into one PeakMap per FAIMS compensation voltage (CV)

The spectra from the original PeakMap are moved to new PeakMaps, so the original PeakMap is unusable afterwards.

Behavior:

Requires that the dataset contains FAIMS spectra (MS1 with DriftTimeUnit::FAIMS_COMPENSATION_VOLTAGE).
MS2+ spectra without an explicit FAIMS CV are assigned to the last seen FAIMS CV (based on run order). Spectra without a prior FAIMS CV context are skipped with a warning.
If the dataset contains no FAIMS spectra at all, an exception is thrown.

Parameters

exp	The PeakMap (will be moved-from)

Returns: Several PeakMaps, one per unique FAIMS CV

Exceptions

Exception::MissingInformation if exp contains no FAIMS data

◆ splitExperimentByIonMobility()

static std::tuple< std::vector<MSExperiment>, Math::BinContainer> splitExperimentByIonMobility	(	MSExperiment &&	in,
		UInt	number_of_IM_bins,
		double	bin_extension_abs,
		double	mz_binning_width,
		MZ_UNITS	mz_binning_width_unit
	)

static

Bins the ion mobility range into discrete bins and creates a new MSExperiment for each IM bin.

The IM range (of the whole in) is divided into equally spaced IM-bins and the bin center is the new drift time (see spec.getDriftTime()). Usually multiple spectra from an IM frame (with close IM values) fall into the same bin. These spectra are merged using SpectraMerger's block-method. When merging m/z peaks of two MS spectra with SpectraMerger, parameters mz_binning_width and mz_binning_width_unit and used internally.

To avoid artifacts at the bin borders, each bin can be extended by bin_extension_abs on both sides. The actual overlap between adjacent bins is thus 2*bin_extension_abs.

Note: All MS levels are binned. If you want to bin only a specific MS level, you need to filter the input MSExperiment before calling this function.

Parameters

in	The PeakMap containing many 'wide' IM-frame spectra (where one spectrum contains multiple IM values).
number_of_IM_bins	Into how many bins should the ion mobility range be sliced?
bin_extension_abs	How much should each bin be extended at its borders? (in absolute IM units). The actual overlap between adjacent bins is thus `2*bin_extension_abs`.
mz_binning_width	The width of the m/z binning window, when merging spectra of the same IM-bin (in Da or ppm, see `mz_binning_width_unit`)
mz_binning_width_unit	The unit of the m/z binning window (Da or ppm)

Returns: One MSExperiment per IM-bin and the corresponding binning borders

Exceptions

Exception::InvalidValue	if any spectrum in `in` is missing an IM-float data array (see IMTypes::determineIMFormat(), or MSSpectrum::containsIMData())
Exception::InvalidValue	if number_of_IM_bins == 0
Exception::InvalidValue	if bin_extension_abs < 0

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ getIMUnit()

◆ reshapeIMFrameToMany()

◆ reshapeIMFrameToSingle()

◆ setIMUnit()

◆ splitByFAIMSCV()

◆ splitExperimentByIonMobility()