Absolute Smooth Pathway Pipeline

1. What The Method Does

This repository compares two pathway-ranking workflows on controlled human transcriptomic perturbations:

• Standard fgsea: limma moderated t-statistics are ranked from positive to negative and tested with two-sided (scoreType = "std") fgsea.
• Absolute Smooth: absolute limma moderated t-statistics are diffused over a frozen human OmniPath interaction network, then tested with positive-only (scoreType = "pos") fgsea.

The development benchmark contains 93 eligible contrasts in 82 GEO study groups. Alpha is tuned by study-grouped development validation; the complete development selection freezes alpha = 0.2 before evaluation on 56 contrasts from 20 independent GEO studies in nine pathway classes. Each contrast has one prespecified target pathway and three frozen matched-negative pathways.

2. Repository Structure

config/          Fixed alpha grids and random seeds
data_manifest/   Public accessions, contrast designs, pathway labels, and negatives
R/               Analysis functions
scripts/         Download, preprocessing, execution, and verification entry points

Downloaded inputs are written to data/; generated outputs and figures are written to results/<run_id>/. Both directories are intentionally ignored by Git.

3. Installation

Install R 4.6.0, Python 3.12, and the renv package. Python is used only to convert three public Excel supplementary workbooks.

R -e "install.packages('renv'); renv::restore(lockfile = 'renv.lock')"
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -r requirements.txt

The lockfile fixes the R/Bioconductor package environment, including limma, fgsea, edgeR, GEOquery, Biobase, AnnotationDbi, and org.Hs.eg.db.

4. Data Download

No expression, network, pathway-result, or intermediate data are committed. Run:

Rscript scripts/download_inputs.R

The downloader creates the required folders and obtains all inputs from their original public sources. GEO series matrices and annotations come from NCBI GEO; exact accessions, sample selections, and supplementary-file URLs are frozen in data_manifest/. The interaction network is rebuilt from the public OmniPath legacy archive snapshot. The tracked pathway_membership.csv freezes the small SIGNOR/Reactome-derived benchmark pathway labels rather than downloading changing pathway definitions. Every unavailable or empty public download causes a clear failure.

5. Pipeline Execution

From the repository root:

Rscript scripts/run_pipeline.R --run-id reproduction

run_pipeline.R downloads missing public inputs automatically, preprocesses all development and external studies, runs nested development selection, freezes Absolute Smooth at alpha = 0.2, evaluates Standard fgsea and Absolute Smooth on the independent studies, runs phenotype-label permutations, creates the final CSVs and PNG figures, and verifies the key results.

For a faster code-path check after preprocessing:

Rscript scripts/run_pipeline.R --run-id smoke --skip-download --skip-permutations
Rscript scripts/verify_results.R --run-dir results/smoke

Manifest-only verification requires no downloaded data:

Rscript scripts/verify_results.R

6. Expected Key Results

Endpoint	Standard fgsea	Absolute Smooth
Development study-macro AUC	0.643495934959350	0.725609756097561
External study-macro AUC	0.764242424242424	0.826969696969697
External Top-3 recovery	0.732196969696970	0.737727272727273
Significant target rows	28	50
Significant matched-negative rows	26	118
All significant pathway rows	126	389

The external study-level win/tie/loss count is 9/6/5; the exact one-sided sign-flip p-value is 0.275390625. Absolute Smooth improves average pathway-affectedness ranking, but it also reduces selectivity and is not a confirmed universal replacement for Standard fgsea.