ssCCA — single-sample Chemical Class Analysis

Analysis code for integrating multiple metabolomics datasets by grouping metabolites into shared chemical classes derived from the ChEBI ontology, rather than requiring exact metabolite-level overlap across datasets. Each sample receives a per-class score, allowing datasets that share few individual metabolites to be combined for multivariate analysis (PCA, PLS-DA) and batch-effect assessment (PVCA).

This repository contains the analysis pipeline used for the accompanying report. It is provided as runnable scripts (not as an installable package) so that the exact steps behind the reported results can be reproduced and inspected.

---

Repository structure

.
├── core/         # the Stage 1–4 analysis pipeline
├── benchmark/    # the validation / benchmarking study
├── figures/      # cross-scenario figure generation
├── requirements.txt
└── README.md

core/ — the pipeline

Script	Role
Stage1_chebi_id_annotation.py	Assigns ChEBI IDs to metabolite names via the ChemEquivMapper pipeline.
Stage2_chebi_class_mapping.py	Groups metabolites into shared chemical classes using the ChEBI ontology DAG (the ssCCA class mapping).
Stage2_refmet_classyfire_class_mapping.py	Alternative chemical-class mapping via RefMet and ClassyFire.
Stage2_ssPA_mapping_scoring.py	Single-sample pathway analysis (ssPA) scoring — the pathway-level comparator.
Stage3_ssCCA_scoring.py	Computes one representative score per chemical class per sample.
Stage4_integration_MVA.py	Merges the per-class (or per-pathway) score matrices and runs PCA / PLS-DA / PVCA.

The three Stage2_* scripts are alternative mapping strategies that feed the same downstream analysis; the ChEBI-DAG route is the ssCCA method, and the RefMet/ClassyFire and ssPA routes are comparators.

benchmark/ — the validation study

ssCCA_validation.py evaluates ssCCA against baseline integration methods (direct metabolite-level merge, ssPA, ComBat, and RefMet/ClassyFire class mapping) under controlled metabolite-overlap degradation, reporting PVCA disease-variance and PLS-DA discrimination as metabolite overlap is progressively reduced. It imports the core/ scripts as modules.

figures/ — figure generation

cross_scenario_figure.py builds the combined cross-scenario figure (coverage, PCA statistics, and PLS-DA panels) from the per-scenario result workbooks.

---

Pipeline flow

tidy CSV
   │  Stage 1  ── annotate metabolite names → ChEBI IDs
   ▼
<stem>_ChEBI_tidy.csv
   │  Stage 2  ── map each metabolite to a shared chemical class
   ▼             (ChEBI DAG  |  RefMet/ClassyFire  |  ssPA pathways)
class-assigned CSV
   │  Stage 3  ── one representative score per class per sample
   ▼
per-class score CSV
   │  Stage 4  ── merge datasets → PCA / PLS-DA / PVCA
   ▼
integrated multivariate analysis + reports

The benchmark/ study runs this pipeline repeatedly under perturbed overlap; figures/ summarises results across scenarios.

---

Installation

Python 3.10+ is recommended.

git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>
python -m venv .venv && source .venv/bin/activate   # optional
pip install -r requirements.txt

Additional dependencies (not on PyPI)

ChemEquivMapper — required by Stage1 and Stage2_ssPA for ChEBI annotation:

git clone https://github.com/tiganouri/ChemEquivMapper.git
pip install -e ChemEquivMapper

R + lme4 + rpy2 — optional. Enables the R/lme4 REML backend for PVCA (used by Stage4 and the benchmark). If R/rpy2 are not available, the code automatically falls back to a Python ANOVA-based variance-component proxy; the reported results use the R backend.

Data resources

The scripts resolve the ChEBI OBO ontology from a local chebi.obo in the working folder, downloading it from the EBI FTP server on first run if absent. Reactome and KEGG resources used by the ssPA steps are downloaded and cached on first use.

---

Usage

Each script has a single CONFIGURATION block at the top — edit it, then run the script. No command-line arguments are used.

# from core/
python Stage1_chebi_id_annotation.py
python Stage2_chebi_class_mapping.py
python Stage3_ssCCA_scoring.py
python Stage4_integration_MVA.py

In each config block, set INPUT_DATASETS to your input files, for example:

INPUT_DATASETS = [
    {"path": "DATASET_A_ChEBI_tidy.csv", "label": "DATASET_A"},
    {"path": "DATASET_B_ChEBI_tidy.csv", "label": "DATASET_B"},
]

Input format (tidy CSV): column A is Metabolite_name, column B is the identifier (ChEBI_ID or RefMet_name), remaining columns are per-sample values, and metadata rows (e.g. Diagnosis, Sex) sit at the top.

Running the benchmark

ssCCA_validation.py expects to be run from the benchmark/ folder, where its default paths point at ../core/:

cd benchmark
python ssCCA_validation.py

---

Software and data availability

This repository contains the analysis code for the report. Study datasets are identified in the report; input files are not redistributed here. The example configuration uses placeholder file names (DATASET_A, input_table_a.csv) and generic group labels (GROUP_1, GROUP_2); replace these with your own.

The ssCCA method is also available as a separate Python package (see the report's Software and data availability statement).

---

License

Released under the BSD 3-Clause License. See LICENSE.

Citation

If you use this code, please cite the accompanying report. Method references used by the pipeline (Li et al. 2009 for PVCA; Wieder et al. 2022 for ssPA; Tomfohr et al. 2005 and Lee et al. 2008 for the class scoring; Savage et al. 2019; Pinto et al. 2022; Johnson et al. 2007) are listed in each script's References docstring section.