genboostgpu 0.2.0

GENBoostGPU provides a scalable framework for running elastic net regression with boosting across thousands of CpG sites, leveraging GPU acceleration with RAPIDS cuML, CuPy, and cuDF.

GENBoostGPU

Genomic Elastic Net Boosting on GPU (GENBoostGPU)

GENBoostGPU provides a scalable framework for running elastic net regression with boosting across thousands of CpG sites, leveraging GPU acceleration with RAPIDS cuML, CuPy, and cuDF.
It supports SNP preprocessing, cis-window filtering, LD clumping, missing data imputation, and phenotype integration — all optimized for large-scale epigenomics.

---

Features

• Window-based orchestration:
  • run_windows_with_dask coordinates execution across one or more GPUs using Dask.
  • Handles batch scheduling of thousands of genomic windows.
• Single-window analysis:
  • run_single_window executes boosting elastic net on one genomic region.
  • Accepts pre-loaded arrays (CuPy) or file paths (PLINK, phenotype tables).
• GPU-accelerated boosting elastic net:
  • Iterative boosting with cuML ElasticNet and final Ridge refit.
  • Early stopping based on stability of variance explained.
• Automated SNP preprocessing:
  • Zero-variance SNP filtering
  • Missing genotype imputation
  • LD clumping (PLINK-like) with CuPy
  • Cis-window SNP filtering
• Hyperparameter optimization:
  • Optuna-based tuning of ElasticNet (alpha, l1_ratio)
  • Ridge regression tuning with delayed evaluation
  • Optional manual cross-validation for custom grids
• Scalability:
  • Dask orchestration for multiple GPUs (LocalCUDACluster)
  • Single-GPU fallback for smaller jobs
• Flexible outputs:
  • SNP betas, heritability estimates, variance explained
  • Window-level summary tables (.parquet)
  • Intermediate ridge/elastic net models for reproducibility

---

Installation

GENBoostGPU is available on PyPI.
It requires Python ≥3.10 and an NVIDIA GPU with CUDA 12.x.

pip install genboostgpu

For development (from source):

git clone https://github.com/heart-gen/GENBoostGPU.git
cd GENBoostGPU
poetry install

---

Usage

GENBoostGPU can be used either for large-scale orchestration (many genomic windows across one or more GPUs) or for single-window testing/debugging.

---

Example 1: Run a Single Window

The simplest entry point is run_single_window, which takes either:

• File paths (PLINK genotypes + phenotype file + phenotype ID), or
• Pre-loaded CuPy arrays for genotypes and phenotypes.

from genboostgpu.vmr_runner import run_single_window

result = run_single_window(
    chrom=21,
    start=10_000,
    end=510_000,
    geno_path="data/chr21_subset.bed",
    pheno_path="data/phenotypes.tsv",
    pheno_id="pheno_379",
    outdir="results",
    n_iter=50,
    n_trials=10
)

print(result)

Output is a Python dictionary, e.g.:

{
  "chrom": 21,
  "start": 10000,
  "end": 510000,
  "num_snps": 742,
  "final_r2": 0.34,
  "h2_unscaled": 0.29,
  "n_iter": 37
}

This produces:

• Window-level summary (Python dict)
• Saved results (.parquet, betas, heritability estimates) in results/

---

Example 2: Running on VMR Data

REGION=caudate python examples/vmr_test_caudate.py

Script outline (examples/vmr_test_caudate.py):

from genboostgpu.orchestration import run_windows_with_dask

df = run_windows_with_dask(
    windows, error_regions=error_regions,
    outdir="results", window_size=500_000,
    n_iter=100, n_trials=20, use_window=True,
    save=True, prefix="vmr"
)

This runs boosting elastic net across all VMR-defined windows for the chosen region.

---

Example 3: Running on Simulated Data

NUM_SAMPLES=100 python examples/simu_test_100n.py

Script outline (examples/simu_test_100n.py):

from genboostgpu.orchestration import run_windows_with_dask

df = run_windows_with_dask(
    windows, outdir="results", window_size=500_000,
    n_iter=100, n_trials=10, use_window=False,
    save=True, prefix="simu_100"
)

This runs boosting elastic net across synthetic SNP–phenotype pairs for benchmarking.

---

GPU Scaling

• On a single GPU: runs without a Dask cluster.
• On multiple GPUs: run_windows_with_dask automatically launches a LocalCUDACluster and distributes windows across devices.

---

Citation

If you use GENBoostGPU in your research, please cite:

Alexis Bennett and Kynon J.M. Benjamin GENBoostGPU: GPU-accelerated elastic net boosting for large-scale epigenomics DOI: 10.5281/zenodo.17238798

---

License

GENBoostGPU is licensed under the GPL-3.0 license. See the LICENSE file for details.

---