ExprDecay

Code accompanying the ExprDecay paper on gene-level relative mRNA-stability prediction from public expression profiles.

ExprDecay fits source-specific models to ordered HPA cell-line, GTEx tissue, and TCGA/Toil sample profiles. It calibrates candidate predictions against training-fold empirical distributions and selects a greedy rank blend on a separate validation fold. The output is a unitless relative gene score, not an absolute half-life estimate, isoform-level prediction, or causal effect.

This repository contains source code only. Data, checkpoints, results, logs, figures, and manuscript files are excluded.

Repository layout

• src/exprdecay/: data loaders, candidate models, rank stacking, checkpoints, CLI workflows, controls, and reporting helpers.
• scripts/: final-paper robustness, RNADecayCafe, Nucleotide Transformer, Saluki, and mRNABench analyses.

Installation

The paper analyses used Python 3.13.11. The package supports Python 3.11 or newer and is locked with uv.

uv sync --locked

Install optional dependencies only for the corresponding analyses:

uv sync --locked --extra foundation  # Nucleotide Transformer ablation
uv sync --locked --extra saluki      # released Saluki reconstruction/inference

Show available commands:

uv run exprdecay --help

External inputs

Run commands from the repository root. Default paths follow this layout and can be overridden with command-line arguments:

Path	Role
data/processed/saluki_genetic_biochemical_matrix.npz	inherited benchmark targets, folds, gene bridge, and feature matrix
data/processed/mrna_half-life.csv	mature transcript sequences used by sequence-alignment analyses
data/sources/hpa/rna_celline.tsv.zip	HPA cell-line expression
data/sources/gtex/GTEx_Analysis_2017-06-05_v8_RNASeQCv1.1.9_gene_median_tpm.gct.gz	GTEx tissue-median expression
data/sources/xena/tcga_RSEM_gene_tpm.gz	TCGA/Toil expression
data/sources/saluki/datasets/human/all_HLs_human_featTable.txt.gz	Saluki feature table used for the benchmark bridge and leakage audit
data/sources/saluki/	remaining released Saluki predictions and source files
data/sources/rnadecaycafe/	RNADecayCafe source tables
data/sources/hgnc/hgnc_complete_set.txt	HGNC mapping snapshot

The benchmark NPZ must contain X, y, folds, geneids, and feature_cols. This repository does not reconstruct the processed benchmark bridge. Training also runs the leakage audit, so the Saluki feature table is required for expression_only. Obtain source datasets and pretrained models from the versions cited in the paper and confirm their redistribution terms before sharing them.

Core model

Train one inherited benchmark rotation of the final expression-only model:

uv run exprdecay train-stack \
  --track expression_only \
  --test-fold 0 \
  --val-fold 1 \
  --seed 17

The command writes fold metrics, predictions, scored predictions, and validation-selected blend steps under results/biology/runs/ unless an output directory is supplied.

Build or resume the ten benchmark and ten external-inference checkpoint ensembles:

uv run python scripts/train_model_checkpoints.py

Apply saved external-inference checkpoints to new Ensembl gene IDs:

uv run exprdecay predict-expression \
  --checkpoint-dir checkpoints/exprdecay/rnadecaycafe_expression_seed17 \
  --geneids path/to/geneids.csv \
  --output results/predictions/expression_predictions.csv

Paper analyses

The retained scripts reproduce analyses reported in the final manuscript:

• run_context_identity_control.py: capacity-matched sorted-profile control.
• run_multiseed_robustness.py: designated-seed selection stability.
• run_manuscript_readiness_analyses.py: pooled benchmark estimates, ablations, uncertainty, and source audits.
• run_rnadecaycafe_readiness_analyses.py: external-cohort controls, sensitivities, and clustered uncertainty.
• run_foundation_embedding_ablation.py: frozen Nucleotide Transformer probe.
• run_mrnabench_comparison.py: exact sequence bridge and reconstructed mRNABench partitions.
• fetch_saluki_checkpoints.py, validate_saluki_adapter.py, build_rnadecaycafe_saluki_inputs.py, and run_saluki_rnadecaycafe.py: released-Saluki reconstruction and same-row comparison.

These scripts write to ignored results/ and checkpoints/ directories by default. Some require network access, GenomeKit, PyTorch, a GPU for practical runtime, or prior outputs from another analysis.

Checks

uv run --locked ruff check src scripts
uv run --locked basedpyright

Reproducibility boundary

The source code alone is not a complete reproduction archive. Reproducing the paper's numerical results requires the exact processed benchmark, source-data snapshots, released model files, and analysis populations described in the paper.

No software license has been selected. Add an author-approved license before publishing or redistributing this repository.