Reference

base.py

Parent classes used by IsoCor to define specific correctors sub-classes.

There should be no need to instanciate any of those classes directly. However, all correctors classes should inherit from the classes:

class isocor.base.InterfaceMSCorrector[source]

Bases: object

Interface for Mass Spectrometry correctors.

This class defines the minimal methods that a corrector should implement. Keep in mind that a corrector must inherit from both InterfaceMSCorrector and LabelledChemical.

exception ImproperUsageError[source]

Bases: Exception

Raised when the corrector is used incorrectly.

compute_correction_matrix()[source]

Returns the correction matrix taking into account all parameters.

Warning

Does not set correction_matrix if called directly.

Returns:

the correction matrix

Return type:

array

correct(measurement)[source]

Return corrected measurement vector.

Parameters:

measurement (list) – measured areas

Returns:

  • corrected_area (array): Corrected area for each peak.

  • isotopologue_fraction (list): The abundance of each tracer isotopologue (corrected area normalized to 1).

  • residuum

  • mean enrichment

Return type:

tuple

property correction_matrix

Correction matrix.

The correction matrix will be set once and for all using compute_correction_matrix() during the first access. Use del x.correction_matrix if you wish to reset it.

class isocor.base.LabelledChemical(formula, tracer, derivative_formula, tracer_purity, correct_NA_tracer, data_isotopes, charge=None, label=None, inchi=None)[source]

Bases: object

A labeled chemical considered for isotope correction.

This class defines and check the parameters (formulas, tracer, etc.). needed to model a chemical undergoing MS correction.

Default isotopic data come from:

Isotopic Compositions of the Elements 2013, Pure Appl. Chem., 2016, Vol. 88, No. 3, pp. 293-306, https://doi.org/10.1515/pac-2015-0503

Warning

Except specified otherwise, you should never set any attribute at runtime. Always make a new instance if you wish to change the parameters.

Parameters:

  • formula (str) – elemental formula of the metabolite moiety (e.g. “C3H7O6P”)

  • inchi (str) – InChI of the metabolite (e.g. “InChI=1/C6H12O6/c7-1-2-3(8)4(9)5(10)6(11)12-2/ h2-11H,1H2/t2-,3-,4+,5-,6+/m1/s1” for alpha- D -glucopyranose). Note that the InChI might represents the metabolite moiety (e.g. a fragment ion) or the metabolite, hence its formula may differ from formula.

  • tracer (str) – the isotopic tracer (e.g. “13C”)

  • charge (int) – charge of the detected ion

  • label (str) – metabolite abbreviation (e.g. “G3P”)

  • data_isotopes (dict) – isotopic data with mass and abundance as in DEFAULT_ISODATA. If set to None, default isotopic data are used.

  • derivative_formula (str) – elemental formula of the derivative moiety

  • tracer_purity (list) – proportion of each isotope of the tracer element (metabolite moiety) The list must have the same length as the list of isotopes for the relevant isotope in data_isotopes. Must be normalized to one. If set to None, a perfect purity is assumed.

  • correct_NA_tracer (bool) – flag to correct tracer natural abundance or not. If set to True, tracer elements of the metabolite moiety will be corrected for the natural isotopic abundance of the tracer. Note that tracer elements from the derivative moiety will always be corrected at natural abundance (by definition of a derivative moiety).

DEFAULT_ISODATA = {'C': {'abundance': [0.9893, 0.0107], 'mass': [Decimal('12.0'), Decimal('13.003354835')]}, 'H': {'abundance': [0.999885, 0.000115], 'mass': [Decimal('1.0078250322'), Decimal('2.0141017781')]}, 'N': {'abundance': [0.99636, 0.00364], 'mass': [Decimal('14.003074004'), Decimal('15.000108899')]}, 'O': {'abundance': [0.99757, 0.00038, 0.00205], 'mass': [Decimal('15.99491462'), Decimal('16.999131757'), Decimal('17.999159613')]}, 'P': {'abundance': [1.0], 'mass': [Decimal('30.973761998')]}, 'S': {'abundance': [0.9499, 0.0075, 0.0425, 0.0, 0.0001], 'mass': [Decimal('31.972071174'), Decimal('32.971458910'), Decimal('33.9678670'), Decimal('35.0'), Decimal('35.967081')]}, 'Si': {'abundance': [0.92223, 0.04685, 0.03092], 'mass': [Decimal('27.976926535'), Decimal('28.976494665'), Decimal('29.9737701')]}}
property charge

