FeatureFinderMetabo

FeatureFinderMetabo assembles metabolite features from singleton mass traces.

pot. predecessor tools	→ FeatureFinderMetabo →	pot. successor tools
PeakPickerHiRes		TextExporter
PeakPickerHiRes

Mass traces alone would allow for further analysis such as metabolite ID or statistical evaluation. However, in general, monoisotopic mass traces are accompanied by satellite C13 peaks and thus may render the analysis more difficult. FeatureFinderMetabo fulfills a further data reduction step by assembling compatible mass traces to metabolite features (that is, all mass traces originating from one metabolite). To this end, multiple metabolite hypotheses are formulated and scored according to how well differences in RT (optional), m/z or intensity ratios match to those of theoretical isotope patterns.

If the raw data scans contain the scan polarity information, it is stored as meta value "scan_polarity" in the output file.

Mass trace clustering can be done using either 13C distances or a linear model (Kenar et al) – see parameter 'ffm:mz_scoring_13C'. Generally, for lipidomics, use 13C, since lipids contain a lot of 13C. For general metabolites, the linear model is usually more appropriate. To decide what is better, the total number of features can be used as indirect measure

• the lower(!) the better (since more mass traces are assembled into single features). Detailed information is stored in the featureXML output: it contains meta-values for each feature about the mass trace differences (inspectable via TOPPView). If you want this in a tabular format, use TextExporter, i.e.,

  TextExporter.exe -feature:add_metavalues 1 -in <ff_metabo.featureXML> -out <ff_metabo.csv>

  By default, the linear model is used.

The command line parameters of this tool are:

FeatureFinderMetabo -- Assembles metabolite features from centroided (LC-)MS data using the mass trace approa
ch.
Full documentation: http://www.openms.de/doxygen/nightly/html/TOPP_FeatureFinderMetabo.html
Version: 3.5.0-pre-nightly-2025-12-01 Dec  2 2025, 02:56:09, Revision: 957e70b
To cite OpenMS:
 + Pfeuffer, J., Bielow, C., Wein, S. et al.. OpenMS 3 enables reproducible analysis of large-scale mass spec
   trometry data. Nat Methods (2024). doi:10.1038/s41592-024-02197-7.

Usage:
  FeatureFinderMetabo <options>

This tool has algorithm parameters that are not shown here! Please check the ini file for a detailed descript
ion or use the --helphelp option

Options (mandatory options marked with '*'):
  -in <file>*                         Centroided mzML file (valid formats: 'mzML')
  -out <file>*                        FeatureXML file with metabolite features (valid formats: 'featureXML')
  -out_chrom <file>                   Optional mzML file with chromatograms (valid formats: 'mzML')
                                      
  -faims_merge_features <true/false>  For FAIMS data with multiple compensation voltages: Merge features repr
                                      esenting the same analyte detected at different CV values into a single
                                       feature. Only features with DIFFERENT FAIMS CV values are merged (same
                                       CV = different analytes). Has no effect on non-FAIMS data. (default: 
                                      'true') (valid: 'true', 'false')
                                      
                                      
Common TOPP 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)

The following configuration subsections are valid:
 - algorithm   Algorithm parameters section

You can write an example INI file using the '-write_ini' option.
Documentation of subsection parameters can be found in the doxygen documentation or the INIFileEditor.
For more information, please consult the online documentation for this tool:
  - http://www.openms.de/doxygen/nightly/html/TOPP_FeatureFinderMetabo.html

INI file documentation of this tool:

Legend:

required parameter

advanced parameter

+FeatureFinderMetaboAssembles metabolite features from centroided (LC-)MS data using the mass trace approach.

version3.5.0-pre-nightly-2025-12-01 Version of the tool that generated this parameters file.

++1Instance '1' section for 'FeatureFinderMetabo'

in Centroided mzML fileinput file*.mzML

out FeatureXML file with metabolite featuresoutput file*.featureXML

out_chrom Optional mzML file with chromatogramsoutput file*.mzML

faims_merge_featurestrue For FAIMS data with multiple compensation voltages: Merge features representing the same analyte detected at different CV values into a single feature. Only features with DIFFERENT FAIMS CV values are merged (same CV = different analytes). Has no effect on non-FAIMS data.true, false

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

+++algorithmAlgorithm parameters section

