Skip to content

v0.4.0

Choose a tag to compare

View all tags
@KrotosBenjamin KrotosBenjamin released this 02 Oct 15:10
· 2 commits to main since this release
v0.4.0
cef4c0c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

GENBoostGPU v0.4.0 — Local genetic variance engine, deterministic replay & faster GPU site analysis

GENBoostGPU v0.4.0 is a major methods and performance release. It introduces a new engine for local genetic variance analyses at both region and individual-site scale, with R-faithful elastic-net numerics, deterministic replay across compute environments, integrated HE and GEMMA BSLMM estimation, and substantially faster GPU execution.

This release also expands GENBoostGPU beyond the original boosting workflow toward the analysis framework used for the current manuscript endpoints.

Highlights

  • New local genetic variance engine for region- and site-level analyses through genboostgpu.lgv, genboostgpu.lsp, and genboostgpu.sites.
  • R-faithful glmnet implementation with CPU results bitwise identical to R/glmnet 4.1-10 and GPU results agreeing to numerical rounding.
  • Deterministic replay of folds, SNP screening, HE estimates, effective predictor counts, LD calculations, and GEMMA BSLMM results.
  • ~3× faster GPU glmnet batches, with substantial reductions in host-memory use and device-transfer overhead.
  • Nearly 2× higher end-to-end site throughput through vectorized summaries and overlapped CPU/GPU execution.
  • Independent CPU execution of GEMMA BSLMM, allowing expensive site-scale GPU and CPU components to be scheduled separately.
  • Expanded PLINK1/PLINK2 and CpG/CpH support for large regional and million-site studies.

✨ New local genetic variance engine

v0.4.0 introduces the analysis engine used for the manuscript endpoints:

  • genboostgpu.lgv — local genetic variance workflows and joint-model features.
  • genboostgpu.lsp — local SNP contribution scoring.
  • genboostgpu.sites — high-throughput CpG/CpH site analysis.

The new workflow supports:

  • nested out-of-fold elastic-net prediction;
  • Haseman–Elston estimation;
  • effective predictor count (p_eff);
  • LD summaries;
  • GEMMA BSLMM PVE estimation;
  • frozen joint models and domain gates;
  • within-cell relative local-SNP-contribution scoring; and
  • end-to-end out-of-fold prediction with permutation-calibrated HE screening.

A new genboostgpu command-line interface and SLURM launchers support execution on HPC systems.

🔬 R-faithful and reproducible numerics

The Gaussian elastic-net path solver has been reimplemented to reproduce the numerical behavior of glmnet 4.1-10, including Eigen's summation order.

  • CPU paths are bitwise identical to R.
  • GPU paths agree with the CPU/R implementation to numerical rounding.
  • R's Mersenne-Twister set.seed() / sample() behavior is reproduced for fold and sampling operations.
  • Accepted-run replays reproduce folds, statuses, HE estimates, p_eff, LD calculations, and BSLMM results exactly.
  • A 500-task caudate replay produced a nested-EN score Spearman correlation of 0.99999999 within R's own CPU-to-CPU numerical variation.

The SNP screen is also now deterministic: tied SNPs with identical genotypes retain the same ordering across CPUs, GPUs, and BLAS thread counts.

🧬 Reproducible GEMMA BSLMM

GEMMA's OpenBLAS kernel can now be explicitly pinned through bslmm.blas_coretype.

The default SkylakeX setting prevents hardware-dependent OpenBLAS kernel selection from silently changing bslmm_pve estimates between compute nodes. Systems unable to execute the requested kernel now fail explicitly rather than silently switching numerical paths.

--gemma-blas-coretype is available for both:

genboostgpu lgv init
genboostgpu sites init

Supported kernels can be selected per run, including auto and Haswell; invalid kernel names are rejected rather than silently ignored by OpenBLAS.

fit_bslmm_pve now also accepts relative work_dir paths.

⚡ Faster GPU glmnet solver

The GPU implementation of fit_paths(device="gpu") has been substantially optimized.

For a 64-unit site batch containing 11,880 glmnet paths:

  • v0.3-era implementation: 25.9 s
  • v0.4.0: 8.3 s

