| OpenMS 2.5.0

MapAlignerPoseClustering

Corrects retention time distortions between maps, using a pose clustering approach.

potential predecessor tools | MapAlignerPoseClustering | potential successor tools
FeatureFinderCentroided (or another feature finding algorithm) | FeatureLinkerUnlabeled or FeatureLinkerUnlabeledQT

This tool provides an algorithm to align the retention time scales of multiple input files, correcting shifts and distortions between them. Retention time adjustment may be necessary to correct for chromatography differences e.g. before data from multiple LC-MS runs can be combined (feature grouping), or when one run should be annotated with peptide identifications obtained in a different run.

All map alignment tools (MapAligner...) collect retention time data from the input files and - by fitting a model to this data - compute transformations that map all runs to a common retention time scale. They can apply the transformations right away and return output files with aligned time scales (parameter `out`), and/or return descriptions of the transformations in trafoXML format (parameter `trafo_out`). Transformations stored as trafoXML can be applied to arbitrary files with the MapRTTransformer tool.

The map alignment tools differ in how they obtain retention time data for the modeling of transformations, and consequently what types of data they can be applied to. The alignment algorithm implemented here is the pose clustering algorithm as described in doi:10.1093/bioinformatics/btm209. It is used to find an affine transformation, which is further refined by a feature grouping step. This algorithm can be applied to features (featureXML) and peaks (mzML), but it has mostly been developed and tested on features. For more details and algorithm-specific parameters (set in the INI file) see "Detailed Description" in the algorithm documentation.

See also
  MapAlignerPoseClustering MapAlignerSpectrum MapRTTransformer

This algorithm uses an affine transformation model.

To speed up the alignment, consider reducing 'max_number_of_peaks_considered'. If your alignment is not good enough, consider increasing this number (the alignment will take longer though).