++++commonCommon parameters for all other subsections

noise_threshold_int10.0 Intensity threshold below which peaks are regarded as noise.

chrom_peak_snr3.0 Minimum signal-to-noise a mass trace should have.

chrom_fwhm5.0 Expected chromatographic peak width (in seconds).

++++mtdMass Trace Detection parameters

mass_error_ppm20.0 Allowed mass deviation (in ppm).

ion_mobility_tolerance0.01 Allowed ion mobility deviation (in 1/k0).

reestimate_mt_sdtrue Enables dynamic re-estimation of m/z variance during mass trace collection stage.true, false

quant_methodarea Method of quantification for mass traces. For LC data 'area' is recommended, 'median' for direct injection data. 'max_height' simply uses the most intense peak in the trace.area, median, max_height

trace_termination_criterionoutlier Termination criterion for the extension of mass traces. In 'outlier' mode, trace extension cancels if a predefined number of consecutive outliers are found (see trace_termination_outliers parameter). In 'sample_rate' mode, trace extension in both directions stops if ratio of found peaks versus visited spectra falls below the 'min_sample_rate' threshold.outlier, sample_rate

trace_termination_outliers5 Mass trace extension in one direction cancels if this number of consecutive spectra with no detectable peaks is reached.

min_sample_rate0.5 Minimum fraction of scans along the mass trace that must contain a peak.

min_trace_length5.0 Minimum expected length of a mass trace (in seconds).

max_trace_length-1.0 Maximum expected length of a mass trace (in seconds). Set to a negative value to disable maximal length check during mass trace detection.

++++epdElution Profile Detection (to separate isobaric Mass Traces by elution time).

enabledtrue Enable splitting of isobaric mass traces by chromatographic peak detection. Disable for direct injection.true, false

width_filteringfixed Enable filtering of unlikely peak widths. The fixed setting filters out mass traces outside the [min_fwhm, max_fwhm] interval (set parameters accordingly!). The auto setting filters with the 5 and 95% quantiles of the peak width distribution.off, fixed, auto

min_fwhm1.0 Minimum full-width-at-half-maximum of chromatographic peaks (in seconds). Ignored if parameter width_filtering is off or auto.

max_fwhm60.0 Maximum full-width-at-half-maximum of chromatographic peaks (in seconds). Ignored if parameter width_filtering is off or auto.

masstrace_snr_filteringfalse Apply post-filtering by signal-to-noise ratio after smoothing.true, false

++++ffmFeatureFinder parameters (assembling mass traces to charged features)

local_rt_range10.0 RT range where to look for coeluting mass traces

local_mz_range6.5 MZ range where to look for isotopic mass traces

charge_lower_bound1 Lowest charge state to consider

charge_upper_bound3 Highest charge state to consider

report_summed_intsfalse Set to true for a feature intensity summed up over all traces rather than using monoisotopic trace intensity alone.false, true

enable_RT_filteringtrue Require sufficient overlap in RT while assembling mass traces. Disable for direct injection data..false, true

isotope_filtering_modelmetabolites (5% RMS) Remove/score candidate assemblies based on isotope intensities. SVM isotope models for metabolites were trained with either 2% or 5% RMS error. For peptides, an averagine cosine scoring is used. Select the appropriate noise model according to the quality of measurement or MS device.metabolites (2% RMS), metabolites (5% RMS), peptides, none

mz_scoring_13Cfalse Use the 13C isotope peak position (~1.003355 Da) as the expected shift in m/z for isotope mass traces (highly recommended for lipidomics!). Disable for general metabolites (as described in Kenar et al. 2014, MCP.).false, true

use_smoothed_intensitiestrue Use LOWESS intensities instead of raw intensities.false, true

report_smoothed_intensitiestrue Report smoothed intensities (only if use_smoothed_intensities is true).false, true

report_convex_hullsfalse Augment each reported feature with the convex hull of the underlying mass traces (increases featureXML file size considerably).false, true

remove_single_tracesfalse Remove unassembled traces (single traces).false, true

mz_scoring_by_elementsfalse Use the m/z range of the assumed elements to detect isotope peaks. A expected m/z range is computed from the isotopes of the assumed elements. If enabled, this ignores 'mz_scoring_13C'false, true

elementsCHNOPS Elements assumes to be present in the sample (this influences isotope detection).