This is approximately a 3.1× improvement per batch.

For a 5,000-unit CpH workload on an NVIDIA A100:

  • Before: 1,983 s
  • v0.4.0 solver: 961 s
  • Throughput: 5.2 units/s

The new kernel parallelizes KKT and Gram calculations across columns, retains residuals in shared memory, and overlaps column loading with coordinate processing.

Additional memory and transfer optimizations include:

  • returning only the used portion of coefficient buffers;
  • GPU-side matrix transposition;
  • retaining coefficients only for variables that are ever active;
  • lazy construction of dense beta;
  • shared device copies of design matrices across fold alphas; and
  • per-matrix GPU standardization.

At batch size 64, peak host memory falls from approximately 52 GiB to 17 GiB.

🚀 Faster end-to-end site analysis

sites run now combines the optimized solver with:

  • vectorized cross-validation summaries;
  • background batch finalization;
  • concurrent preparation of the next batch while the GPU is active.

On a 5,000-unit CpH analysis using an A100, end-to-end throughput increased from:

1.33 → 2.52 units/s

while preserving bitwise-identical output relative to serial execution on both CPU and GPU.

The higher concurrency increases host memory per batched unit from approximately 0.5 GiB to 0.8 GiB, which should be considered when selecting batch size.

🖥️ Lower GPU cost and independent GEMMA jobs

v0.4.0 reduces GPU overhead by using:

  • one process per GPU;
  • shared shard arrays;
  • multiple loci per kernel launch;
  • shared design matrices across alpha values;
  • idle CPU cores for GEMMA; and
  • a complete --device cpu fallback.

Module 02 now requires roughly 3× less host-to-device design-matrix traffic, while Module 03 requires roughly 4× less.

For large site studies, GEMMA can also be separated entirely from the GPU job:

genboostgpu sites init --bslmm separate
genboostgpu sites bslmm --shard i/N

BSLMM can therefore run as a CPU-only array—even on a separate cluster—while GPU resources are reserved for elastic-net calculations.

lgv combine safely joins the two result streams using:

  • a run key that verifies identical initialization;
  • per-unit input digests;
  • detection of missing GEMMA rows through bslmm_rows_missing.

Separate and inline GEMMA execution produce equivalent result rows.

📥 Expanded input support

The new engine supports:

  • generic regional phenotype matrices;
  • PLINK1 and PLINK2 genotype data;
  • per-chromosome and genome-wide genotype filesets;
  • chromosome-at-a-time loading for large datasets;
  • the dna-methylation-heritability run layout;
  • CpG and CpH region/tile construction with scripts/build_regions.R; and
  • million-scale site input preparation with scripts/prepare_site_inputs.sh.

Region construction supports --exclude-bed, including resources such as the ENCODE blacklist.

Genome-wide .pvar loading is also faster through integer position parsing and one-time chromosome normalization per fileset.

📦 Packaging and dependencies

Optional functionality is now separated more clearly:

  • gpu — GPU glmnet solver;
  • plink2 — PLINK2/PGEN support;
  • legacy — the original RAPIDS-based boosting workflow.

Dependency updates include:

  • pyarrow ≥23.0.1
  • RAPIDS 26.2 for the legacy extra
    • cudf-cu12
    • cuml-cu12
    • dask-cuda
  • updated distributed dependency through the RAPIDS stack
  • refreshed Poetry lockfile
  • routine security and maintenance updates to urllib3, tornado, msgpack, idna, mako, pygments, requests, pytest, and black.

⚠️ Deprecated legacy boosting entry points

The original boosting APIs remain available but are now deprecated for the primary local-genetic-variance analyses:

  • boosting_elastic_net
  • run_windows_with_dask
  • run_single_window
  • run_cpgs_*
  • scripts/prepare_cpg_inputs.R

These entry points now explicitly warn that final_r2 is an in-sample statistic.

New analyses intended to estimate predictive performance or local genetic contribution should use the out-of-fold workflows provided by the v0.4 engine.

What's Changed

New Contributors

Thanks to everyone who contributed to this release.

Full Changelog: v0.3.0...v0.4.0

Contributors

KrotosBenjamin and dependabot
Assets 2
Loading