FeatureFinderAlgorithmMetaboIdent#

class pyopenms.FeatureFinderAlgorithmMetaboIdent#

Bases: DefaultParamHandler

Perform targeted feature extraction of compounds provided as table and stores them in features

The algorithms detects quantitative features in MS1 data for a list of targets, typically small molecule/metabolite identifications Internally, it uses algorithms for targeted data analysis from the OpenSWATH pipeline In the simplest case, only CompoundName, SumFormula, Charge and RetentionTime need to be given, all other values may be zero Every combination of compound (mass), RT and charge defines one target for feature detection Output: The main output is a feature map of detected features, with annotations in meta data entries Additional outputs are the extracted chromatograms/peak groups, the assay in TraML compatible format, and transformations that contain the error between provided and observed peaks

Usage:

exp = MSExperiment()
MzMLFile().load(path_to_file, exp)
ff = FeatureFinderAlgorithmMetaboIdent()
ff.setMSData(exp)

fm = FeatureMap() # detected features will be stored here

library = []
# fill library with compounds: FeatureFinderMetaboIdentCompound(name, formula, mass, [charges], [RTs_in_sec], [RT_ranges], [isotope_distributions], [ion_mobilities], adduct)
# e.g. FeatureFinderMetaboIdentCompound('glucose','C6H12O6', 0.0, [-1], [123.4], [0.0], [0.0])

params = ff.getParameters() # optional!
params[param_name] = new_value # e.g. params[b'extract:n_isotopes'] = 3
ff.setParameters(params)

ff.run(library, fm, path_to_file)

# Alternatively (requires pandas), build the library from a DataFrame whose
# columns mirror the FeatureFinderMetaboIdent TSV, including the optional
# IonMobility and Adduct columns:
#   ff.run_from_df(df, fm, path_to_file)
# or build the compound list explicitly and inspect/round-trip it:
#   compounds = FeatureFinderAlgorithmMetaboIdent.compounds_from_df(df)
#   df2 = FeatureFinderAlgorithmMetaboIdent.compounds_to_df(compounds)

__init__() → None#

Methods

`__init__`()
`compounds_from_df`(df)	Convert a pandas DataFrame to a list of `FeatureFinderMetaboIdentCompound` objects.
`compounds_to_df`(compounds)	Convert a list of `FeatureFinderMetaboIdentCompound` objects to a DataFrame.
`getChromatograms`()	Retrieves chromatograms (empty if run was not executed)
`getDefaults`()	Returns the default parameters
`getLibrary`()	Retrieves the assay library (e.g., to store as TraML, empty if run was not executed)
`getMSData`()	Returns spectra
`getNShared`()	Retrieves number of features with shared identifications
`getName`()	Returns the name
`getParameters`()	Returns the parameters
`getSubsections`()
`getTransformations`()	Retrieves deviations between provided coordinates and extacted ones (e.g., to store as TrafoXML or for plotting)
`run`(metaboIdentTable, features[, spectra_file])	Perform targeted feature extraction of compounds and store them in features.
`run_from_df`(df, features[, spectra_path])	Run targeted feature extraction using compounds from a pandas DataFrame.
`setMSData`(m)	Sets spectra
`setName`(name)	Sets the name
`setParameters`(param)	Sets the parameters

static compounds_from_df(df)#

Convert a pandas DataFrame to a list of FeatureFinderMetaboIdentCompound objects.

Column names are case-insensitive and accept snake_case and common aliases (e.g. rt for RetentionTime, im for IonMobility). The columns mirror the input TSV of the FeatureFinderMetaboIdent TOPP tool.

Parameters#

dfpandas.DataFrame

Table with the following columns (required unless noted):

CompoundName (compound_name, name): str, unique identifier.
SumFormula (sum_formula, formula): str, chemical formula (may be empty if Mass is given).
Mass (mass): float, neutral mass; 0 = derive from formula.
Charge (charges): int, list[int], or comma-separated str.
RetentionTime (retention_time, rt): float, list[float], or comma-separated str.
RetentionTimeRange (rt_range): float/list/str; 0 = use the extract:rt_window parameter.
IsoDistribution (iso_distribution): float/list/str; 0 = calculate from formula.
IonMobility (ion_mobility, im) (optional): float/list/str; one value, or one per RT entry; absent or 0 disables IM filtering.
Adduct (adducts) (optional): str, e.g. "[M+H]+", "[M+Na]+", "[M-H]-"; if omitted, [M+H]+ / [M-H]- is assumed from charge polarity.

Returns#

list of FeatureFinderMetaboIdentCompound

