Skip to content

Compatibility

Status Applies to Owner
Pre-release draft main branch as of 2026-06-30 REGENIE Step 2 compatibility Public user docs

This page is the canonical public compatibility and scope reference.

g is pre-release. Backward compatibility is not guaranteed until a stable release line exists.

Supported Surface

Area Status
REGENIE Step 2 quantitative traits Supported with --qt.
REGENIE Step 2 binary score test Supported with --bt.
Binary approximate Firth fallback Experimental with --bt --binary-fallback firth_approximate; not production-stable until upstream golden parity is added.
Layout 2 BGEN input Supported with uncompressed or zlib blocks and the BGEN v1.3 Zstandard extension.
Oxford .sample files Required for BGEN row identities.
Embedded BGEN sample identifiers Unsupported; pass an Oxford sample file with --sample.
Sample identity Fixed to non-empty, unique (FID, IID) pairs across aligned inputs; IID-only matching is unsupported.
Multiple phenotypes Supported with per-phenotype semantics by default.
Output Chunked Parquet datasets under each phenotype run's parts/ directory.
GPU execution Supported through JAX when the environment exposes a compatible accelerator.
TOML config Supported through --config.

Not Implemented

Area Behavior
REGENIE Step 1 Not implemented. Use upstream regenie and pass --pred.
PLINK BED input --bed is outside the current option surface and fails as unknown.
PLINK2 PGEN input --pgen is outside the current option surface and fails as unknown.
Sample/variant filters --keep, --remove, --extract, and --exclude fail as unknown.
Categorical covariates --catCovarList fails as unknown.
SPA fallback --spa fails as unknown.
Exact Firth No option is exposed; unsupported flags fail as unknown.
Alternative tests and time-to-event traits --test and --t2e fail as unknown.

Unsupported flags fail loudly so REGENIE command migration does not silently drop scientific intent.

Future Goals

Area Goal
Python embedding API Expose a supported Python API after the CLI, configuration, output, and runtime contracts stabilize.

REGENIE Command Migration

The supported command is intentionally close to REGENIE Step 2:

g regenie --qt --bgen ... --sample ... --phenoFile ... --phenoCol ... --pred ... --out ...

Important migration limits:

  • Replace Step 1 commands with upstream regenie, not g.
  • Keep BGEN Step 2 inputs; BED/PGEN Step 2 inputs are not accepted.
  • Compare equivalent statistical modes only. A binary score-only g run should not be compared to upstream REGENIE output that used approximate Firth.
  • Treat --bt --binary-fallback firth_approximate as experimental until the pre-release parity suite includes an upstream golden approximate-Firth fixture.
  • Consume each phenotype run's parts/ directory as a Parquet dataset. This is the sole result contract; there is no consolidated result file.

Versioning Expectations

Until the project declares a stable release:

  • CLI and TOML behavior in the current checkout is authoritative.
  • Defaults can change; use crates/interface/src/config.default.toml for the exact current values.
  • Output schema changes are guarded by manifest/schema versions but may still evolve.
  • Performance assumptions are workload-dependent and should be re-measured on the target machine.