Quantitative Mode Metabolomics Configuration

quantitative-mode-metabolomics-configuration

Summary

Configure and validate the input data structure for quantitative metabolomics meta-analysis by specifying column mappings, selecting mode='quan', and handling missing and negative fold-change values. This skill ensures metabolomics datasets from heterogeneous sources (xls/xlsx/csv/txt) conform to the required tibble schema before statistical combination.

When to use

When you have metabolomics results from multiple studies reporting compound identifiers, p-values, fold-changes, and study sizes (N), and you need to prepare them for quantitative meta-analysis using weighted Fisher's method and logarithmic fold-change combination. This skill is required before computing global significance and effect size estimates across studies.

When NOT to use

• Input dataset already contains error/variance or standard deviation columns—use standard meta-analysis tools (e.g., metafor) instead, as amanida is specifically designed for metabolomics studies lacking variance data.
• You only have compound identifiers and trend labels (up/down regulation) without p-values and fold-changes—use qualitative vote-counting mode (mode='qual') instead.
• Raw individual-level data is available—aggregate it to study-level summary statistics (p-value, fold-change, N) before using this skill.

Inputs

• metabolomics results file (xls, xlsx, csv, or txt format)
• column name mapping vector specifying: compound identifier, p-value, fold-change, N, reference
• file separator specification (e.g., semicolon, comma, tab)

Outputs

• tibble data structure with columns: compound identifier, p-value, fold-change (positive values), N, reference
• S4 object suitable for input to compute_amanida() quantitative meta-analysis function

How to apply

Call amanida_read() with mode='quan' and specify the coln parameter as a vector listing column names in this exact order: [compound identifier, p-value, fold-change, N (study size), reference]. The function will parse the input file (xls/xlsx/csv/txt format), map columns accordingly, ignore any rows with missing data, and transform negative fold-change values to positive using the reciprocal formula (1/value). Validate the output tibble structure and data types before passing to compute_amanida() for meta-analysis. This transformation is necessary because metabolomics reports relative change via fold-change (not difference of means), and negative fold-changes represent down-regulation but must be expressed as positive reciprocals to maintain directionality in the weighted combination step.

Related tools

• amanida (R package implementing amanida_read() function for quantitative metabolomics data import and configuration; handles column mapping, missing data, and fold-change reciprocal transformation) — https://github.com/mariallr/amanida
• webchem (optional tool for downstream compound ID harmonization via PubChem lookup (used in check_names() after amanida_read()))
• R (execution environment for amanida package and tibble data structure operations)

Examples

coln = c("Compound Name", "P-value", "Fold-change", "N total", "References"); datafile <- amanida_read("colorectal_cancer_urine.csv", mode = "quan", coln, separator=";")

Evaluation signals

• Output tibble has exactly 5 columns with correct names and data types: character (identifier, reference), numeric (p-value, fold-change, N)
• All fold-change values are positive; any original negative values have been transformed via 1/value reciprocal
• No rows with missing data appear in output (NA handling verified by row count comparison with input)
• P-value range is [0, 1] and N values are positive integers ≥ 1
• Output tibble is compatible with compute_amanida() function signature without errors or type coercion warnings

Limitations

• Missing data is silently ignored (rows dropped); no reporting of how many records were excluded due to incompleteness
• Negative fold-change transformation via 1/value assumes bidirectional symmetry around 1.0; extreme values (e.g., FC < 0.01) may produce very large reciprocals
• Column order in coln parameter is strict and position-dependent; misspecification silently maps wrong columns and corrupts analysis
• Only supports xls/xlsx/csv/txt formats; does not read JSON, XML, or proprietary mass spectrometry data formats
• Does not validate biological plausibility of fold-change or p-value ranges before meta-analysis (garbage-in, garbage-out)

Evidence

• [intro] Dataset to analyse must include the following columns: identifier, p-value, fold-change, study size (N) and reference: "Dataset to analyse must include the following columns: identifier, p-value, fold-change, study size (N) and reference"
• [readme] Supported files are csv, xls/xlsx and txt. For quantitative meta-analysis include the following parameters: Indicate mode = "quan": "Supported files are csv, xls/xlsx and txt. For quantitative meta-analysis include the following parameters: Indicate mode = "quan""
• [readme] coln: vector containing the column names, which need to be in this order: Id: compound name or unique identification, P-value, Fold-change, N: number of individuals in the study, Reference: "coln: vector containing the column names, which need to be in this order: Id: compound name, P-value, Fold-change, N: number of individuals, Reference"
• [other] During import, missing data is ignored and negative fold-change values are transformed to positive using the reciprocal formula (1/value): "missing data is ignored and negative fold-change values are transformed to positive using the reciprocal formula (1/value)"
• [intro] negative values of fold-change are transformed to positive (1/value): "negative values of fold-change are transformed to positive (1/value)"
• [readme] only using p-value and fold-change, global significance and effect size for compounds or metabolites are obtained: "only using p-value and fold-change, global significance and effect size for compounds are obtained"
• [readme] coln = c("Compound Name", "P-value", "Fold-change", "N total", "References"); datafile <- amanida_read(input_file, mode = "quan", coln, separator=";"): "coln = c("Compound Name", "P-value", "Fold-change", "N total", "References"); amanida_read(input_file, mode = "quan", coln, separator=";")"