4 Advanced options

TraceGroomer offers the necessary options to normalise the data, and also allows to perform additional data formatting.

Two types of normalisations are possible:

• The isotopologue absolute values (or the metabolite total abundances alone if specified) can be normalized by the amount of material.
• The metabolite total abundances can be normalized by an internal standard.

The combination is also possible, e.g. normalise the data by the amount of material and also by the internal standard.

Details of the advanced parameters

In addition to the basic parameters (-lm labeled metabolomics file, -tf type of file, and -cf configuration file), for any of the four types of input, specific advanced parameters are offered:

Parameters related to the normalisation by the amount of material

• --amountMaterial_path: str. Absolute path to the file having the amount of material by sample, for the normalization. This file must be a tab delimited file with exactly 2 columns with a header: the first column contains the original names of the samples, and the second column the numbers (tissue weight, number of cells, volume, etc).

  When providing this file, the division of the absolute values by the amount of material is performed automatically, across all isotopologues (or metabolites) for each sample. See also --alternative_div_amount_material and --div_isotopologues_by_amount_material.

  If this parameter is left as None (simply not used), the normalisation by the amount of material is not performed.

  Default: None.

• --alternative_div_amount_material: bool. In the normalisation by the amount of material, not only the division of the given absolute values by these amounts is performed, but also the product of the resulting quotients and the averaged amount of material is computed. This guarantees to stay in abundance units, for each isotopologue (and/or metabolite) and sample, example:

  • (q unit/microgram) * (avg(a) microgram) = q*avg(a) unit

  This procedure (quotient * avg) is performed by default. The user can change it to False using --no-alternative_div_amount_material: in this case, the division returns the quotients only (e.g. q unit/microgram).

  Default: True.

• --div_isotopologues_by_amount_material: bool. Apply normalization by the amount of material at the level of isotopologue absolute values. Immediately after this, and before any other computation, tracegroomer re-computes all derived (thus normalized) metrics.

  To disable the default behavior (change to False) use --no-div_isotopologues_by_amount_material: in this case, instead the isotopologue absolute values, only the total metabolite abundances are subjected to the normalisation.

  Default: True

Important

For safety reasons, TraceGroomer normalises in first place by the amount of material (before any other type of normalisation). When choosing to normalise the isotopologues absolute values, all the derived metrics are re-computed: thus the obtained total abundances are normalized (no need to re-normalize the total abundances, this is ensured internally).

Parameters related to the normalisation by an internal standard

• --use_internal_standard: str. The name of the internal standard, which is a compound or metabolite that has been stated as reference signal. By providing this name, the normalization by the internal standard is automatically performed. To note, this operation is exclusively applied to the total metabolite abundances.

  The internal standard name must be a valid string: i) the compound must exist in the input data (data that has been given by the user through the -lm parameter), and ii) without spaces ' ' within. One example of such a name is Myristic_acid_d27. By providing a valid name, the division: total_abundances/internal_standard, is automatically computed for each metabolite across all samples.

  If this parameter is left as None (simply not used), the normalisation by the internal standard is not performed.

  Default: None.

  Important: Internal standards are never normalized by the amount or material, following the recommendation of expertise platforms.

Parameters related to data characteristics

• --isotopologues_preview: bool. Generate simple plots that give a general overview of the isotopologue proportions given by the user. Performs a scatter plot of the individual isotopologue proportions for all metabolites, as well as a plot of the sums of isotopologue proportions (the sum must be equal to 1 for each metabolite and sample). Default: False (i.e. --no-isotopologues_preview)

• --remove_these_metabolites: str. Absolute path to the tab delimited file with columns: compartment, metabolite. This file lists the metabolites to be completely excluded, compartment specific. Defining such exclusion list requires deep knowledge of the data by the user (measurements coherence/quality, etc). Default: None.

• --isosprop_min_admitted float. Metabolites whose isotopologue proportions are less or equal to this cutoff, are removed. To disable this behavior, set to -2. Default: -0.5

• --fractions_stomp_values: bool. Stomps fractional contributions (synonym: mean enrichment), and isotopologue proportions, to max 1.0 and min 0.0. Default: True

Parameters of exclusive usage for VIB-MEC data holders

Exclusively in the case that the user provides VIB-MEC data input, additional parameters are available. This is due to the fact that VIB data provides total abundances data obtained across the samples and also the blanks or mocks:

• --subtract_blankavg: from samples' abundances, subtracts the average of the blanks for all metabolites across all samples. Note that the Internal Standards are not subjected to this operation, as recommended by VIB platform. To disable this behavior (change to False) use --no-subtract_blankavg. Default:True

• --under_detection_limit_set_nan: The Limit Of Detection, LOD, corresponds to the averaged blanks abundance values, multiplied by three times the blanks standard deviation. By default, any value that is strictly inferior to its corresponding LOD, is converted into NaN. For setting to False to disable this behavior, use --no-under_detection_limit_set_nan. Default:True

---

Usage examples

Normalising by the amount of material

1. Example with defaults:

python -m tracegroomer -lm ~/examples_TraceGroomer/data/example-isocor_data/TRACER_IsoCor_out_example.tsv -tf IsoCor_out_tsv -cf ~/examples_TraceGroomer/groom_files/example-isocor/config-1-groom.yml \
--amountMaterial_path ~/examples_TraceGroomer/groom_files/example-isocor/amount_material_weightorcells.csv

The amountMaterial_path, if is a valid file as in the code snippet above, automatically triggers the normalisation by the amount of material.

The other parameters were left with defaults (--div_isotopologues_by_amount_material and --alternative_div_amount_material). This means that TraceGroomer will apply, at the level of isotopologues' absolute values, the alternative way of computation as explained above, it is, "quotient * avg".

2. Example to return only quotients:

python -m tracegroomer -lm ~/examples_TraceGroomer/data/example-isocor_data/TRACER_IsoCor_out_example.tsv -tf IsoCor_out_tsv -cf ~/examples_TraceGroomer/groom_files/example-isocor/config-1-groom.yml --amountMaterial_path ~/examples_TraceGroomer/groom_files/example-isocor/amount_material_weightorcells.csv
--no-alternative_div_amount_material

In this case, the --div_isotopologues_by_amount_material is unchanged as in the example above (True), so isotopologues absolute values are normalised. The difference is that --no-alternative_div_amount_material makes the computation to return only the quotients (e.g. will return unit).

3. Examples to apply normalisation only to the total abundances, and return only quotients:

On the IsoCor example data:

python -m tracegroomer -lm ~/examples_TraceGroomer/data/example-isocor_data/TRACER_IsoCor_out_example.tsv -tf IsoCor_out_tsv -cf ~/examples_TraceGroomer/groom_files/example-isocor/config-1-groom.yml \
 --amountMaterial_path ~/examples_TraceGroomer/groom_files/example-isocor/amount_material_weightorcells.csv \
 --no-div_isotopologues_by_amount_material
 --no-alternative_div_amount_material

On the VIB-MEC example data:

python -m tracegroomer -lm ~/examples_TraceGroomer/data/example-vib_data/TRACER_metabo_4.xlsx -tf VIBMEC_xlsx -cf ~/examples_TraceGroomer/groom_files/example-vib/config-4-groom.yml \
--amountMaterial_path ~/examples_TraceGroomer/groom_files/example-vib/nbcells-or-amountOfMaterial.csv \
--no-div_isotopologues_by_amount_material \
--no-alternative_div_amount_material