absolute value of the charge of the metabolite.

Type:

int

property correct_NA_tracer

correct tracer natural abundance if set to True

Type:

bool

property correction_formula

molecular formula on which the correction will be applied

This formula is the one on which the correction vector is based. Remember that for the correction vector we need non-tracers atoms from the measured metabolite (all elements excluding the tracer element) and all atoms from the derivative (including the tracer element).

Type:

Counter

property data_isotopes

isotopic data with mass and abundance

See DEFAULT_ISODATA for an example.

Type:

dict of dicts

property derivative_formula

elemental formula of the derivative moiety.

Type:

Counter

property formula

elemental formula of the metabolite moiety

Type:

Counter

property inchi

inchi of the metabolite.

Type:

str

property isotopic_inchi

Generate isotopic inchis of the corrected fractions, or just the isotopic layer if no InChI has been provided.

Standard proposed by the InChI Isotopologue and Isotopomer Development Team:

Simple Definition: /a(Ee#<+|->#…) Complete Definition:

/a(<element><isotope_count><isotope_designation>[,<atom_number>]) <element> - one or two letter Element code (Ee). <isotope_count> - number of atoms with the designated isotope (#). <isotope_designation> - isotope designation indicated by a sign (+ or -) and number

indicating the unit mass difference from the rounded average atomic mass of the element. For example, the average atomic mass of Sn (118.710) is rounded to 119. We specify two 118 Sn atoms as “/a(Sn2-1)”.

Example

13C2 isotopologue of alpha-D-glucopyranose: InChI=1/C6H12O6/c7-1-2-3(8)4(9)5(10)6(11)12-2/h2-11H,1H2/t2-,3-,4+,5-,6+/m1/s1 /a(C2+1),(C4+0)

Returns:

isotopic inchis

Return type:

list

property molecular_weight

exact molecular weight of the metabolite.

Including the derivative and the tracer.

Type:

Decimal

property mzshift_tracer

mass shift of the tracer

Warning

Mass shift is computed from the first isotope of the list in data_isotopes.

Type:

Decimal

property tracer_purity

proportion of each isotope for the tracer element of the metabolite

Type:

list

mscorrectors.py

Correctors classes of IsoCor for mass spectrometry data.

Metabolite correctors are metabolite-centered objects used to correct mass spectrometry data for natural abundance and tracer purity.

Metabolite correctors can be instanciated directly or through their factory (recommended).

class isocor.mscorrectors.HighResMetaboliteCorrector(formula, tracer, resolution, mz_of_resolution, resolution_formula_code, charge, **kwargs)[source]

Bases: LowResMetaboliteCorrector

Metabolite corrector for high-resolution mass-spectrometry data.

At high-resolution, we consider that the measured peak may not encompass all isotopologues due to isotope natural abundance, depending on the operating resolution of the mass spectrometer at a given m/z.

This is essentially the same correction pipeline as for low-resolution data, except that the calculation of the correction vector must be more precise and therefore requires a more complex (and more time-consumming) algorithm.

Parameters:

  • formula (str) – elemental formula of the metabolite moiety (e.g. “C3H7O6P”)

  • tracer (str) – the isotopic tracer (e.g. “13C”)

  • label (str) – metabolite abbreviation (e.g. “G3P”)

  • inchi (str) – InChI of the metabolite (e.g. “InChI=1/C6H12O6/c7-1-2-3(8)4(9)5(10)6(11)12-2/ h2-11H,1H2/t2-,3-,4+,5-,6+/m1/s1” for alpha- D -glucopyranose). Note that the InChI might represents the metabolite moiety (e.g. a fragment ion) or the metabolite, hence its formula may differ from formula.

  • data_isotopes (dict) – isotopic data with mass and abundance as in DEFAULT_ISODATA

  • derivative_formula (str) – elemental formula of the derivative moiety

  • tracer_purity (list) – proportion of each isotope of the tracer element (metabolite moiety) The list must have the same length as the list of isotopes for the relevant isotope in data_isotopes. Must be normalized to one.

  • correct_NA_tracer (bool) – flag to correct tracer natural abundance or not. If set to True, tracer elements of the metabolite moiety will be corrected for the natural isotopic abundance of the tracer. Note that tracer elements from the derivative moiety will always be corrected at natural abundance (by definition of a derivative moiety).

  • resolution (int) – resolution of the mass spectrometer (e.g. “1e4”)

  • mz_of_resolution (int) – m/z at which the resolution was measured (e.g. “400”). This is not the m/z of the metabolite.

  • resolution_formula_code (str) – code for the resolution formula you wish to use to compute the correction limit among the presets: “orbitrap”, “ft-icr”, and “constant”. This formula depends on your mass spectrometer.

  • resolution_formula (func) – (EXPERIMENTAL) if no code suits you, you can use this parameter to provide a function returning the resolution at the mz of the metabolite. Use the same format as in RES_FORMULAS. resolution_formula has precedence over resolution_formula_code.

  • charge (int) – charge state of the metabolite (e.g. “-2”).

RES_FORMULAS = {'constant': <function HighResMetaboliteCorrector.<lambda>>, 'datafile': <function HighResMetaboliteCorrector.<lambda>>, 'ft-icr': <function HighResMetaboliteCorrector.<lambda>>, 'orbitrap': <function HighResMetaboliteCorrector.<lambda>>}
compute_correction_matrix()[source]

Returns the correction matrix taking into account all parameters.

Attention

Does not set correction_matrix if called directly.

Returns:

the correction matrix

Return type:

array

property correction_limit

Operative correction limit (in Da).

Depends on the calibration resolution, the m/z at which the instrument was calibrated, the m/z of the meabolite and of course the formula that gives the relation between those values (that depends on the spectrometer).

get_isotopic_cluster()[source]

Return the full isotopic cluster of the compound (for non-tracer elements).

Parameters:

threshold_p (float) – Probability threshold under which a peak will be ignored (default: keep all peaks).

Returns:

isotopologues masses mapped to their respective expected abundance (e.g. {83.9959772546: 0.966808533640457, …}).

Return type:

dict

get_mass_distribution_vector()[source]

Get mass distribution vector (at natural abundancy) for non-tracers elements.

Based on the elemental compositions of both metabolite’s and derivative’s moieties.

Important

This methods needs to compute the full isotopic cluster, which is an expensive operation.

Returns:

mass distribution vector

Return type:

list

get_peaks_around(isotopic_cluster, masses)[source]

Sum unresolved peaks of isotopic cluster according to the MS resolution.

Parameters:

  • isotopic_cluster (dict) – isotopic cluster as returned by :meth:~get_isotopic_cluster

  • masses (list) – m/z around which peaks will be pooled

Returns:

abundances for each input mass, after sorting the mass and pooling nearby peaks within the resolution limit (correction_limit)

Return type:

list

get_tracershifted_peaks_between(mz_min, mz_max)[source]

Return the mass of all the peaks that originate from the tracer.

Those peaks are the ‘main’ peaks around which we will find other peaks due to the incorporation of natural isotopes of non-tracer elements (different from the most abundant isotope).

Parameters:

  • mz_min (float) – minimum range

  • mz_max (float) – maximum range

Returns:

mass of all peaks that originate from the tracer

Return type:

list

class isocor.mscorrectors.LowResMetaboliteCorrector(formula, tracer, **kwargs)[source]

Bases: LabelledChemical, InterfaceMSCorrector

Metabolite corrector for low-resolution mass-spectrometry data.

At low-resolution, all isotopologues with the same nominal mass are considered to be measured together.

Parameters:

  • formula (str) – elemental formula of the metabolite moiety (e.g. “C3H7O6P”)

  • inchi (str) – InChI of the metabolite (e.g. “InChI=1/C6H12O6/c7-1-2-3(8)4(9)5(10)6(11)12-2/ h2-11H,1H2/t2-,3-,4+,5-,6+/m1/s1” for alpha- D -glucopyranose). Note that the InChI might represents the metabolite moiety (e.g. a fragment ion) or the metabolite, hence its formula may differ from formula.

  • tracer (str) – the isotopic tracer (e.g. “13C”)

  • label (str) – metabolite abbreviation (e.g. “G3P”)

  • data_isotopes (dict) – isotopic data with mass and abundance as in DEFAULT_ISODATA

  • derivative_formula (str) – elemental formula of the derivative moiety

  • tracer_purity (list) – proportion of each isotope of the tracer element (metabolite moiety) The list must have the same length as the list of isotopes for the relevant isotope in data_isotopes. Must be normalized to one. Default is perfect purity.

  • correct_NA_tracer (bool) – flag to correct tracer natural abundance or not. If set to True, tracer elements of the metabolite moiety will be corrected for the natural isotopic abundance of the tracer. Note that tracer elements from the derivative moiety will always be corrected at natural abundance (by definition of a derivative moiety).

compute_correction_matrix()[source]

Returns the correction matrix taking into account all parameters.

Attention

Does not set correction_matrix if called directly.

Returns:

the correction matrix

Return type:

array

correct(measurement)[source]

Return corrected measurement vector.

Parameters:

measurement (list) – measured areas

Returns:

  • corrected_area (array): Corrected area for each peak.

  • isotopologue_fraction (list): The abundance of each tracer isotopologue (corrected area normalized to 1).

  • residuum

  • mean enrichment

Return type:

tuple

get_mass_distribution_vector()[source]

Get low resolution mass distribution vector (at natural abundance) for non-tracers elements.

Based on the elemental compositions of both metabolite’s and derivative’s moieties. The element corresponding to the isotopic tracer is ignored.

Calculation is based on convolution of isotopic vectors of individual elements (IsoCor, Millard et al., 2012), which is much faster than the combinatorial approach implemented for simulation at high resolution.

Returns:

mass distribution vector

Return type:

list

class isocor.mscorrectors.MetaboliteCorrectorFactory(formula, tracer, **kwargs)[source]

Bases: object

A Factory that returns the right metabolite corrector given the correction options.

Parameters:

  • formula (str) – elemental formula of the metabolite moiety (e.g. “C3H7O6P”)

  • inchi (str) – InChI of the metabolite (e.g. “InChI=1/C6H12O6/c7-1-2-3(8)4(9)5(10)6(11)12-2/ h2-11H,1H2/t2-,3-,4+,5-,6+/m1/s1” for alpha- D -glucopyranose). Note that the InChI might represents the metabolite moiety (e.g. a fragment ion) or the metabolite, hence its formula may differ from formula.

  • tracer (str) – the isotopic tracer (e.g. “13C”)

  • label (str) – metabolite abbreviation (e.g. “G3P”)

  • data_isotopes (dict) – isotopic data with mass and abundance as in DEFAULT_ISODATA (default values)

  • derivative_formula (str) – elemental formula of the derivative moiety (default: no derivative)

  • tracer_purity (list) – proportion of each isotope of the tracer element (metabolite moiety) The list must have the same length as the list of isotopes for the relevant isotope in data_isotopes. Must be normalized to one. Default is perfect purity.

  • correct_NA_tracer (bool) – flag to correct tracer natural abundance or not. If set to True, tracer elements of the metabolite moiety will be corrected for the natural isotopic abundance of the tracer. Note that tracer elements from the derivative moiety will always be corrected at natural abundance (by definition of a derivative moiety). Default is False.

  • resolution (int) – resolution of the mass spectrometer (e.g. “1e4”); default “None” (low-resolution).

  • mz_of_resolution (int) – m/z at which the resolution was measured (e.g. “400”). This is not the m/z of the metabolite.

  • resolution_formula_code (str) – code for the resolution formula you wish to use to compute the correction limit among the presets: “orbitrap” (default), “ft-icr”, and “constant”. This formula depends on your mass spectrometer.

  • charge (int) – charge state of the metabolite (e.g. “-2”).

Raises: