Torch-eCpG v2.0.0 Beta 2

Torch-eCpG v2.0.0 Beta 2

Second beta pre-release of Torch-eCpG v2 — a GPU-accelerated eQTM mapper that
maps every CpG × gene pair and then tells you, on your own data, which
associations to believe. Cut from dev (527 commits since Beta 1, 2026-05-29). Presented as a poster
at the 21st International Conference on Computational Intelligence Methods for
Bioinformatics and Biostatistics (CIBB 2026), Sapienza Università di Roma,
Rome, 2–4 September 2026.

Usable now; testing and feedback welcome. Flags, output columns, and defaults
may still change before 2.0.0. main remains the published v1 (Kober et al.
2024, BMC Bioinformatics 25:71).

Install

pip install git+https://github.com/kordk/torch-ecpg@v2.0.0-beta.2

Container (CUDA 12.4.1 base, full pipeline): docker build -t tecpg-pipeline -f docker-related/Dockerfile . — see docker-related/README.md.

What's new since Beta 1

Permutation testing (new backend). --mlr-method qr_permute scores a
mapping catalog against a design-fixed Freedman–Lane null: batched-QR observed
statistics, cis/trans masking, null-population subsampling, empirical p-values
with a GPD peaks-over-threshold tail, and a persisted .npz null accumulator.
pipelinePermute.sh drives it end to end — reservoir or gene-anchored master,
region annotation, seven-way per-region calibration (eval_permute,
summarize_permute), a self-contained QC report (bulk calibration, direction,
verdict robustness, permutation resolution, tail, analytic-p precision) — and
writes p_permute / fdr_permute onto the mainline catalog alongside, never
over, the analytic values.

Single-point influence screen. --compute-influence emits each CpG's
maximum sample leverage (mt_h_max) from the QR factor at mapping time.
tools/flagInfluence_parquet.py derives mt_influence_flag under a
covariate-floor rule, pipelinePost.sh filters flagged CpGs into a single
retained universe for every downstream stage, and the influence QC report,
calibration bridge, dose-response / SE-ratio figures, and per-pair anatomy
panels show what deleting the highest-leverage subject does to a fit.

Integrated Gradients as a readout. IG on the bootstrap candidates
(compute_ig, deep variant, baseline and covariate-filter options),
tools/evaluateSaliency.py (rank-window profiles, fraction diagnostics, and a
--frac-exclude second denominator that sets expression-derived covariates
aside), and tools/ig_qc_report.py (coverage, ranking-axis redundancy, drivers
of magnitude, methylation share of attribution, per-region IG).

Annotation. GENCODE-derived probe → gene model; region assignment from
gene spans into seven strand-aware regions (PROMOTER, GENEBODY, CIS5, CIS3,
DISTAL5, DISTAL3, TRANS); drop-if-ambiguous probe/symbol resolvers; gzipped
annotation reads; demo BEDs regenerated without fabricated positions; a
region-composition crosswalk to Kennedy's four categories.

Enrichment and networks. Kennedy Fig. 6-style chromatin-feature
enrichment (tools/chromatin_features.py, tools/chromatinEnrichment_parquet.py;
Fisher exact, BH, log-OR heatmap); functional enrichment extracted to
tools/runEnrichment.py with an HTML summary; network export on the
FDR-significant universe (--max-fdr); signed biclustered heatmap,
hypergeometric gene–gene projection, and per-region figures.

Mapping engine. Batched QR bootstrap solver replacing lstsq (with a
degenerate-resample guard); seeded bootstrap and namespaced provenance columns
(boot_seed, perm_seed, perm_n_perm) so any resampled result is
reproducible from the catalog; degrees of freedom derived unconditionally from
C.csv; between-sample quantile normalization of expression; per-cell integer
counts behind every reported rate.

Pipelines and benchmark. pipeline.sh split into pipelinePre.sh (450k
probe blacklist by default with a guard, EpiDISH cell fractions, covariate
residualization and PCA, ancestry instruments, MESA clinical encoding,
concurrent GTP/MESA runs) and a nine-stage core; an eleven-stage
pipelinePost.sh; pipelineBenchmarkKennedy.sh with eligibility
decomposition, blacklist audit, sign / t-statistic concordance,
influence-stratified recovery; the gtpsub dataset and tools/subsample_loci.py.

Verified on the GTP run of record (2026-08-26, one NVIDIA L4)

• 340 samples · 335,630 CpGs × 39,352 genes · 17 covariates · 13.2 B tests mapped in 18.7 min; full pipeline through a 1,000-resample bootstrap in 2 h 12 min.
• 50,237 pairs at FDR < 0.05 (p ≤ 1.9 × 10⁻⁷); 34,839 after the leverage screen; λ = 1.004 on a 1 M-pair reservoir.
• Kennedy et al. 2018 benchmark at matched p ≤ 10⁻¹¹: 15,565 / 15,566 shared pairs sign-concordant, t-statistic r = 0.94, recovery 47 % (82 % at 10⁻⁵).
• Permutation QC (100 permutations): bulk median p_perm / p_ana = 1.005 in every region — single global null adequate.
• Influence: 4.5 % of CpGs carry 31.8 % of significant trans pairs; at δ = 0.1, 76 % of flagged pairs are bootstrap-unstable vs 1.2 % of kept.

Known limitations

• Pre-release API: flag names, output columns, and defaults may change before 2.0.0.
• The permutation tail below the resolution floor (2.6 × 10⁻⁹ at 100 permutations) is unresolved, not validated; raise --permutations to probe it.
• A per-pair drop-one |t| ratio is computed by the anatomy tool only; it is not emitted catalog-wide.
• visualizeBipartiteNetwork.py's biclustered heatmap can exceed Python's recursion limit on large networks (the other network figures are unaffected).
• The Docker Hub image (kordk/torch-ecpg) is v1; the v2 container is built locally from docker-related/.
• MESA results are in progress; GTP is the validated cohort in this release.

Full history: [CHANGELOG.md](https://github.com/kordk/torch-ecpg/blob/v2.0.0-beta.2/CHANGELOG.md) · compare [v2.0.0-beta.1...v2.0.0-beta.2](https://github.com/kordk/torch-ecpg/compare/v2.0.0-beta.1...v2.0.0-beta.2)

Citation

Tool: Kober KM, Berger L, Roy R, Olshen A. Torch-eCpG: a fast and scalable eQTM mapper for thousands of molecular phenotypes with graphical processing units. BMC Bioinformatics. 2024;25:71. https://doi.org/10.1186/s12859-024-05670-4

This release: Kober K, Rau A, Olshen A. Torch-eCpG v2: a scalable and interpretable framework for eQTM mapping and multi-omic network analysis [poster]. 21st International Conference on Computational Intelligence Methods for Bioinformatics and Biostatistics (CIBB 2026); 2026 Sep 2–4; Sapienza Università di Roma, Rome, Italy.

Supported by an NIH NCI MERIT award (R37 CA233774, PI: Kober) and a Cancer Center Support Grant (P30 CA082103, Co-I: Olshen).