4.1.1 General (IsoCorrectoR and IsoCorrectoRGUI)

If you want IsoCorrectoR to write correction results as xls files, a Perl installation is required. If you want your results written as csv files, a Perl installation is not needed. To check if Perl is installed on your machine, type which perl in the command line of Linux and Mac OS machines or where perl in the command line of Windows machines. On Linux distributions, Perl should usually be installed by default. On Windows, the Perl distribution Strawberry Perl (http://strawberryperl.com/) can be used.

4.1.2 Graphical user interface version only (IsoCorrectoRGUI)

The graphical user interface (GUI) package of IsoCorrectoR, IsoCorrectoRGUI, additionally requires the R package ‘tcltk’. This package is installed with all standard installations of R. On Linux and Mac OS systems (but not on Windows), the X11 window manager is additionally required for running the GUI. To check if tcltk and (in the case of Linux and Mac OS systems) X11 is available on your system, start an R session and type capabilities() in your R console. If the value below tcltk and X11 in the output is TRUE, they are available to your R installation. Otherwise, please refer to the distributors of Tcl/tk and/or X11 for installing the software on your operating system if you wish to use the GUI.

5.1.0.1 Parameters that can be set in the graphical user interface:

• Measurement File: The file that contains the measured data to be corrected. Has to be provided
• Molecule File: The file that contains the information on the molecules for which data is to be corrected. Has to be provided
• Element File: The file that contains the element information required for correction. Has to be provided
• Output Directory: Defines the directory the corrected data and log-file should be written to. Has to be provided
• Name Outputfile: Defines the name of the file that contains the corrected data. The name of the file will be IsoCorrectoR_[Name Outputfile].[Format Outputfile]. If the format is csv, the name will also contain the type of corrected data in the respective file
• Format Outputfile: Defines the format of the files that contain the corrected data. Can either be ‘csv’ or ‘xls’. If ‘csv’ is choosen, multiple files will be produced, one for each type of corrected data (corrected data, fractions, mean enrichment…). If ‘xls’ is choosen, all correction results are provided in one excel file in different sheets
• Correct Tracer Impurity: If checked, correction for isotopic impurity of the tracer substrate is performed
• Corr. Tracer Element Core: If checked, the tracer element atoms in the core molecule (usually the part of the molecule that does not come from derivatization) are considered when correcting. Recommended to be checked
• Calculate Mean Enrichment: If checked, mean isotopic enrichment is calculated for each molecule
• High Resolution Mode: If checked, performs high resolution correction on the data. Should only be checked if you know that you have high resolution data
• Advanced Options: see section Input files and parameters

5.2.0.1 Function call:

IsoCorrection(MeasurementFile=NA, ElementFile=NA, MoleculeFile=NA, 
              CorrectTracerImpurity=FALSE, CorrectTracerElementCore=TRUE, 
              CalculateMeanEnrichment=TRUE, UltraHighRes=FALSE, 
              DirOut='.', FileOut='result', FileOutFormat='csv', 
              ReturnResultsObject=FALSE, CorrectAlsoMonoisotopic=FALSE, 
              CalculationThreshold=10^-8, CalculationThreshold_UHR=8, 
              verbose=FALSE, Testmode=FALSE)

5.2.0.2 Basic arguments:

• MeasurementFile: The file that contains the measured data to be corrected. Has to be set
• ElementFile: The file that contains the element information required for correction. Has to be set
• MoleculeFile: The file that contains the information on the molecules for which data is to be corrected. Has to be set
• CorrectTracerImpurity: If TRUE, correction for isotopic impurity of the tracer substrate is performed
• CorrectTracerElementCore: If TRUE, the tracer element atoms in the core molecule (usually the part of the molecule that does not come from derivatization) are considered when correcting. Recommended to be set to TRUE
• CalculateMeanEnrichment: If TRUE, mean isotopic enrichment is calculated for each molecule
• UltraHighRes: If TRUE, performs high resolution correction on the data. Should only be set to TRUE if you know that you have high resolution data
• DirOut: String that defines the directory the corrected data and log-file should be written to. Defaults to the current working directory (‘.’)
• FileOut: String that defines the name of the file that contains the corrected data. The name of the file will be IsoCorrectoR_[FileOut].[FileOutFormat]. If the format is csv, the name will also contain the type of corrected data in the respective file
• FileOutFormat: Defines the format of the files that contain the corrected data. Can either be ‘csv’ or ‘xls’. If ‘csv’ is choosen, multiple files will be produced, one for each type of corrected data (corrected data, fractions, mean enrichment…). If ‘xls’ is choosen, all correction results are provided in one excel file in different sheets
• ReturnResultsObject: If TRUE, returns the correction results as a list in the current R-session in addition to writing the results to file. This is useful if the corrected data has to be processed directly in R
• verbose: If TRUE, status messages are sent to standard output.

5.2.0.3 Advanced arguments (usually need not be changed):

• CorrectAlsoMonoisotopic: If TRUE, will also provide monoisotopic correction results
• CalculationThreshold: Defines a threshold to stop probability calculations at for making correction faster (normal resolution mode). Should be left at default value
• CalculationThreshold_UHR: Defines a threshold to stop probability calculations at for making correction faster (high resolution mode). Should be left at default value
• Testmode: If TRUE, starts a testmode for development purposes. Not required for users of IsoCorrectoR

5.2.0.4 Returned value

The IsoCorrection() function returns a list with 4 elements: success, results, log and error.

• success: string that is “TRUE” if the correction was successful, “FALSE” if an error occured and “WARNINGS” if warnings occured
• results: a list containing a dataframe for each type of corrected data (normal, fractions, mean enrichment…)
• log: list containing log information on the correction run (parameters, file names and paths, warnings and errors)
• error: contains a string with the associated error message if an error occurred, empty otherwise

The list element results only contains the data from correction if ReturnResultsObject is set to TRUE.

See section Input files and parameters for further information on input files, input file structure and the function parameters.

6.1.1 Molecule information file

The molecule information file contains all relevant information on the molecules that are to be corrected for natural isotope abundance/tracer purity. The file must contain three columns with the names Molecule, MS ion or MS/MS product ion and MS/MS neutral loss. The names/IDs of the molecules to be corrected are given in the first column of the file.

The file has to be adjusted depending on the molecules measured (taking into account the derivatizations used), the type of measurement performed (MS or MS/MS) and the tracer element used. For each molecule(-fragment) to be corrected, the number of atoms of all elements relevant for correction needs to be given in a sum formula, for example: C6H12O2N1LabC2 (alanine product ion sum formula from the example table below). The prefix Lab marks the tracer element. In the example, C6 indicates that there are in total 6 atoms of carbon in the molecule or fragment considered. Then, LabC2 provides the information that of those 6 carbons, 2 positions may actually be labeled due to incorporation from the tracer substrate. The other 4 positions cannot contain tracer from the tracer substrate e.g. because they stem from derivatization.

For MS¹ measurements, the second column of the molecule file, MS ion or MS/MS product ion needs to be filled with the sum formula of the ion arriving at the detector. The third column must remain empty. In the case of MS/MS measurements, the second column needs to be filled with the sum formula of the product ion while the third column, MS/MS neutral loss, must contain the information for the neutral loss portion.

Be aware that also elements that occur only once in the molecule(-fragment) must be assigned a number, e.g. N1 in the example above. Elements that do not occur at all need not be mentioned. If an element is present in the molecule information file but not in the element information file, this will produce an error and the correction is aborted.

In high resolution correction, multiple tracers can be considered in a single molecule. Thus, e.g. C9N1LabC2LabN1 can be written for a glycine molecule that can contains both ¹³C and ¹⁵N tracers. It is important to note that due to the nature of high resolution correction, elements other than the tracer elements are not relevant to the correction and need not be provided. Providing multiple tracers in normal resolution mode will result in an error, as well as providing a neutral loss sum formula in high resolution mode (MS/MS mode is not supported for high resolution correction).

See the tables below for normal and high resolution example setups of the file.

6.1.2 Measurement file

This file contains the measured data that needs to be corrected. The row names in the first column of the file define the kind of measurement made (e.g. what kind of transition was measured in an MS/MS experiment), the column names in the first row define the samples. The entry in row 1/column 1 of the file must be Measurements/Samples. The measured values must be placed so that they match the measurement and sample they belong to.

The names of the measurements in the first column need to be consistent with the following nomenclature, where ‘Name’ is the name of the respective molecule specified in the molecule information file: Name_x.y for MS/MS measurements and Name_x for non-MS/MS measurements. Here, x is the mass shift of the precursor of a given measurement with respect to the precursor of the completely unlabeled molecule. y is the mass shift of the product ion.

An alanine molecule that is named ‘Ala’ in the molecule information file and that shows a mass shift of 2 in the precursor and 1 in the product ion would be named Ala_2.1. A non-MS/MS-measurement of that alanine species with a mass shift of 2 would be named Ala_2. See the table below for an example file setup (MS/MS case for molecule Ala and MS¹ case for molecule Ser).

If high resolution measurements are to be corrected, the measurement names must be specified according to the following example: Gly_C2.N1 for the measurement corresponding to a glycine molecule containing two C tracers and one N tracer. If there are more than two tracers employed in the experiment, the syntax is analogous (e.g. Gly_C2.N1.O2 if an O tracer is used in addition). The sequence of occurence of the elements in the measurement names must equal the sequence of the tracer elements in the sum formula in the molecule information file (e.g. sum formula of Gly: C9N1LabC2LabN1, measurement name: Gly_C2.N1, not Gly_N1.C2).

See the tables below for example setups of a measurement file: In the normal resolution case, the molecule Ala was measured in MS/MS mode and can contain up to 2 tracers in the product ion and up to 1 tracer in the neutral loss. Ser was measured in MS¹ mode and can contain up to 3 tracers. In the high resolution example, Gly and Asn were measured in a combined ¹³C and ¹⁵N tracing experiment and can contain both ¹³C and ¹⁵N tracer.

6.1.3 Element information file

The element information file contains all relevant information on the elements important for the correction process. These are elements that occur in the molecules to be corrected and the stable isotopes of which show a high enough natural abundance to make a recognizable contribution to measurements of higher mass. The file has four columns which must be named Element, Isotope abundance_Mass shift, Tracer isotope mass shift, and Tracer purity. In the first column, the file must contain the element names (e.g. C, N, O…). The second column contains the natural isotope abundance (probability of occurrence) and the mass shift of the isotopes for each element. The mass shift is provided in relation to the isotope with the highest natural abundance. Thus, when considering e.g. C, the mass shift of ¹²C, which is the most abundant isotope of C, would be 0 and the mass shift of ¹³C would be 1.For each isotope, abundance and mass shift are separated by an underscore (_) while the different isotopes of an element are separated by a forward slash (/). For example 0.0107_1/0.9893_0 for the C isotopes ¹³C and ¹²C, respectively. The order of isotopes is not important.

In the uncommon case of the most abundant isotope not being the stable isotope with the lowest mass (e.g. when considering Se), negative mass shifts have to be employed (see example element file provided with the package).

In the third column, the mass shift associated with the tracer isotope is given (e.g. 1 for ¹³C or 2 for ¹⁸O) in the row corresponding to the tracer element. If correction for tracer purity is desired, the purity of the tracer has to be given as a fraction value in column four. See the table below for an example setup of the file.

6.2.1 Tracer purity correction

Tracer purity is the probability that a tracer element atom in the tracer substrate that should be labeled actually is labeled. E.g. a 99.0% isotopic purity 1,2-¹³C2-Glucose has a 99.0% chance for each of its carbon atom positions 1 and 2 of containing a ¹³C. Thus, there is a 1.0% chance for each of those carbons that they are not ¹³C. Consequently, molecules that contain portions of the tracer substrate due to metabolic activity inherit its impurity and contribute to measurements of lower mass according to the impurity of the tracer. This is due to the decrease in mass shift associated with tracer impurity (e.g. ¹²C instead of ¹³C at a carbon position). Tracer purity correction should only be performed if the purity information at a hand is reliable. If CorrectTracerImpurity is set to TRUE, correction for tracer impurity is performed in addition to natural abundance correction, if it is set to FALSE, no correction for tracer impurity is performed, only correction for natural isotope abundance.

6.2.2 Correction of tracer element natural abundance in the core molecule

If CorrectTracerElementCore is TRUE, the natural isotope abundance of the core tracer element atoms is taken into account for the correction procedure. The core of a molecule(-fragment) to be corrected is defined as the portion which can incorporate atoms from the tracer substrate (through metabolism).

The maximum number of tracer element atoms expected in the core is given by the user in the Lab[Element-Name] entry in the molecule information file (e.g. LabC or LabN). Usually, Lab[Element-Name] is just set to the amount of tracer element atoms present in the molecule(-fragment) without derivatization (e.g. LabC5 if C is the tracer element and glutamate is the molecule in question, measured in MS¹). If possible, CorrectTracerElementCore should be active, as the core usually makes a substantial contribution to the natural abundance correction. Switching the functionality off leads to only partially corrected values. This may also be desired, for example if only the natural abundance contribution of derivatization is to be corrected.

Another reason for setting CorrectTracerElementCore to FALSE may be that the isotopic abundances of the tracer element in the tracer substrate are unknown. This can occur with partially labeled tracer substrates like 1,2-¹³C2-Glucose. Part of the molecule is unlabeled. Due to the production process it is however not guaranteed that the unlabeled positions follow natural isotope abundance. This should usually be the case. If there are doubts, however, the manufacturer should be consulted. Abnormality can be checked by measuring the tracer substrates isotopologue distribution and correcting it with CorrectTracerElementCore turned on and CorrectTracerImpurity turned off. In this case, high correction residuals indicate non-natural isotope abundance, as well as area values at m/z higher than that of the substrate itself which are substantially higher than 0. The core tracer element correction always works with fully labeled tracer substrates like U-¹³C-Glucose or U-¹³C-Glutamine.

6.2.3 Normal/High resolution correction

The parameter UltraHighRes decides whether normal or high resolution correction is performed. FALSE stands for normal resolution, TRUE for high resolution. High resolution correction should only be used for high resolution data, meaning that the incorporation of isotopes that give the same nominal mass shift (e.g. the incorporation of ¹³C compared to the incorporation of ¹⁵N) can be resolved due to mass defect related differences. If this is the case, also data from experiments where multiple tracers were used simultaneously (e.g. ¹³C and ¹⁵N) can be corrected using the high resolution mode.

Be aware that using the high resolution mode on normal resolution data will either abort directly (if measurements are named according to the normal resolution scheme in the measurement file) or provide wrong results as correction is only performed on the tracer element and no other elements. The same is true for performing normal resolution correction on high resolution data. Here, natural abundance contributions are considered that are not present in high resolution data because they can be resolved spectrometrically. Plus, normal resolution correction cannot be used for data of experiments where multiple tracers (e.g. ¹³C and ¹⁵N) have been employed simultaneously.

6.3.1 Correction results for monoisotopic species

It might at first appear intuitive that the correction for natural isotope abundance and tracer impurity would correspond to a substraction of those contributions from the measured values. But such values would only reflect the quantity of the corrected monoisotopic species, the m/z of which corresponds to the respective m/z windows chosen for the measurements (the monoisotopic species is the respective labeled species where all isotopes (except for the tracers) are present in their most abundant from).

However, the quantity of the monoisotopic species is not a very good measure when trying to compare the different isotopologues of a molecule quantitatively. This is because the ratio between the monoisotopic portion and the total amount of a given labeled species varies with the amount of label incorporated from the tracing experiment. Thus, IsoCorrectoR by default provides the corrected total amount values of the labeled species.

Here, the contributions from other species are removed, while the quantities of the different natural abundance and tracer impurity derived isotopologues of the species to be corrected are added (correcting for natural abundance and tracer impurity means removing contributions from other species, not the natural abundance/tracer purity derived portions of the species to be corrected itself). If corrected monoisotopic values are explicitly wished for, however, this can be achieved by running IsoCorrectoR with the option CorrectAlsoMonoisotopic = TRUE. Then, corrected monoisotopic values are provided in addition to the corrected total amount values. By default, CorrectAlsoMonoisotopic is set to FALSE.

6.3.2 Calculation thresholds

In normal resolution mode, CalculationThreshold can be set to omit the calculation of natural abundance/tracer purity contribution probabilities that are lower than the threshold. This saves computational resources. The threshold is set to 10^-8 by default and should only be changed with good consideration. CalculationThreshold must be a value between 10^-2 and 0, the lower the value, the more accurate the correction. If set to 0, the threshold is turned off completely.

In high resolution mode CalculationThreshold_UHR can be set to limit the calculation of contribution probabilities. This is done by omitting the calculation of probabilities associated with the total natural abundance incorporation or tracer impurity caused loss of [CalculationThreshold_UHR] tracer isotopes. At CalculationThreshold_UHR = 8 (default), those probabilities can be considered negligible and the threshold should only be changed with good consideration. CalculationThreshold_UHR must be a non-negative integer value, the higher the value, to more accurate the correction. If set to 0, the threshold is turned off completely.