Detects features in MS1 data corresponding to small molecule identifications.

pot. predecessor tools	$\longrightarrow$ FeatureFinderMetaboIdent $\longrightarrow$	pot. successor tools
PeakPickerHiRes (optional)		TextExporter

This tool detects quantitative features in MS1 data for a list of targets, typically small molecule/metabolite identifications. It uses algorithms for targeted data analysis from the OpenSWATH pipeline.

Note: This tool is still experimental!

See also: FeatureFinderIdentification - targeted feature detection based on peptide identifications.

Input format

The targets to quantify have to be specified in a tab-separated text file that is passed via the id parameter. This file has to start with the following header line, defining its columns:

CompoundName    SumFormula    Mass    Charge    RetentionTime    RetentionTimeRange    IsoDistribution

Every subsequent line defines a target. (Except lines starting with "#", which are considered as comments and skipped.) The following requirements apply:

CompoundName: unique name for the target compound
SumFormula: chemical sum formula (see OpenMS::EmpiricalFormula), optional
Mass: neutral mass; if zero calculated from Formula
Charge: charge state, or comma-separated list of multiple charges
RetentionTime: retention time (RT), or comma-separated list of multiple RTs
RetentionTimeRange: RT window around RetentionTime for chromatogram extraction, either one value or one per RT entry; if zero parameter extract:rt_window is used
IsoDistribution: comma-separated list of relative abundances of isotopologues (see OpenMS::IsotopeDistribution); if zero calculated from Formula

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 format

The main output (parameter out) is a featureXML file containing the detected features, with annotations in meta data entries. This file can be visualized in TOPPView - perhaps most usefully as a layer on top of the LC-MS data that gave rise to it. Compound annotations of features (Name entries from the id input) can be shown by clicking the "Show feature annotation" button in the tool bar and selecting "Label meta data". Positions of targets for which no feature was detected can be shown by clicking the "Show unassigned peptide identifications" button and selecting "Show label meta data".

To export the data from the featureXML file to a tabular text file (CSV), use TextExporter with the options no_ids and feature:add_metavalues 0 (to include all meta data annotations). In the result, the information from the CompoundName, SumFormula, Charge and RetentionTime columns from the input will be in the label, sum_formula, charge and expected_rt columns, respectively.

The command line parameters of this tool are:

FeatureFinderMetaboIdent -- Detects features in MS1 data based on metabolite identifications.
Full documentation: http://www.openms.de/documentation/UTILS_FeatureFinderMetaboIdent.html
Version: 2.6.0 Sep 30 2020, 12:54:34, Revision: c26f752
To cite OpenMS:
  Rost HL, Sachsenberg T, Aiche S, Bielow C et al.. OpenMS: a flexible open-source software platform for mass spectrometry data analysis. Nat Meth. 2016; 13, 9: 741-748. doi:10.1038/nmeth.3959.

Usage:
  FeatureFinderMetaboIdent <options>

