If you have a question that is not covered in the tutorials, have a look at the faq.
IsoCor takes as input the raw MS data, i.e. mass fractions <mass fractions> of the isotopic cluster <isotopic cluster>, to calculate the corresponding isotopologue distribution <isotopologue distribution>, hence providing quantitative information on the incorporation of labeling into metabolites.
The raw MS data and the information required to perform the correction (i.e. the natural abundance and exact mass of isotopes, and a list of metabolites and derivatives moieties with their elemental formulas) are provided in flat text files.
At first start, IsoCor creates in the user directory a IsoCor data folder isocordb containing default database files. These files can be edited and implemented according to the user's needs, as detailed below. Different database files can also be created (e.g. to have specific project-related databases), as detailed below.
This file contains the raw MS data for each metabolite of each sample, i.e. the mass fractions <mass fractions> of the measured isotopic cluster <isotopic cluster> that contain information on the tracer isotopologues <tracer isotopologues>. For each metabolite you should always measure n + 1 mass fractions, where n is the number of atoms of the tracer element in the metabolite.
The measurement file is a TSV file with one row by isotopologue <isotopologues> and the following columns:
- sample
The sample name (optional); e.g. "Cloverfield 10".
- metabolite
The metabolite name that represents the metabolite moiety, as it is referred in the metabolite database (metabolites.dat); e.g. "PEP".
- derivative
The derivative name (optional) that represents the derivative moiety, as it is referred in the derivative database (derivatives.dat); e.g. "TMS".
- isotopologue
The index of the peak measured, as an integer; e.g. '0' for the M0 peak that does not have any mass shift.
- area
The measured
mass fractions <mass fractions>; e.g. "4242.42".
Example file <../isocor/data/Data_example.tsv>.
Note
An example file is provided with IsoCor. It is created at the first run of IsoCor in your user directory (yourusername/isocordb/Data_example.tsv).
About derivatives
The derivative field is optional and should be declared only if:
- a derivatization step was performed before MS analysis,
- some atoms of the derivative remains in the molecular entity that gives rise to measured
isotopic cluster <isotopic cluster>.
Declaration of elemental formulas: "metabolite" and "derivative" moieties <Formulas>
The exact mass and natural abundance of each isotope and the elemental formulas used for correction have to be defined carefully, otherwise the correction will be wrong.
IsoCor rely on several flat-files to store this information. Pre-configured files are shipped with IsoCor and created at the first run of IsoCor. Those database should be modified according to the user needs. They are located in IsoCor data directory, in user main directory: yourusername/isocordb/.
Note
IsoCor is case sensitive; i.e. two metabolites or derivatives with the same name but different cases will be considered as two distinct entities.
This file stores the exact mass and natural abundance of all stable isotopes of each element, given as relative fractions.
It is a TSV file with one row by isotope and the following columns:
- element
The element symbol of the isotope; e.g. "C".
- mass
The exact mass of this isotope; e.g. "13.003354835" for 13C.
- abundance
The relative abundance of this isotope normalized to 1; e.g. "0.0107" for 13C.
Example file <../isocor/data/Isotopes.dat>.
A pre-configured isotopes database can be found in IsoCor data directory and should be edited according to the users needs. It is located in user main directory at yourusername/isocordb/Isotopes.dat.
Warning
The isotopes database is always loaded from IsoCor data directory, i.e. from yourusername/isocordb/Isotopes.dat.
Note
All elements should be declared, including elements with only one isotope (with its abundance set to 1). This is required for accurate correction of high-resolution data.
Note
For elements with gaps in the list of nominal mass of isotopes (e.g. for sulfur with isotopes 33S, 34S, 36S, but not 35S), declare the missing isotope(s), with the exact mass set at the missing integer(s), and an abundance of 0 (as done in the example file for sulfur).
This file stores elemental formulas of the metabolites.
It is a TSV file with the following columns:
- name
Metabolite name or abbreviation, e.g: "pyruvic acid" or "PYR".
- formula
Elemental formula of the metabolite moiety of the molecular entity that gives rise to the measured
isotopic cluster <isotopic cluster>; e.g: "C3H4O3". See alsoFormulas.
Example file <../isocor/data/Metabolites.dat>.
A pre-configured metabolites database can be found in IsoCor data directory and should be edited according to the users needs. It is located in user main directory at yourusername/isocordb/Metabolites.dat.
This file stores elemental formulas of chemical derivatives that have to be considered for the isotopic correction of metabolites derivatized prior to MS analysis.
It is a TSV file with the following columns:
- name
Derivative name or abbrevation, e.g: "t-butyldimethyl-silylation" or "M-57".
- formula
Elemental formula of the derivative moiety of the molecular entity that gives rise to the measured
isotopic cluster <isotopic cluster>; e.g: "Si2C8H21". See alsoFormulas.
Example file <../isocor/data/Derivatives.dat>.
A pre-configured derivatives database can be found in IsoCor data directory and should be edited according to the users needs. It is located in the user main directory at yourusername/isocordb/Derivatives.dat.
IsoCor data directory is created at the first run of IsoCor with pre-configured databases files in the user main directory (yourusername/isocordb/). These files should be edited according to the users needs, e.g. to add some metabolites and derivatives formulas.
Alternatively, users can select at runtime a custom folder from which metabolites and derivatives will be loaded ('Metabolites.dat' and 'Derivatives.dat') with the 'Databases Path' button. It is especially useful to define project-based database files.
Warning
Importantly, 'Isotopes.dat' is always loaded from IsoCor data directory ('yourusername/isocordb/Isotopes.dat') and will not be loaded from a custom databases folder.
IsoCor provides several options to adapt to many situations that can be encountered in terms of isotopic tracer, sample processing, resolution <resolution> of the MS analyzer, etc.
- Measurements file
Path to the
Measurements file.- Isotopic tracer
The tracer used for your experiment. Available tracers are imported from isotopes.dat database file.
- Resolution
Resolutionof the MS analyzer.- Resolution measured at
m/z at which the
resolution <resolution>is given.- Resolution formula
The relationship between the operating
resolution <resolution>and the resolution at m/z of the measured metabolite moiety depends on the MS analyzer, which has to be selected.- Tracer purity
Correct for the presence of unlabeled atoms at labeled positions, using the relative abundance of each isotope of the tracer element at labeled positions. Default is to assume a perfect purity (i.e. tracer isotope=1).
- Correct natural abundance of the tracer element
Correct for natural abundance of the tracer element at unlabeled positions. Default is no correction.
- Output data path
Path to the
Output data. A log file with the same name will be created in the same directory, with a '.log' extension.- Verbose logs
If set, the log-file will contain all information necessary to check intermediate results of the correction process.
Tutorial: Isotopic purity and natural abundance of the tracer.
The result file is a TSV file with the following columns:
- sample
Name of the sample, as it was provided in the
Measurements file.- metabolite
Name of the metabolite, as it was provided in the
Measurements file.- derivative
Name of the derivative, as it was provided in the
Measurements file.- isotopologue
The index of the peak measured, as an integer; e.g. '0' for the M0 peak that does not have any mass shift, as it was provided in the
Measurements file.- area
The measured peak intensity; e.g. '42.5', as it was provided in the
Measurements file.- corrected_area
The corrected area.
- isotopologue_fraction
The abundance of each
isotopologue <Isotopologues>(corrected area normalized to 1).- residuum
Residuum of the fit (difference between experimental and optimal isotopologue distribution, normalized to 1).
- mean_enrichment
Mean molecular content in isotopic tracer in the metabolite.
A log file is created in the same directory as the Result file to store correction parameters (for reproducibility), with a '.log' extension.
Extensive information on the correction process (correction vector, correction matrix, intermediary results, etc.) can be found in the log file if 'Verbose logs' option has been checked.
Error messages are explicit. You should examine carefully any warning/error message. After correcting the problem, you might have to restart IsoCor (to reload databases files) and perform the correction again.
This section provides guidelines for the definition of elemental formulas of "metabolite" and "derivative" moieties. It also provides representative examples to cover a large panel of MS and MS/MS methods dedicated to quantitative isotopic analysis.
Elemental formulas must be defined according to the molecular entity that gives rise to the measured isotopic cluster <isotopic cluster>. It may correspond (but not necessarily) to the elemental formula of the detected ion.
For instance, in the following situations, the formulas should include:
- for MS measurements: all atoms of the detected ion
- for MS/MS measurements, with all tracer atoms in the detected ion: only atoms of the detected ion
- for MS/MS measurements, with no tracer atoms in the detected ion: only atoms of the complement (neutral fragment)
All atoms of the molecular entity that gives rise to the measured isotopic cluster <isotopic cluster> should be declared strictly once in a formula, either as a "metabolite" or a "derivative" moiety.
Atoms that originate from the metabolite should be declared in the file "metabolites.dat", and atoms that originate from the derivative (if any) should be declared in the file "derivatives.dat".
A derivative moiety should thus be declared only if a derivatization step was performed before MS analysis. Importantly, we consider that the derivative moiety do not contain any tracer atom. Therefore, all its atoms (including atoms of the tracer element) are expected to be at natural isotope abundance and will be corrected as such. This is obviously not the case for the metabolite moiety that do incorporate tracer atoms and is thus corrected differently. It follows that, to ensure the accurate correction of the measured isotopic cluster <isotopic cluster>, the atoms originated from the derivative moiety must be declared separately from those originated from the metabolite moiety (respectively into derivatives.dat and metabolites.dat).
Example 1 - MS analysis: Pyruvate
Pyruvic acid (C3H4O3) can be analyzed by LC-MS using multiple ion monitoring (MIM) in the negative mode, and the measured isotopic cluster <isotopic cluster> originates from the molecular ion [C3H3O3]-, then the formula to use for correction is C3H3O3. This formula must be set into metabolites.dat and referred to by its associated name into the measurements file.
Example 2 - MS/MS analysis, with no tracer atoms in the detected ion: PEP
Phosphoenolpyruvate (PEP) can be analyzed using the MS/MS method developed by Kiefer et al. (2007). The fragmentation of phosphorylated metabolites results in the efficient release of [PO3]- or [H2PO4]- ions, allowing highly sensitive measurement of isotopologue distributions <isotopologue distribution> in these compounds in the multiple reaction monitoring (MRM) mode. This is achieved by selecting MRM transitions in which phosphate ions are detected but which encode the isotopic cluster <isotopic cluster> of the complement, i.e., the part of the molecule that remains after loss of the phosphate ion that is actually detected. In the case of PEP (C3H5O6P), for which the molecular ion that is analyzed is [C3H4O6P]-, the analysis is based on MRM transitions in which [PO3]- ions are used, meaning that the isotopic cluster <isotopic cluster> is actually measured for the complement fragment C3H4O3. Hence, the formula to enter in metabolites.dat is C3H4O3.
Example 3 - MS analysis of derivatized metabolites with in source fragmentation, with all tracer atoms in the detected ion: TBDMS-derivatized Alanine
Alanine (C3H7O2N) can be analyzed by GC-MS after t-butyldimethyl-silylation (TBDMS derivatization). A fragment that is classically used for 13C-metabolic flux analysis is the 'M-57' fragment that contains all atoms the compound of interest and two TBDMS groups, one of which lose the fragment [C4H9]. The elemental formula of the two TBDMS groups excluding the latter fragment (i.e. [Si2C8H21]) must be declared into derivatives.dat since it will be present in the molecular entity that gives rise to the measured isotopic cluster <isotopic cluster>. Meanwhile, the elemental composition of the alanine moiety of the detected ion (i.e. [C3H5O2N]) must be declared as the "metabolite moiety", thus into metabolites.dat.
Example 4 - MS/MS analysis, with all tracer atoms in the detected ion
In this situation where the fragment ion which is detected gives rise to the measured isotopic cluster <isotopic cluster>, the elemental formula to declare in IsoCor is the formula of the fragment ion. Atoms of the fragment that originate from the metabolite should be declared into metabolites.dat, and atoms that originate from the derivative should be declared into derivatives.dat.
This section provides guidelines to account for the resolution <resolution> of the MS analyzer.
For low resolution <resolution> datasets collected at unitary resolution (i.e. typically R<1000), select "Low resolution".
For high resolution <resolution> datasets, accurate correction requires to know the resolution of the MS analyzer at the particular m/z of the molecular entity that gives rise to the experimental isotopic cluster <isotopic cluster>. It is used to identify the correct set of isotopic species that overlap with the masses of the tracer isotopologues in the isotopic cluster <isotopic cluster>, and ultimately remove their contribution.
Typically, the resolution <resolution> of the MS analyzer is given at a specific m/z (defined during instrument calibration). IsoCor estimates the resolution at the appropriate m/z, provided this relationship is known. This relationship depends on each instrument and was implemented for FT-ICR and Orbitrap analyzers.
We have also implemented an option to set a "constant resolution", i.e. which is considered to be independent of the m/z.
Note
If you want to use IsoCor with a high-resolution MS instrument that is not currently supported (and for which you have the mathematical relationship to calculate the resolution <resolution> at a given m/z from the resolution at the calibration mass), please contact us.
IsoCor provides options to correct (or not) for isotopic purity of the tracer and natural abundance of the tracer elements. Ideally, you should correct the data for both isotopic purity of the tracer and natural abundance of the tracer elements. By doing so, the output data will readily reflect the incorporation of labeling and will be comparable between metabolites.
However, this is not always possible (e.g. if the isotopic purity is not known it cannot be corrected), nor desirable (e.g. if a tool downstream in your analysis pipeline will force you to perform some corrections). In the end, the correction options must always be taken into account when interpreting the data so you should choose them carefully.
Warning
The choice to correct isotopic purity and/or natural abundance of the tracer is absolutely critical for accurate interpretations of the output data (isotopologues distributions)!
Labelled substrates are not isotopically pure, i.e. they are not 100 % enriched at the 'labelled' position(s). The latter contain small fractions of non-tracer isotopes for which MS data must be corrected. To do so, the fractions of each isotope into the 'labelled' positions must be provided. For example, if the content in 13C atoms in each position of a U-13C-labeled compound is 99 %, other 1 % being 12C atoms, the purity must be entered as 12C=0.01 and 13C=0.99.
Note
If you do not want to correct isotopic clusters <isotopic cluster> for the isotopic purity of the substrate, or if you do not know it, just let the default value (purity = 1).
Warning
Tracer purity correction is only valid if all the labelled positions of the substrate(s) have the same isotopic purity. It should be checked from the manufacturers or determined experimentally.
When different labeled substrates are mixed, tracer purity correction also requires that all their labeled positions have the same isotopic purity.
Example: Unknown purity
If the purity of the label input(s) is not known you will not be able to correct it, despite the fact that it could be significant. Therefore, you should take special care in the interpretation of mean enrichment which will be overestimated.
Example: Several inputs with distinct purity
If two or more labeled inputs have highly different isotopic purity you will not be able to correct it properly. Therefore, you should take special care in the interpretation of mean enrichment.
When the label input is not uniformly labelled, it contains 'unlabelled' positions in which the tracer isotope is usually occurring at its natural abundance. The MS data can be corrected for the contribution of these naturally occurring isotopes.
Warning
Correction for natural abundance of the tracer element is only valid when the isotopes of the tracer element occur at natural abundance into the unlabeled positions of the input substrate(s). It is typically the case but should be checked from the manufacturer or determined experimentally.
Example: Natural abundance and downstream analysis
You must be aware of the corrections performed by downstream analysis tools and make sure that you do not correct something twice.
In a 13C-metabolic flux analysis experiment, if the raw data has already been corrected for natural abundance of the tracer element, the unlabeled position(s) of all carbon sources must be declared as unlabeled with a perfect purity when calculating fluxes (e.g. CO2 input should be declared as: 12C=1.0), which might be counter-intuitive since you knew they were at natural abundance.
In contrast, if the raw data was not corrected for natural abundance of the tracer element, the unlabeled position(s) of all carbon sources must be declared at natural abundance when calculating fluxes (e.g. CO2 input should be declared as: 12C=0.9893, 13C=0.0107).