OpenMS
IMDataConverter Class Reference

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< PeakMapsplitByFAIMSCV (PeakMap &&exp)
 Splits a PeakMap into one PeakMap per FAIMS compensation voltage. More...
 
static MSExperiment splitByIonMobility (MSSpectrum im_frame, UInt number_of_bins=-1)
 Split a (TimsTOF) ion mobility frame (i.e. a spectrum concatenated from multiple spectra with different IM values) into separate spectra. More...
 
static MSExperiment splitByIonMobility (MSExperiment &&in, UInt number_of_bins=-1)
 Expands all (TimsTOF) ion mobility frames in the PeakMap (i.e. all IM spectra with an IM float data array) into separate spectra. Non-IM spectra are simply copied to the result. More...
 
static MSExperiment collapseFramesToSingle (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

◆ collapseFramesToSingle()

static MSExperiment collapseFramesToSingle ( 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
expThe input experiment with multiple spectra per frame
resultThe 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")
Exceptions
Exception::InvalidValueif any spectrum has both a single drift time AND a IM-float data array (see IMTypes::determineIMFormat)

◆ 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]fdaInput array, which is tested for its name
[out]unitIf fda is an IM array, the unit will contain the IM unit (undefined otherwise)
Returns
True if fda is an IM array, false otherwise

◆ 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]fdaThe FDA to be annotated as an IM array
[in]unitThe unit of the IM measurement
Exceptions
Exception::InvalidValuefor unsupported units

◆ splitByFAIMSCV()

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

Splits a PeakMap into one PeakMap per FAIMS compensation voltage.

This only works with a PeakMap that has a FAIMS compensation voltage associated with each spectrum. The spectra from the original PeakMap are moved to new PeakMaps, so the original PeakMap is unusable afterwards.

Parameters
expThe PeakMap
Returns
Several maps, split by CVs
Exceptions
Exception::MissingInformationif exp is not FAIMS data

◆ splitByIonMobility() [1/2]

static MSExperiment splitByIonMobility ( MSExperiment &&  in,
UInt  number_of_bins = -1 
)
static

Expands all (TimsTOF) ion mobility frames in the PeakMap (i.e. all IM spectra with an IM float data array) into separate spectra. Non-IM spectra are simply copied to the result.

To get some coarser custom binning, choose a smaller number_of_bins. The default creates a new bin (=spectrum in the output) for each distinct ion mobility value. For custom bins, the IM range is divided into equally spaced bins and the bin center is the new drift time.

Parameters
inThe PeakMap containing IM-frame spectra
number_of_binsIn how many bins should the ion mobility frame be sliced? Default(-1) assigns all peaks with identical ion-mobility values to a separate spectrum.
Returns
All IM frames split into multiple bins (= 1 spectrum per bin)

◆ splitByIonMobility() [2/2]

static MSExperiment splitByIonMobility ( MSSpectrum  im_frame,
UInt  number_of_bins = -1 
)
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.

To get some coarser binning, choose a smaller number_of_bins. The default creates a new bin (=spectrum in the output) for each distinct ion mobility value.

Parameters
im_frameConcatenated spectrum representing a frame
number_of_binsIn how many bins should the ion mobility frame be sliced? Default(-1) assigns all peaks with identical ion-mobility values to a separate spectrum.
Returns
IM frame split into multiple bins (= 1 spectrum per bin)
Exceptions
Exception::MissingInformationif im_frame does not have IM data in floatDataArrays

Referenced by TOPPViewBase::showCurrentPeaksAsIonMobility().