Options (mandatory options marked with '*'):
  -in <file>*                   Input file: LC-MS raw data (valid formats: 'mzML')
  -id <file>*                   Input file: Metabolite identifications (valid formats: 'tsv')
  -out <file>*                  Output file: Features (valid formats: 'featureXML')
  -lib_out <file>               Output file: Assay library (valid formats: 'traML')
  -chrom_out <file>             Output file: Chromatograms (valid formats: 'mzML')
  -candidates_out <file>        Output file: Feature candidates (before filtering and model fitting) (valid 
                                formats: 'featureXML')
  -trafo_out <file>             Output file: Retention times (expected vs. observed) (valid formats: 'trafoXM
                                L')

Parameters for ion chromatogram extraction:
  -extract:mz_window <value>    M/z window size for chromatogram extraction (unit: ppm if 1 or greater, else 
                                Da/Th) (default: '10.0' min: '0.0')
  -extract:n_isotopes <number>  Number of isotopes to include in each assay. (default: '2' min: '2')
  -extract:rt_window <value>    RT window size (in sec.) for chromatogram extraction. If zero, calculated 
                                based on 'detect:peak_width'. (default: '0.0' min: '0.0')

Parameters for detecting features in extracted ion chromatograms:
  -detect:peak_width <value>    Expected elution peak width in seconds, for smoothing (Gauss filter). Also 
                                determines the RT extration window, unless set explicitly via 'extract:rt_win
                                dow'. (default: '5.0' min: '0.0')

Parameters for fitting elution models to features:
  -model:type <choice>          Type of elution model to fit to features (default: 'symmetric' valid: 'symmet
                                ric', 'asymmetric', 'none')

                                
Common UTIL options:
  -ini <file>                   Use the given TOPP INI file
  -threads <n>                  Sets the number of threads allowed to be used by the TOPP tool (default: '1')
  -write_ini <file>             Writes the default configuration file
  --help                        Shows options
  --helphelp                    Shows all options (including advanced)

INI file documentation of this tool:

Legend:

required parameter

advanced parameter

+FeatureFinderMetaboIdentDetects features in MS1 data based on metabolite identifications.

version2.6.0 Version of the tool that generated this parameters file.

++1Instance '1' section for 'FeatureFinderMetaboIdent'

in Input file: LC-MS raw datainput file*.mzML

id Input file: Metabolite identificationsinput file*.tsv

out Output file: Featuresoutput file*.featureXML

lib_out Output file: Assay libraryoutput file*.traML

chrom_out Output file: Chromatogramsoutput file*.mzML

candidates_out Output file: Feature candidates (before filtering and model fitting)output file*.featureXML

trafo_out Output file: Retention times (expected vs. observed)output file*.trafoXML

log Name of log file (created only when specified)

debug0 Sets the debug level

threads1 Sets the number of threads allowed to be used by the TOPP tool

no_progressfalse Disables progress logging to command linetrue,false

forcefalse Overrides tool-specific checkstrue,false

testfalse Enables the test mode (needed for internal use only)true,false

+++extractParameters for ion chromatogram extraction

mz_window10.0 m/z window size for chromatogram extraction (unit: ppm if 1 or greater, else Da/Th)0.0:∞

n_isotopes2 Number of isotopes to include in each assay.2:∞

isotope_pmin0.0 Minimum probability for an isotope to be included in the assay for a compound. If set, this parameter takes precedence over 'extract:n_isotopes'.0.0:1.0

rt_window0.0 RT window size (in sec.) for chromatogram extraction. If zero, calculated based on 'detect:peak_width'.0.0:∞

+++detectParameters for detecting features in extracted ion chromatograms

peak_width5.0 Expected elution peak width in seconds, for smoothing (Gauss filter). Also determines the RT extration window, unless set explicitly via 'extract:rt_window'.0.0:∞

min_peak_width0.2 Minimum elution peak width. Absolute value in seconds if 1 or greater, else relative to 'peak_width'.0.0:∞

signal_to_noise0.8 Signal-to-noise threshold for OpenSWATH feature detection0.1:∞

+++modelParameters for fitting elution models to features

typesymmetric Type of elution model to fit to featuressymmetric,asymmetric,none

add_zeros0.2 Add zero-intensity points outside the feature range to constrain the model fit. This parameter sets the weight given to these points during model fitting; '0' to disable.0.0:∞

unweighted_fitfalse Suppress weighting of mass traces according to theoretical intensities when fitting elution modelstrue,false

no_imputationfalse If fitting the elution model fails for a feature, set its intensity to zero instead of imputing a value from the initial intensity estimatetrue,false

each_tracefalse Fit elution model to each individual mass tracetrue,false

++++checkParameters for checking the validity of elution models (and rejecting them if necessary)

min_area1.0 Lower bound for the area under the curve of a valid elution model0.0:∞

boundaries0.5 Time points corresponding to this fraction of the elution model height have to be within the data region used for model fitting0.0:1.0

width10.0 Upper limit for acceptable widths of elution models (Gaussian or EGH), expressed in terms of modified (median-based) z-scores. '0' to disable. Not applied to individual mass traces (parameter 'each_trace').0.0:∞

asymmetry10.0 Upper limit for acceptable asymmetry of elution models (EGH only), expressed in terms of modified (median-based) z-scores. '0' to disable. Not applied to individual mass traces (parameter 'each_trace').0.0:∞