Decharges a feature map by clustering charge variants of metabolites to zero-charge entities.
The Decharger uses an ILP approach to group charge variants of the same metabolite, which usually occur in ESI ionization mode. The resulting zero-charge metabolites, which are defined by RT and mass, are written to consensusXML. Intensities of charge variants are summed up. The position of the zero charge variant is the average of all clustered metabolites in each dimension (m and RT). For clustered metabolites, the reported m/z is thus their neutral mass. For unclusted features with known charge, a default adduct (protonation for positive mode, deprotonation for negative mode) is assumed to compute the neutral mass. For unclustered features without known charge, m/z zero is reported. It is also possible to include adducted species to the charge ladders (see 'potential_adducts' parameter). Via this mechanism it is also possible to use this tool to find pairs/triples/quadruples/... in labeled data (by specifing the mass tag weight as an adduct). If mass tags induce an RT shift (e.g. deuterium labeled data) you can also specify this also in the adduct list. This will allow to tighten the RT search window, thus reducing false positive results.
This tool is derived from the method described in the following publication:
Bielow C, Ruzek S, Huber CG, Reinert K. Optimal decharging and clustering of charge ladders generated in ESI-MS. J Proteome Res 2010; 9: 2688.
DOI: 10.1021/pr100177k
The command line parameters of this tool are:
MetaboliteAdductDecharger -- Decharges and merges different feature charge variants of the same metabolite.
Full documentation: http://www.openms.de/doxygen/release/3.2.0/html/TOPP_MetaboliteAdductDecharger.html
Version: 3.2.0 Nov 26 2024, 13:16:38, Revision: 962e60f
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:
MetaboliteAdductDecharger <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>* Input file (valid formats: 'featureXML')
-out_cm <file> Output consensus map (valid formats: 'consensusXML')
-out_fm <file> Output feature map (valid formats: 'featureXML')
-outpairs <file> Output file (valid formats: 'consensusXML')
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 Feature decharging algorithm 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/release/3.2.0/html/TOPP_MetaboliteAdductDecharger.html
INI file documentation of this tool:
Legend:
required parameter
advanced parameter
+MetaboliteAdductDechargerDecharges and merges different feature charge variants of the same metabolite.
version3.2.0
Version of the tool that generated this parameters file.
++1Instance '1' section for 'MetaboliteAdductDecharger'
in
input file input file*.featureXML
out_cm
output consensus mapoutput file*.consensusXML
out_fm
output feature mapoutput file*.featureXML
outpairs
output fileoutput file*.consensusXML
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
+++algorithmFeature decharging algorithm section
++++MetaboliteFeatureDeconvolution
charge_min1
Minimal possible charge
charge_max3
Maximal possible charge
charge_span_max3
Maximal range of charges for a single analyte, i.e. observing q1=[5,6,7] implies span=3. Setting this to 1 will only find adduct variants of the same charge1:∞
q_tryfeature
Try different values of charge for each feature according to the above settings ('heuristic' [does not test all charges, just the likely ones] or 'all' ), or leave feature charge untouched ('feature').feature, heuristic, all
retention_max_diff1.0
Maximum allowed RT difference between any two features if their relation shall be determined
retention_max_diff_local1.0
Maximum allowed RT difference between between two co-features, after adduct shifts have been accounted for (if you do not have any adduct shifts, this value should be equal to 'retention_max_diff', otherwise it should be smaller!)
mass_max_diff0.05
Maximum allowed mass tolerance per feature. Defines a symmetric tolerance window around the feature. When looking at possible feature pairs, the allowed feature-wise errors are combined for consideration of possible adduct shifts. For ppm tolerances, each window is based on the respective observed feature mz (instead of putative experimental mzs causing the observed one)!0.0:∞
unitDa
Unit of the 'max_difference' parameterDa, ppm
potential_adducts[H:+:0.4, Na:+:0.25, NH4:+:0.25, K:+:0.1, H-2O-1:0:0.05]
Adducts used to explain mass differences in format: 'Elements:Charge(+/-/0):Probability[:RTShift[:Label]]', i.e. the number of '+' or '-' indicate the charge ('0' if neutral adduct), e.g. 'Ca:++:0.5' indicates +2. Probabilites have to be in (0,1]. The optional RTShift param indicates the expected RT shift caused by this adduct, e.g. '(2)H4H-4:0:1:-3' indicates a 4 deuterium label, which causes early elution by 3 seconds. As fifth parameter you can add a label for every feature with this adduct. This also determines the map number in the consensus file. Adduct element losses are written in the form 'H-2'. All provided adducts need to have the same charge sign or be neutral! Mixing of adducts with different charge directions is only allowed as neutral complexes. For example, 'H-1Na:0:0.05' can be used to model Sodium gains (with balancing deprotonation) in negative mode.
max_neutrals1
Maximal number of neutral adducts(q=0) allowed. Add them in the 'potential_adducts' section!
use_minority_boundtrue
Prune the considered adduct transitions by transition probabilities.true, false
max_minority_bound3
Limits allowed adduct compositions and changes between compositions in the underlying graph optimization problem by introducing a probability-based threshold: the minority bound sets the maximum count of the least probable adduct (according to 'potential_adducts' param) within a charge variant with maximum charge only containing the most likely adduct otherwise. E.g., for 'charge_max' 4 and 'max_minority_bound' 2 with most probable adduct being H+ and least probable adduct being Na+, this will allow adduct compositions of '2(H+),2(Na+)' but not of '1(H+),3(Na+)'. Further, adduct compositions/changes less likely than '2(H+),2(Na+)' will be discarded as well.0:∞
min_rt_overlap0.66
Minimum overlap of the convex hull' RT intersection measured against the union from two features (if CHs are given)0.0:1.0
intensity_filterfalse
Enable the intensity filter, which will only allow edges between two equally charged features if the intensity of the feature with less likely adducts is smaller than that of the other feature. It is not used for features of different charge.true, false
negative_modefalse
Enable negative ionization mode.true, false
default_map_labeldecharged features
Label of map in output consensus file where all features are put by default
verbose_level0
Amount of debug information given during processing.0:3
1.9.1