singular-value-decomposition-metabolomics
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Apply singular value decomposition (SVD) to metabolite intensity subsets within defined pathways to extract the first principal component as a pathway activity score. This decomposition-based approach is more robust to noise and missing peaks than ORA and GSEA methods, making it well-suited for metabolomics data where such artifacts are prevalent.
When to use
When you have a log2-normalized, zero-mean, unit-variance intensity matrix (rows=metabolites, columns=samples) and a curated metabolite set database (e.g., KEGG pathways, Reactome, or user-defined molecular families), and you need to rank pathways or metabolite groups by their activity level in a way that tolerates missing data and measurement noise. Particularly appropriate when individual metabolite measurements are sparse or unreliable.
When NOT to use
- Input intensity matrix has not been log2-transformed and standardized (unit variance, zero mean); preprocessing must be completed first
- Metabolite annotations are unavailable or unreliable; pathways cannot be mapped to the observed features
- You require gene-level or transcript-level pathway analysis (use transcriptomics/proteomics database IDs such as ENSEMBL or UniProt instead of metabolite IDs)
Inputs
- Log2-normalized intensity matrix: rows are metabolite/peak features with feature ID in column one; subsequent columns are sample intensities; optional second row contains sample group assignments (CSV format)
- Annotation matrix: two-column CSV with peak/feature IDs (column one) mapped to metabolite database IDs (column two, e.g., KEGG compound ID, ChEBI ID, or UniProt ID); multiple IDs can be assigned to a single peak
- Metabolite set database: pathway or molecular family definitions mapping metabolite identifiers to set membership (e.g., KEGG pathway, Reactome metabolic pathway, GNPS Molecular Families, MS2LDA Mass2Motifs)
- Experimental design specification: comparisons as case/control group pairs (e.g., 'beer1/beer2', 'Stage_1/Control') to define which samples constitute each factor
Outputs
- Pathway ranking table: CSV with columns for pathway identifier, pathway name, activity score (first principal component magnitude), p-value (permutation test), coverage metric (unique metabolites detected / total pathway metabolites), and unique formulae/metabolites found in that pathway
- Ranked pathways sorted by activity score magnitude or p-value, enabling interpretation of which pathway activities distinguish the compared groups
How to apply
For each pathway or metabolite set in the database, extract the subset of the intensity matrix corresponding to metabolites assigned to that set. Apply SVD to the subset matrix and extract the first left singular vector (principal component). Use the magnitude of this first principal component as the pathway activity score for that set. Standardize scores across all pathways (zero mean, unit variance) and optionally compute p-values via permutation testing to assess significance. Rank pathways by activity magnitude and compile results into a ranked output table with pathway identifiers, activity scores, and statistical measures (p-value, coverage). The robustness of this approach stems from SVD's ability to capture dominant variance patterns even when some metabolites within a pathway are missing or noisy.
Related tools
- PALS (Pathway Activity Level Scoring) (Implements the complete SVD-based decomposition pipeline including database queries, data imputation, SVD per pathway, score normalization, and statistical significance testing) — https://github.com/glasgowcompbio/PALS
- PALS Viewer (Web interface (Streamlit-based) for running PALS, visualizing ranked pathway results, inspecting significantly changing pathways, and analyzing molecular families from GNPS and Mass2Motifs from MS2LDA) — https://pals.glasgowcompbio.org/app/
- KEGG (Pathway and compound database used for metabolite ID matching and pathway definitions)
- Reactome (Metabolic and signaling pathway database queryable in online (Neo4j) or offline mode; supports metabolite, protein, and gene-level analysis)
- GNPS (Global Natural Products Social Molecular Networking) (Source of Molecular Families metabolite groupings that can be analyzed using PALS decomposition) — http://gnps.ucsd.edu/
- MS2LDA (Source of Mass2Motifs metabolite groupings that can be analyzed using PALS decomposition) — http://ms2lda.org/
Examples
python pals/run.py PLAGE notebooks/test_data/HAT/int_df.csv notebooks/test_data/HAT/annotation_df.csv test_output.csv --db PiMP_KEGG --comparisons Stage_1/Control Stage_2/Control --min_replace 5000
Evaluation signals
- SVD is computed successfully for each pathway subset without numerical errors (singular matrix, rank deficiency); verify that the first singular value is larger than subsequent singular values, indicating dominance of the principal component
- Pathway activity scores sum to zero across all pathways after standardization; min and max scores should be symmetric around zero
- P-values are computed via permutation test and fall in range [0, 1]; pathways with low p-values (< 0.05) should show consistent activity direction across biological replicates
- Coverage metric (detected metabolites / pathway size) should be > 0 for included pathways; pathways with very low coverage (< 10% of metabolites detected) may have inflated p-values due to sparse data
- Ranked results show biological coherence: pathways known to be active in the experimental condition (case group) rank higher than control-specific pathways; results are stable under resampling or cross-validation
Limitations
- Pathway activity score depends on the first principal component only; if metabolites within a pathway show opposing activity trends, the first component may cancel signal and produce low scores despite biological relevance
- Requires complete pathway definitions and metabolite-to-ID mappings; poor annotation quality or missing pathways will reduce coverage and statistical power
- Data imputation (replacing zero intensities with minimum or group mean) may bias SVD if a large proportion of values are missing or below detection limit
- P-value computation via permutation testing is computationally expensive for large pathway databases or high-dimensional sample sets; no correction for multiple hypothesis testing is performed within PALS output (user responsibility)
- SVD-based scores are sensitive to outliers and extreme values; robust preprocessing (log transformation, standardization, outlier handling) is essential
Evidence
- [other] For each pathway, apply PLAGE (Pathway Level Analysis of Gene Expression) decomposition via singular value decomposition (SVD) on the subset of metabolites assigned to that pathway. Extract the first principal component (singular vector) from each pathway's SVD as the pathway activity score.: "For each pathway, apply PLAGE (Pathway Level Analysis of Gene Expression) decomposition via singular value decomposition (SVD) on the subset of metabolites assigned to that pathway. Extract the first"
- [readme] The results are found to be more robust to noise and missing peaks compared to the alternatives (ORA, GSEA). This is particularly important for metabolomics peak data, where noise and missing peaks are prevalent.: "The results are found to be more robust to noise and missing peaks compared to the alternatives (ORA, GSEA). This is particularly important for metabolomics peak data, where noise and missing peaks"
- [readme] decomposes activity levels in pathways via [the PLAGE method]: "decomposes activity levels in pathways via the PLAGE method"
- [readme] The data is subsequently transformed to log-2 base and standardised using the preprocessing module in Scipy such that the intensity matrix has a zero mean and unit variance across the samples.: "The data is subsequently transformed to log-2 base and standardised using the preprocessing module in Scipy such that the intensity matrix has a zero mean and unit variance across the samples."
- [readme] the [decomposition approach] in PALS is amenable to the analysis of any group of metabolite sets, not just pathways: "the decomposition approach in PALS is amenable to the analysis of any group of metabolite sets, not just pathways"
1---2name: singular-value-decomposition-metabolomics-23description: Use when when you have a log2-normalized, zero-mean, unit-variance intensity matrix (rows=metabolites, columns=samples) and a curated metabolite set database (e.4license: CC-BY-4.05---67# singular-value-decomposition-metabolomics89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Apply singular value decomposition (SVD) to metabolite intensity subsets within defined pathways to extract the first principal component as a pathway activity score. This decomposition-based approach is more robust to noise and missing peaks than ORA and GSEA methods, making it well-suited for metabolomics data where such artifacts are prevalent.1314## When to use1516When you have a log2-normalized, zero-mean, unit-variance intensity matrix (rows=metabolites, columns=samples) and a curated metabolite set database (e.g., KEGG pathways, Reactome, or user-defined molecular families), and you need to rank pathways or metabolite groups by their activity level in a way that tolerates missing data and measurement noise. Particularly appropriate when individual metabolite measurements are sparse or unreliable.1718## When NOT to use1920- Input intensity matrix has not been log2-transformed and standardized (unit variance, zero mean); preprocessing must be completed first21- Metabolite annotations are unavailable or unreliable; pathways cannot be mapped to the observed features22- You require gene-level or transcript-level pathway analysis (use transcriptomics/proteomics database IDs such as ENSEMBL or UniProt instead of metabolite IDs)2324## Inputs2526- Log2-normalized intensity matrix: rows are metabolite/peak features with feature ID in column one; subsequent columns are sample intensities; optional second row contains sample group assignments (CSV format)27- Annotation matrix: two-column CSV with peak/feature IDs (column one) mapped to metabolite database IDs (column two, e.g., KEGG compound ID, ChEBI ID, or UniProt ID); multiple IDs can be assigned to a single peak28- Metabolite set database: pathway or molecular family definitions mapping metabolite identifiers to set membership (e.g., KEGG pathway, Reactome metabolic pathway, GNPS Molecular Families, MS2LDA Mass2Motifs)29- Experimental design specification: comparisons as case/control group pairs (e.g., 'beer1/beer2', 'Stage_1/Control') to define which samples constitute each factor3031## Outputs3233- Pathway ranking table: CSV with columns for pathway identifier, pathway name, activity score (first principal component magnitude), p-value (permutation test), coverage metric (unique metabolites detected / total pathway metabolites), and unique formulae/metabolites found in that pathway34- Ranked pathways sorted by activity score magnitude or p-value, enabling interpretation of which pathway activities distinguish the compared groups3536## How to apply3738For each pathway or metabolite set in the database, extract the subset of the intensity matrix corresponding to metabolites assigned to that set. Apply SVD to the subset matrix and extract the first left singular vector (principal component). Use the magnitude of this first principal component as the pathway activity score for that set. Standardize scores across all pathways (zero mean, unit variance) and optionally compute p-values via permutation testing to assess significance. Rank pathways by activity magnitude and compile results into a ranked output table with pathway identifiers, activity scores, and statistical measures (p-value, coverage). The robustness of this approach stems from SVD's ability to capture dominant variance patterns even when some metabolites within a pathway are missing or noisy.3940## Related tools4142- **PALS (Pathway Activity Level Scoring)** (Implements the complete SVD-based decomposition pipeline including database queries, data imputation, SVD per pathway, score normalization, and statistical significance testing) — https://github.com/glasgowcompbio/PALS43- **PALS Viewer** (Web interface (Streamlit-based) for running PALS, visualizing ranked pathway results, inspecting significantly changing pathways, and analyzing molecular families from GNPS and Mass2Motifs from MS2LDA) — https://pals.glasgowcompbio.org/app/44- **KEGG** (Pathway and compound database used for metabolite ID matching and pathway definitions)45- **Reactome** (Metabolic and signaling pathway database queryable in online (Neo4j) or offline mode; supports metabolite, protein, and gene-level analysis)46- **GNPS (Global Natural Products Social Molecular Networking)** (Source of Molecular Families metabolite groupings that can be analyzed using PALS decomposition) — http://gnps.ucsd.edu/47- **MS2LDA** (Source of Mass2Motifs metabolite groupings that can be analyzed using PALS decomposition) — http://ms2lda.org/4849## Examples5051```52python pals/run.py PLAGE notebooks/test_data/HAT/int_df.csv notebooks/test_data/HAT/annotation_df.csv test_output.csv --db PiMP_KEGG --comparisons Stage_1/Control Stage_2/Control --min_replace 500053```5455## Evaluation signals5657- SVD is computed successfully for each pathway subset without numerical errors (singular matrix, rank deficiency); verify that the first singular value is larger than subsequent singular values, indicating dominance of the principal component58- Pathway activity scores sum to zero across all pathways after standardization; min and max scores should be symmetric around zero59- P-values are computed via permutation test and fall in range [0, 1]; pathways with low p-values (< 0.05) should show consistent activity direction across biological replicates60- Coverage metric (detected metabolites / pathway size) should be > 0 for included pathways; pathways with very low coverage (< 10% of metabolites detected) may have inflated p-values due to sparse data61- Ranked results show biological coherence: pathways known to be active in the experimental condition (case group) rank higher than control-specific pathways; results are stable under resampling or cross-validation6263## Limitations6465- Pathway activity score depends on the first principal component only; if metabolites within a pathway show opposing activity trends, the first component may cancel signal and produce low scores despite biological relevance66- Requires complete pathway definitions and metabolite-to-ID mappings; poor annotation quality or missing pathways will reduce coverage and statistical power67- Data imputation (replacing zero intensities with minimum or group mean) may bias SVD if a large proportion of values are missing or below detection limit68- P-value computation via permutation testing is computationally expensive for large pathway databases or high-dimensional sample sets; no correction for multiple hypothesis testing is performed within PALS output (user responsibility)69- SVD-based scores are sensitive to outliers and extreme values; robust preprocessing (log transformation, standardization, outlier handling) is essential7071## Evidence7273- [other] For each pathway, apply PLAGE (Pathway Level Analysis of Gene Expression) decomposition via singular value decomposition (SVD) on the subset of metabolites assigned to that pathway. Extract the first principal component (singular vector) from each pathway's SVD as the pathway activity score.: "For each pathway, apply PLAGE (Pathway Level Analysis of Gene Expression) decomposition via singular value decomposition (SVD) on the subset of metabolites assigned to that pathway. Extract the first"74- [readme] The results are found to be more robust to noise and missing peaks compared to the alternatives (ORA, GSEA). This is particularly important for metabolomics peak data, where noise and missing peaks are prevalent.: "The results are found to be more robust to noise and missing peaks compared to the alternatives (ORA, GSEA). This is particularly important for metabolomics peak data, where noise and missing peaks"75- [readme] decomposes activity levels in pathways via [the PLAGE method]: "decomposes activity levels in pathways via the PLAGE method"76- [readme] The data is subsequently transformed to log-2 base and standardised using the preprocessing module in Scipy such that the intensity matrix has a zero mean and unit variance across the samples.: "The data is subsequently transformed to log-2 base and standardised using the preprocessing module in Scipy such that the intensity matrix has a zero mean and unit variance across the samples."77- [readme] the [decomposition approach] in PALS is amenable to the analysis of any group of metabolite sets, not just pathways: "the decomposition approach in PALS is amenable to the analysis of any group of metabolite sets, not just pathways"
HolobiomicsLab