Raises#

ValueError: If required columns are missing, two columns map to the same field, or a compound violates the contract: empty/duplicate name; empty Charge/RetentionTime; a zero charge; neither Mass > 0 nor a SumFormula; or a RetentionTimeRange/IonMobility whose length is neither 1 nor the number of retention times.
ImportError: If pandas or numpy are not installed.

Examples#

>>> import pandas as pd
>>> from pyopenms import FeatureFinderAlgorithmMetaboIdent
>>> df = pd.DataFrame({
...     'CompoundName': ['glucose', 'fructose'],
...     'SumFormula': ['C6H12O6', 'C6H12O6'],
...     'Mass': [0.0, 0.0],
...     'Charge': [-1, '-1,1'],
...     'RetentionTime': [123.4, '200.0,250.0'],
...     'RetentionTimeRange': [0.0, 0.0],
...     'IsoDistribution': [0.0, 0.0],
...     'IonMobility': [0.0, 0.95],   # optional
...     'Adduct': ['[M-H]-', ''],     # optional
... })
>>> compounds = FeatureFinderAlgorithmMetaboIdent.compounds_from_df(df)

static compounds_to_df(compounds)#

Convert a list of FeatureFinderMetaboIdentCompound objects to a DataFrame.

Inverse of compounds_from_df(): the returned DataFrame uses the canonical column names and can be fed straight back into compounds_from_df(). The multi-value fields (Charge, RetentionTime, RetentionTimeRange, IsoDistribution, IonMobility) are returned as Python lists; Adduct is a string.

Parameters#

compounds : iterable of FeatureFinderMetaboIdentCompound

Returns#

pandas.DataFrame: One row per compound, columns in canonical order.

Raises#

ImportError: If pandas is not installed.

Examples#

>>> df2 = FeatureFinderAlgorithmMetaboIdent.compounds_to_df(compounds)
>>> # round-trips back through compounds_from_df:
>>> compounds2 = FeatureFinderAlgorithmMetaboIdent.compounds_from_df(df2)

getChromatograms() → pyopenms.MSExperiment#: Retrieves chromatograms (empty if run was not executed)

getDefaults() → pyopenms.Param#: Returns the default parameters

getLibrary() → pyopenms.TargetedExperiment#: Retrieves the assay library (e.g., to store as TraML, empty if run was not executed)

getMSData() → pyopenms.MSExperiment#: Returns spectra

getNShared() → int#: Retrieves number of features with shared identifications

getName() → str#: Returns the name

getParameters() → pyopenms.Param#: Returns the parameters

getSubsections() → list[str]#

getTransformations() → pyopenms.TransformationDescription#: Retrieves deviations between provided coordinates and extacted ones (e.g., to store as TrafoXML or for plotting)

run(metaboIdentTable: collections.abc.Sequence[pyopenms.FeatureFinderMetaboIdentCompound], features: pyopenms.FeatureMap, spectra_file: str = '') → None#

Perform targeted feature extraction of compounds and store them in features.

If spectra_file is provided it will be used as a fall-back to setPrimaryMSRunPath in the feature map in case a proper primaryMSRunPath is not annotated in the MSExperiment. If there are no MS1 scans in the MSData, features will be returned unchanged.

Parameters:

metaboIdentTable – List of FeatureFinderMetaboIdentCompound objects defining targets
features – FeatureMap to store detected features (modified in-place)
spectra_file – Optional path to spectra file for annotation

run_from_df(df, features, spectra_path='')#

Run targeted feature extraction using compounds from a pandas DataFrame.

Convenience wrapper that combines compounds_from_df() and run(). The spectra must be set beforehand via setMSData().

Parameters#

dfpandas.DataFrame: Compound table (see compounds_from_df() for the accepted columns, including the optional IonMobility and Adduct columns).
featuresFeatureMap: Output map; detected features are stored here (modified in-place).
spectra_pathstr, optional: Path to the spectra file, used as a fallback for the primary MS run path annotated in the feature map.

Examples#

>>> exp = MSExperiment()
>>> MzMLFile().load("spectra.mzML", exp)
>>> ff = FeatureFinderAlgorithmMetaboIdent()
>>> ff.setMSData(exp)
>>> features = FeatureMap()
>>> ff.run_from_df(df, features, "spectra.mzML")

setMSData(m: pyopenms.MSExperiment) → None#
setMSData(m: pyopenms.MSExperiment) → None: Sets spectra

setName(name: str) → None#: Sets the name

setParameters(param: pyopenms.Param) → None#: Sets the parameters