OpenMS
InternalCalibration Class Reference

A mass recalibration method using linear/quadratic interpolation (robust/weighted) of given reference masses. More...

#include <OpenMS/FILTERING/CALIBRATION/InternalCalibration.h>

Inheritance diagram for InternalCalibration:
[legend]
Collaboration diagram for InternalCalibration:
[legend]

Classes

struct  CalibrantStats_
 statistics when adding peptide calibrants More...
 
struct  LockMass
 helper class, describing a lock mass More...
 

Public Member Functions

 InternalCalibration ()
 Default constructor. More...
 
 ~InternalCalibration () override
 Destructor. More...
 
Size fillCalibrants (const PeakMap &exp, const std::vector< InternalCalibration::LockMass > &ref_masses, double tol_ppm, bool lock_require_mono, bool lock_require_iso, CalibrationData &failed_lock_masses, bool verbose=true)
 Extract calibrants from Raw data (mzML) More...
 
Size fillCalibrants (const FeatureMap &fm, double tol_ppm)
 Extract calibrants from identifications. More...
 
Size fillCalibrants (const std::vector< PeptideIdentification > &pep_ids, double tol_ppm)
 Extract calibrants from identifications. More...
 
const CalibrationDatagetCalibrationPoints () const
 Get container of calibration points. More...
 
bool calibrate (PeakMap &exp, const IntList &target_mslvl, MZTrafoModel::MODELTYPE model_type, double rt_chunk, bool use_RANSAC, double post_ppm_median, double post_ppm_MAD, const String &file_models="", const String &file_models_plot="", const String &file_residuals="", const String &file_residuals_plot="", const String &rscript_executable="Rscript")
 Apply calibration to data. More...
 
- Public Member Functions inherited from ProgressLogger
 ProgressLogger ()
 Constructor. More...
 
virtual ~ProgressLogger ()
 Destructor. More...
 
 ProgressLogger (const ProgressLogger &other)
 Copy constructor. More...
 
ProgressLoggeroperator= (const ProgressLogger &other)
 Assignment Operator. More...
 
void setLogType (LogType type) const
 Sets the progress log that should be used. The default type is NONE! More...
 
LogType getLogType () const
 Returns the type of progress log being used. More...
 
void startProgress (SignedSize begin, SignedSize end, const String &label) const
 Initializes the progress display. More...
 
void setProgress (SignedSize value) const
 Sets the current progress. More...
 
void endProgress () const
 Ends the progress display. More...
 
void nextProgress () const
 increment progress by 1 (according to range begin-end) More...
 

Static Public Member Functions

static void applyTransformation (std::vector< Precursor > &pcs, const MZTrafoModel &trafo)
 Transform a precursor's m/z. More...
 
static void applyTransformation (PeakMap::SpectrumType &spec, const IntList &target_mslvl, const MZTrafoModel &trafo)
 Transform a spectrum (data+precursor) More...
 
static void applyTransformation (PeakMap &exp, const IntList &target_mslvl, const MZTrafoModel &trafo)
 Transform spectra from a whole map (data+precursor) More...
 

Protected Member Functions

void fillID_ (const PeptideIdentification &pep_id, const double tol_ppm, CalibrantStats_ &stats)
 Add(no prior clear) calibrants to internal list. More...
 
void fillIDs_ (const std::vector< PeptideIdentification > &pep_ids, const double tol_ppm, CalibrantStats_ &stats)
 calls fillID_ on all PeptideIDs More...
 
bool isDecalibrated_ (const PeptideIdentification &pep_id, const double mz_obs, const double tol_ppm, CalibrantStats_ &stats, double &mz_ref)
 determine if sequence is within tol_ppm and update stats; fills mz_ref with the theoretical m/z of the sequence More...
 

Static Protected Member Functions

static void applyTransformation_ (PeakMap::SpectrumType &spec, const MZTrafoModel &trafo)
 Calibrate m/z of a spectrum, ignoring precursors! More...
 
- Static Protected Member Functions inherited from ProgressLogger
static String logTypeToFactoryName_ (LogType type)
 Return the name of the factory product used for this log type. More...
 

Private Attributes

CalibrationData cal_data_
 

Additional Inherited Members

- Public Types inherited from ProgressLogger
enum  LogType { CMD , GUI , NONE }
 Possible log types. More...
 
- Protected Attributes inherited from ProgressLogger
LogType type_
 
time_t last_invoke_
 
ProgressLoggerImplcurrent_logger_
 
