Input Files

This page is the canonical user-facing input contract for g regenie.

For the statistical use of each input, see Algorithm. For the CLI names and TOML mapping, see CLI and Configuration.

Required Files

Genotypes

g currently supports Layout 2 BGEN for Step 2 scans. This includes the uncompressed and zlib encodings defined by BGEN v1.2 and the Zstandard compression extension added by BGEN v1.3.

Supported:

• Layout 2 genotype input with uncompressed, zlib, or Zstandard variant blocks.
• Oxford .sample files through --sample.

--sample is required. Sample identities are loaded from that Oxford .sample file, not from identifiers embedded in the BGEN. Adjacent .sample files are not discovered implicitly.

Unsupported options, which are absent from the CLI and rejected as unknown:

• --bed
• --pgen
• variant filtering through --extract and --exclude
• sample filtering through --keep and --remove

Eligible GPU runs select the packed8 fast path automatically, including multi-phenotype groups and groups with different aligned sample selections. Before using it, the engine validates that every BGEN variant is compatible with the no-missing diploid 8-bit representation. The scan also rejects invalid probability lengths, normalization sums, padding, reserved flags, and nonzero probabilities for missing samples before choosing a delivery format. Both typed outcomes—packed8 compatible and dosage required—are cached by a file-identity, timestamp, size, and dimension fingerprint under the user cache directory. The exact opened file is checked after indexing, before and after compatibility validation, and around genotype delivery, so a source changed during a run fails. Cache-directory lookup or persistence failures trigger an uncached scan and do not disable packed8. Otherwise-supported biallelic diploid Layout-2 variants with missing values, phased probabilities, or a bit depth other than 8 fall back to dosage delivery. Multiallelic, non-diploid or otherwise unsupported input fails instead of falling back. Compatibility validation and packed8 selection are internal policies rather than configuration keys.

Sample Identity

Sample alignment always uses the (FID, IID) pair. Both values must be non-empty, and each pair must be unique. There is no public IID-only matching mode. The same identity rule applies across the Oxford .sample file, phenotype rows, covariate rows, and prediction rows.

The Oxford .sample header must contain ID_1 and ID_2, and its following type row must mark both columns with type 0. ID_1 supplies FID and ID_2 supplies IID for the other inputs. The columns may appear anywhere in the sample header; their names and types are required. Fields are separated by ASCII whitespace, as defined by the Oxford format; Unicode whitespace is not a delimiter.

Phenotypes And Covariates

Phenotype and covariate tables are parsed by the native Rust path. Tables are expected to include both FID and IID.

Column selection rules:

• Repeat --phenoCol for each phenotype.
• Repeat --covarCol for each covariate.
• Multiple phenotypes write one output run per phenotype.

Binary phenotypes use REGENIE-style coding:

Missing tokens include empty string, NA, NaN, nan, and -9. Rows must still physically contain each selected field: FID, IID, selected phenotype columns, and selected covariate columns. A structurally short row that ends before one of those columns fails instead of being treated as missing. Use an explicit empty field with the delimiter present, such as a trailing tab for the final selected column, when the intended value is missing. Empty FID or IID fields always fail, including on rows that do not match the sample file or would otherwise be excluded for missing phenotype or covariate values.

--catCovarList is not accepted and fails as an unknown option.

Step 1 Predictions

--pred must point to a prediction list produced by upstream REGENIE Step 1. g does not produce Step 1 predictions.

Each prediction-list row maps one phenotype to one LOCO prediction file. Relative LOCO paths are resolved from the prediction-list directory. Run manifests record the prediction-list content hash and the content hash of each selected LOCO file for the phenotype or compatible compute group, so changing a referenced LOCO file prevents resume even when the prediction-list file itself is unchanged. Prediction lists and LOCO files use ASCII whitespace delimiters; Unicode whitespace is not a delimiter.

Each LOCO header starts with FID_IID; every following sample token must encode non-empty FID and IID values separated by an underscore, and each resulting pair must be unique.

Step 2 statistics depend on the prediction file, trait mode, covariates, chromosome, and aligned sample set. Changing the prediction list can change results even when the tested BGEN file is unchanged.

Multi-Phenotype Sample Semantics

[compute] multi_phenotype_sample_mode controls how g aligns rows for multiple requested phenotypes:

• per-phenotype (default): each phenotype uses its own complete-case sample set. This is the statistical equivalent to running each phenotype in a separate single-phenotype CLI run with identical options.
• complete-case: all requested phenotypes share one intersection of complete phenotype and covariate rows.

Every phenotype run manifest records the selected mode, the aligned sample count, the sample-set fingerprint, the covariate-design fingerprint, and the prediction alignment fingerprint used for that phenotype. Resume treats these fields as result-affecting, so a per-phenotype output cannot be resumed as complete-case output or vice versa.

This is a statistical choice, not only an execution strategy:

• Use per-phenotype when you want each trait to be analyzed on its own largest non-missing sample.
• Use complete-case when you want all traits analyzed on the same cohort (for strict per-trait comparability) or when missingness is nearly identical.

complete-case can change test statistics when phenotype missingness differs across traits because it changes sample_count, covariate projections, and LOCO alignment for every phenotype in the command. In that situation, this mode can bias or lose power for phenotypes with trait-specific missingness patterns.

Performance implications:

• per-phenotype may still group traits that share compatible complete-case samples internally and therefore can reuse some startup and decode work.
• complete-case usually increases sample-mask and projection reuse because one shared sample intersection is computed once, but it can lower effective sample size versus per-phenotype analysis.

For full definitions and implementation details, see Algorithm > Multi-Phenotype Behavior and Configuration for the exact TOML setting name.