The command line parameters of this tool are:

    MapAlignerPoseClustering -- Corrects retention time distortions between maps using a pose clustering approach

    .

    Full documentation: http://www.openms.de/documentation/TOPP_MapAlignerPoseClustering.html

    Version: 2.5.0-GIT-NOTFOUND-GIT-NOTFOUND Sep 10 2020, 12:20:39, Revision: GIT-NOTFOUND

    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:

      MapAlignerPoseClustering <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 <files>*               Input files to align (all must have the same file type) (valid formats: 'feature

                                 XML', 'mzML')

      -out <files>               Output files (same file type as 'in'). This option or 'trafo_out' has to be prov

                                 ided; they can be used together. (valid formats: 'featureXML', 'mzML')

      -trafo_out <files>         Transformation output files. This option or 'out' has to be provided; they can

                                 be used together. (valid formats: 'trafoXML')

    Options to define a reference file (use either 'file' or 'index', not both):

      -reference:file <file>     File to use as reference (same file format as input files required) (valid forma

                                 ts: 'featureXML', 'mzML')

      -reference:index <number>  Use one of the input files as reference ('1' for the first file, etc.).

                                 If '0', no explicit reference is set - the algorithm will select a reference. (

                                 default: '0' min: '0')

    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/documentation/TOPP_MapAlignerPoseClustering.html

INI file documentation of this tool:

Legend:
required parameter
advanced parameter
+MapAlignerPoseClustering Corrects retention time distortions between maps using a pose clustering approach.
version 2.5.0-GIT-NOTFOUND-GIT-NOTFOUND Version of the tool that generated this parameters file.
++1 Instance '1' section for 'MapAlignerPoseClustering'
in[] Input files to align (all must have the same file type)input file*.featureXML,*.mzML
out[] Output files (same file type as 'in'). This option or 'trafo_out' has to be provided; they can be used together.output file*.featureXML,*.mzML
trafo_out[] Transformation output files. This option or 'out' has to be provided; they can be used together.output file*.trafoXML
log Name of log file (created only when specified)
debug 0 Sets the debug level
threads 1 Sets the number of threads allowed to be used by the TOPP tool
no_progress false Disables progress logging to command line true,false
force false Overwrite tool specific checks.true,false
test false Enables the test mode (needed for internal use only)true,false
+++reference Options to define a reference file (use either 'file' or 'index', not both)
file File to use as reference (same file format as input files required)input file*.featureXML,*.mzML
index 0 Use one of the input files as reference ('1' for the first file, etc.).
If '0', no explicit reference is set - the algorithm will select a reference.0:∞
+++algorithm Algorithm parameters section
max_num_peaks_considered 1000 The maximal number of peaks/features to be considered per map. To use all, set to '-1'.-1:∞
++++superimposer
mz_pair_max_distance 0.5 Maximum of m/z deviation of corresponding elements in different maps. This condition applies to the pairs considered in hashing.0.0:∞
rt_pair_distance_fraction 0.1 Within each of the two maps, the pairs considered for pose clustering must be separated by at least this fraction of the total elution time interval (i.e., max - min). 0.0:1.0
num_used_points 2000 Maximum number of elements considered in each map (selected by intensity). Use this to reduce the running time and to disregard weak signals during alignment. For using all points, set this to -1.-1:∞
scaling_bucket_size 0.005 The scaling of the retention time interval is being hashed into buckets of this size during pose clustering. A good choice for this would be a bit smaller than the error you would expect from repeated runs.0.0:∞
shift_bucket_size 3.0 The shift at the lower (respectively, higher) end of the retention time interval is being hashed into buckets of this size during pose clustering. A good choice for this would be about the time between consecutive MS scans.0.0:∞
max_shift 1000.0 Maximal shift which is considered during histogramming (in seconds). This applies for both directions.0.0:∞
max_scaling 2.0 Maximal scaling which is considered during histogramming. The minimal scaling is the reciprocal of this.1.0:∞
dump_buckets [DEBUG] If non-empty, base filename where hash table buckets will be dumped to. A serial number for each invocation will be appended automatically.
dump_pairs [DEBUG] If non-empty, base filename where the individual hashed pairs will be dumped to (large!). A serial number for each invocation will be appended automatically.
++++pairfinder
second_nearest_gap 2.0 Only link features whose distance to the second nearest neighbors (for both sides) is larger by 'second_nearest_gap' than the distance between the matched pair itself.1.0:∞
use_identifications false Never link features that are annotated with different peptides (features without ID's always match; only the best hit per peptide identification is considered).true,false
ignore_charge false false [default]: pairing requires equal charge state (or at least one unknown charge '0'); true: Pairing irrespective of charge state true,false
ignore_adduct true true [default]: pairing requires equal adducts (or at least one without adduct annotation); true: Pairing irrespective of adducts true,false
+++++distance_RT Distance component based on RT differences
max_difference 100.0 Never pair features with a larger RT distance (in seconds).0.0:∞
exponent 1.0 Normalized RT differences ([0-1], relative to 'max_difference') are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)0.0:∞
weight 1.0 Final RT distances are weighted by this factor 0.0:∞
+++++distance_MZ Distance component based on m/z differences
max_difference 0.3 Never pair features with larger m/z distance (unit defined by 'unit')0.0:∞
unit Da Unit of the 'max_difference' parameter Da,ppm
exponent 2.0 Normalized ([0-1], relative to 'max_difference') m/z differences are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)0.0:∞
weight 1.0 Final m/z distances are weighted by this factor 0.0:∞
+++++distance_intensity Distance component based on differences in relative intensity (usually relative to highest peak in the whole data set)
exponent 1.0 Differences in relative intensity ([0-1]) are raised to this power (using 1 or 2 will be fast, everything else is REALLY slow)0.0:∞
weight 0.0 Final intensity distances are weighted by this factor 0.0:∞
log_transform disabled Log-transform intensities? If disabled, d = |int_f2 - int_f1| / int_max. If enabled, d = |log(int_f2 + 1) - log(int_f1 + 1)| / log(int_max + 1))enabled,disabled