- Static Protected Attributes inherited from ProgressLogger
static int recursion_depth_
 

Detailed Description

A mass recalibration method using linear/quadratic interpolation (robust/weighted) of given reference masses.

...

Constructor & Destructor Documentation

◆ InternalCalibration()

Default constructor.

◆ ~InternalCalibration()

~InternalCalibration ( )
inlineoverride

Destructor.

Member Function Documentation

◆ applyTransformation() [1/3]

static void applyTransformation ( PeakMap exp,
const IntList target_mslvl,
const MZTrafoModel trafo 
)
static

Transform spectra from a whole map (data+precursor)

All data peaks and precursor information (if present) are calibrated in m/z.

Only spectra whose MS-level is contained in 'target_mslvl' are calibrated. In addition, if a fragmentation spectrum's precursor information originates from an MS level in 'target_mslvl', the precursor (not the spectrum itself) is also subjected to calibration. E.g., If we only have MS and MS/MS spectra: for 'target_mslvl' = {1} then all MS1 spectra and MS2 precursors are calibrated. If 'target_mslvl' = {2}, only MS2 spectra (not their precursors) are calibrated. If 'target_mslvl' = {1,2} all spectra and precursors are calibrated.

Parameters
expUncalibrated peak map
target_mslvlList (can be unsorted) of MS levels to calibrate
trafoThe calibration function to apply

◆ applyTransformation() [2/3]

static void applyTransformation ( PeakMap::SpectrumType spec,
const IntList target_mslvl,
const MZTrafoModel trafo 
)
static

Transform a spectrum (data+precursor)

See applyTransformation(MSExperiment, ...) for details.

Parameters
specUncalibrated MSSpectrum
target_mslvlList (can be unsorted) of MS levels to calibrate
trafoThe calibration function to apply

◆ applyTransformation() [3/3]

static void applyTransformation ( std::vector< Precursor > &  pcs,
const MZTrafoModel trafo 
)
static

Transform a precursor's m/z.

Calibrate m/z of precursors.

Parameters
pcsUncalibrated Precursors
trafoThe calibration function to apply

◆ applyTransformation_()

static void applyTransformation_ ( PeakMap::SpectrumType spec,
const MZTrafoModel trafo 
)
staticprotected

Calibrate m/z of a spectrum, ignoring precursors!

This method is not exposed as public, because its easy to be misused on spectra while forgetting about the precursors of high-level spectra.

◆ calibrate()

bool calibrate ( PeakMap exp,
const IntList target_mslvl,
MZTrafoModel::MODELTYPE  model_type,
double  rt_chunk,
bool  use_RANSAC,
double  post_ppm_median,
double  post_ppm_MAD,
const String file_models = "",
const String file_models_plot = "",
const String file_residuals = "",
const String file_residuals_plot = "",
const String rscript_executable = "Rscript" 
)

Apply calibration to data.

For each spectrum, a calibration model will be computed and applied. Make sure to call fillCalibrants() before, so a model can be created.

The MSExperiment will be sorted by RT and m/z if unsorted.

Parameters
expMSExperiment holding the Raw data to calibrate
target_mslvlMS-levels where calibration should be applied to
model_typeLinear or quadratic model; select based on your instrument
rt_chunkRT-window size (one-sided) of calibration points to collect around each spectrum. Set to negative values, to build one global model instead.
use_RANSACRemove outliers before fitting a model?!
post_ppm_medianThe median ppm error of the calibrants must be at least this good after calibration; otherwise this method returns false(fail)
post_ppm_MADThe median absolute deviation of the calibrants must be at least this good after calibration; otherwise this method returns false(fail)
file_modelsOutput CSV filename, where model parameters are written to (pass empty string to skip)
file_models_plotOutput PNG image model parameters (pass empty string to skip)
file_residualsOutput CSV filename, where ppm errors of calibrants before and after model fitting parameters are written to (pass empty string to skip)
file_residuals_plotOutput PNG image of the ppm errors of calibrants (pass empty string to skip)
rscript_executableFull path to the Rscript executable
Returns
true upon successful calibration

◆ fillCalibrants() [1/3]

Size fillCalibrants ( const FeatureMap fm,
double  tol_ppm 
)

Extract calibrants from identifications.

Extracts only the first hit from the first peptide identification of each feature. Hits are sorted beforehand. Ambiguities should be resolved before, e.g. using IDFilter. RT and m/z are taken from the features, not from the identifications (for an exception see below)!

Unassigned peptide identifications are also taken into account! RT and m/z are naturally taken from the IDs, since to feature is assigned. If you do not want these IDs, remove them from the feature map before calling this function.

A filtering step is done in the m/z dimension using tol_ppm. Since precursor masses could be annotated wrongly (e.g. isotope peak instead of mono), larger outliers are removed before accepting an ID as calibrant.

Parameters
fmFeatureMap with peptide identifications
tol_ppmOnly accept ID's whose theoretical mass deviates at most this much from annotated
Returns
Number of calibration masses found

◆ fillCalibrants() [2/3]

Size fillCalibrants ( const PeakMap exp,
const std::vector< InternalCalibration::LockMass > &  ref_masses,
double  tol_ppm,
bool  lock_require_mono,
bool  lock_require_iso,
CalibrationData failed_lock_masses,
bool  verbose = true 
)

Extract calibrants from Raw data (mzML)

Lock masses are searched in each spectrum and added to the internal calibrant database.

Filters can be used to exclude spurious peaks, i.e. require the calibrant peak to be monoisotopic or to have a +1 isotope (should not be used for very low abundant calibrants). If a calibrant is not found, it is added to a 'failed_lock_masses' database which is returned and not stored internally. The intensity of the peaks describe the reason for failed detection: 0.0 - peak not found with the given ppm tolerance; 1.0 - peak is not monoisotopic (can only occur if 'lock_require_mono' is true) 2.0 - peak has no +1 isotope (can only occur if 'lock_require_iso' is true)

Parameters
expPeak map containing the lock masses
ref_massesList of lock masses
tol_ppmSearch window for lock masses in 'exp'
lock_require_monoRequire that a lock mass is the monoisotopic peak (i.e. not an isotope peak) – lock mass is rejected otherwise
lock_require_isoRequire that a lock mass has isotope peaks to its right – lock mass is rejected otherwise
failed_lock_massesSet of calibration masses which were not found, i.e. their expected m/z and RT positions;
verbosePrint information on 'lock_require_XXX' matches during search
Returns
Number of calibration masses found

◆ fillCalibrants() [3/3]

Size fillCalibrants ( const std::vector< PeptideIdentification > &  pep_ids,
double  tol_ppm 
)

Extract calibrants from identifications.

Extracts only the first hit from each peptide identification. Hits are sorted beforehand. Ambiguities should be resolved before, e.g. using IDFilter.

A filtering step is done in the m/z dimension using tol_ppm. Since precursor masses could be annotated wrongly (e.g. isotope peak instead of mono), larger outliers are removed before accepting an ID as calibrant.

Parameters
pep_idsPeptide ids (e.g. from an idXML file)
tol_ppmOnly accept ID's whose theoretical mass deviates at most this much from annotated
Returns
Number of calibration masses found

◆ fillID_()

void fillID_ ( const PeptideIdentification pep_id,
const double  tol_ppm,
CalibrantStats_ stats 
)
protected

Add(no prior clear) calibrants to internal list.

Extracts only the first hit from each peptide identification. Hits are sorted beforehand. Ambiguities should be resolved before, e.g. using IDFilter.

A filtering step is done in the m/z dimension using tol_ppm. Since precursor masses could be annotated wrongly (e.g. isotope peak instead of mono), larger outliers are removed before accepting an ID as calibrant.

Parameters
pep_idA single PeptideID (e.g. from an idXML file); only the top peptide hit is used
tol_ppmOnly accept ID's whose theoretical mass deviates at most this much from annotated
statsUpdate stats, if calibrant cannot be used (no RT, no MZ, no sequence, out-of tolerance)

◆ fillIDs_()

void fillIDs_ ( const std::vector< PeptideIdentification > &  pep_ids,
const double  tol_ppm,
CalibrantStats_ stats 
)
protected

calls fillID_ on all PeptideIDs

◆ getCalibrationPoints()

const CalibrationData& getCalibrationPoints ( ) const

Get container of calibration points.

Filled using fillCalibrants() methods.

Returns
Container of calibration points

◆ isDecalibrated_()

bool isDecalibrated_ ( const PeptideIdentification pep_id,
const double  mz_obs,
const double  tol_ppm,
CalibrantStats_ stats,
double &  mz_ref 
)
protected

determine if sequence is within tol_ppm and update stats; fills mz_ref with the theoretical m/z of the sequence

Member Data Documentation

◆ cal_data_

CalibrationData cal_data_
private