HomoeoGWAS v2.2.0

HomoeoGWAS v2.2.0 adds publication-ready output figures (pip install homoeogwas==2.2.0).

Added: interact now ends by writing a genome-wide interaction scan, an evidence
figure for up to 12 significant groups (or the top three when none is significant), a calibration figure and, for smooth_pc4 runs,
a null-variance diagnostic, together with a figures.html page. fit draws the
subgenome PVE with bootstrap intervals, and homoeogwas follow-up draws
allele-combination means and accession-deletion robustness. homoeogwas plot
regenerates the figures of a finished fit or interact directory. Figures are
written as PDF, SVG and PNG; subgenomes are coloured by letter. The result JSON
records the bootstrap family minima, the per-edge component P values of reported
groups and the null-variance profile used by the figures.

No statistical code changed. Estimates, P values and decisions equal v2.1.4.
See the changelog for details.

HomoeoGWAS v2.1.4

HomoeoGWAS v2.1.4 is a patch release of v2.1.3 (pip install homoeogwas==2.1.4).

Fixed: the optional MCP interface is pinned to mcp>=1.0,<2. The 2.x series of
mcp renamed its server API, so a fresh pip install "homoeogwas[mcp]" could not
start homoeogwas mcp.

Changed: the documentation now shows the workflow figure, describes every input
and output file of fit and interact, adds an interaction quick start and the
full command list, and its algorithm page matches the current methods. Error
messages for the pairwise omniB compatibility wrapper and for
scan.loco.fallback=emmax are clearer. Species configs use relative example
paths, and tests that need local reference data are enabled through environment
variables. Internal development notes were removed from the repository and the
source distribution.

No statistical code changed. Estimates, P values and decisions equal v2.1.3.
See the changelog for details.

HomoeoGWAS v2.1.3

HomoeoGWAS v2.1.3 is a patch release of v2.1.2 and the first v2 release on PyPI
(pip install homoeogwas==2.1.3).

Changed: common analysis traps now stop at preflight or are flagged by audit.
A homoeolog table that repeats a gene across groups is refused without naming a
bypass; interact.allow_duplicate_genes is removed, and only the data owner can
waive the check (written reason, named approver, bound to the table hash; not
exposed via MCP; flagged OVERRIDDEN_INPUT_CHECK). fit and interact record
the sample join and refuse to run when unmatched phenotype IDs match genotype IDs
after normalisation (leading zeros, case, whitespace, trailing .0); losing more
than 5% of phenotyped samples is flagged SAMPLE_JOIN_LOSS.
prep-homoeologs --method diamond-rbh refuses protein FASTAs with non-amino-acid
characters or unmatched headers, runs DIAMOND with a timeout and treats zero
reciprocal pairs as an error. fit checks .bed/.bim/.fam for every subgenome
before computing, prep-snps refuses empty subgenomes or chromosome names absent
from the .bim, and validate runs fit's phenotype checks without computing.
A trait equal to the mean of trials with different means is flagged
PHENOTYPE_RAW_TRIAL_AVERAGE. PVE_UNCERTAINTY_NOT_ASSESSED is now info.

Added: report_card_<result>.json next to every fit summary and interact
result, with the numbers to quote, the audit flags and the statements a report
must carry; it is built from the result and audit, no statistic is recomputed.

No statistical code changed. Estimates, p-values and decisions equal v2.1.2.
See the changelog for details.

HomoeoGWAS v2.1.2

HomoeoGWAS v2.1.2 is a patch release of v2.1.1.

Added: a phenotype screen. Analysed values beyond 5 SD of the mean are listed
by validate_inputs, printed as WARN by fit and interact, recorded under
input_qc.phenotype in the result JSON and flagged by audit
(PHENOTYPE_EXTREME_VALUES, info; beyond 10 SD PHENOTYPE_OUTLIER, review).
Values are never removed.

Added: interact refuses a homoeolog table in which a gene appears in more than
one group of the same subgenome. interact.allow_duplicate_genes: true runs it
anyway; the duplicated genes are recorded and audit flags
DUPLICATED_GROUP_GENES (review).

Documented: with the homoscedastic null the bootstrap random stream differs
with and without checkpointing, so the same seed gives slightly different
Monte Carlo p-values in the two modes.

No statistical code changed. Estimates, p-values and FWER decisions equal
v2.1.1; result JSONs gain an input_qc block. Configs whose homoeolog table
repeats a gene now stop at preflight.

HomoeoGWAS v2.1.1

HomoeoGWAS v2.1.1 is a patch release of v2.1.0.

Fixed: canonical group omniB with the default null_variance: smooth_pc4
requires bootstrap checkpointing, and v2.1.0 treated every checkpointed omniB
run as a formal launch that needs a git-bound provenance.pre_run_manifest.
Configs generated by the MCP run_interaction tool, workflow.build_interact_config
and the AGENTS.md template therefore stopped with "checkpointed group omniB
requires provenance.pre_run_manifest". Such runs now declare
provenance: {mode: unattested}, which the generator and the template write;
their results carry the non-formal (legacy) evidence role. A checkpointed
config without a provenance block still fails, so deleting the binding of a
formal config does not downgrade it; replacing the binding with the unattested
declaration runs the analysis as non-formal.

Fixed: homoeogwas split indexed subset VCFs with tabix .tbi indexes,
which cannot store positions above 2^29 bp, so splitting a wheat VCF failed for
every subgenome. It now writes CSI indexes.

No statistical code changed; results of runs that completed under v2.1.0 are
unaffected.

Upgrade guidance: add provenance: {mode: unattested} at the top level of
hand-written checkpointed omniB configs, or regenerate them.

HomoeoGWAS v2.1.0

HomoeoGWAS v2.1.0 adds a heteroscedasticity-robust bootstrap null for group
omniB, chunk-parallel streaming scans and agent-facing audit and summary
tools.

Highlights:

• interact.calibration.null_variance: smooth_pc4 (canonical group omniB).
  The parametric bootstrap draws null phenotypes whose residual variance is a
  smooth function of the leading genotype principal components, fitted by
  IRLS. When residual variance tracks population structure, the homoscedastic
  bootstrap can be anti-conservative; smooth_pc4 restored familywise
  calibration in the tested settings. On real data it can reject fewer units
  than the homoscedastic null. Results record
  smooth_variance_parametric_bootstrap_minp_plus_one and the fitted
  weights. The low-level config default stays homoscedastic; report it as a
  sensitivity analysis. smooth_pc4 requires bootstrap checkpointing.
• scan.n_jobs for streaming single-locus scans (plain and LOCO). Chunks keep
  the serial chunk boundaries and batches and are scored by forked workers;
  each worker uses one native thread, and the decompressed summary statistics
  are byte-identical to the serial scan run with one BLAS thread (verified on
  1.9 million wheat markers). Each worker holds about
  chunk_size × n_samples × 20 bytes (about 3.3 GB at the default chunk size
  and 827 samples); lower scan.chunk_size or scan.n_jobs if memory is
  limited. A worker that dies stops the scan with an error. scan.n_jobs has
  no effect on in-memory or GPU scans. Gzip output is a standard multi-member
  gzip stream.
• MCP tools audit_results and summarize_results. run_interaction
  exposes null_variance (default smooth_pc4, with checkpointing enabled in
  the generated config) and run_gwas exposes scan_jobs.
• Batched interact cases share phenotype-independent panel preparation, and
  an opt-in hash-keyed GRM cache reuses relationship matrices across runs with
  identical inputs.
• interact.burden.feature_seed separates gene-feature randomness from the
  bootstrap seed (default: the bootstrap seed).

Behaviour changes:

• In group-unit (and joint) families, a homoeolog group is eligible only when
  every declared pair edge is estimable; groups with an unestimable edge are
  marked unestimable instead of being scored on a partial edge set, which can
  reduce the number of tested groups. Edge-unit families are unchanged.
• Partial omniB response errors fail closed.

Reproducibility note: REML variance components depend on the BLAS thread count
in the last digits (about 1e-6 in PVE), which propagates to per-marker
statistics. Bit-identical reproduction requires the same thread settings; the
formal interaction path fixes one native thread per worker.

Upgrade guidance: existing configs run unchanged. To use the robust null, add
null_variance: smooth_pc4 and checkpoint: {enabled: true, root: <dir>}
under interact.calibration.

HomoeoGWAS v2.0.1

HomoeoGWAS v2.0.1 unifies homoeolog interaction analysis across polyploid
species and adds the evidence, stability, provenance, and runtime safeguards
needed for publication-grade use.

Highlights:

• One canonical mode: group, statistic: omniB engine now covers two or
  more subgenomes. Pair edges are the shared primitive: two copies yield one
  edge, three yield three, and four yield six. Four-copy groups aggregate
  their six pair edges; HomoeoGWAS never fits or claims a direct four-way
  coefficient.
• Edge and group hypotheses can be calibrated as one declared
  experiment-wide bootstrap-minP family. Results record adjusted p-values,
  family hashes and counts, the complete ranking, and the evidence-driving
  omniB component.
• Canonical omniB scoring and material/environment deletion follow-up now use
  observable POSIX worker processes with one native numerical thread per
  worker. Requested and effective jobs, backend, and worker PIDs are recorded,
  while bootstrap streams, checkpoint identities, score arrays, and FWER
  decisions remain unchanged.
• homoeogwas audit writes JSON, TSV, and Markdown reports that distinguish
  computational validity, internal familywise discovery, component-level
  interpretation, and replication status.
• Complete component-aware rankings retain minor-allele burden, PC1, and
  kernel-Hadamard evidence. Components localize a combined omniB signal; they
  are not treated as separate discoveries.
• Optional fitted-model bootstrap intervals quantify uncertainty in the
  per-subgenome PVE partition, including boundary rates, refit success, and
  component-rank stability.
• Biallelic PAV, SV, and haplotype pseudo-markers now require explicit marker
  encodings and exact BIM-linked manifests. Scan and GRM inputs are validated
  independently; binary absence/presence must be encoded as 0/2.
• The experimental triad3 statistic remains available as an opt-in
  exact-three-copy sensitivity analysis. The canonical publication claim is
  encoding-robust omnibus pairwise interaction evidence within a homoeolog
  group, not a third- or fourth-order causal or physical mechanism.

Validation:

• Clean-checkout test suite: 771 passed, 4 skipped, and 1 deselected.
• GitHub Actions passed Ruff, CPU tests on Python 3.10, 3.11, and 3.12, and
  source/wheel package builds.
• Cross-species production checks cover wheat, cotton, peanut, and rapeseed
  through the same canonical group-omniB configuration and runtime contract.

Important upgrade notes:

• Use interact.mode: group, statistic: omniB, and one declared
  bootstrap-minP family for new two-, three-, and four-copy analyses. Legacy
  burden analyses remain accepted only when explicitly requested.
• Regenerate legacy SNP-to-gene NPZ files with the analysis BED using
  homoeogwas prep-snps; unverified mappings or BIM fingerprint mismatches are
  refused.
• Raw or multi-allelic copy-number states are not accepted as diploid SNP
  surrogates. Convert them into defensible biallelic features with a marker
  manifest or use a model designed for copy number.
• A significant group result supports omnibus pairwise interaction evidence
  within that homoeolog group. It does not establish a direct multi-protein
  complex or higher-order causal coefficient.

Paper analysis code, frozen configs, figure sources, and result fingerprints
remain in the separate
HomoeoGWAS-reproducibility
repository.

HomoeoGWAS v2.0.0

HomoeoGWAS v2.0.0 is the first release with the corrected family-wise
multiplicity contract for multi-subgenome interaction scans.

Highlights:

• Subgenome-stratified LMM GWAS with per-subgenome variance partitioning,
  SNP scans, LOCO support, and CPU/GPU backends.
• Homoeolog pair and triad burden-product interaction scans with explicit
  pairwise and group-omnibus hypothesis families.
• Corrected triad/clique multiplicity handling and strict estimability masks.
• Stronger phenotype/sample-ID, PLINK prefix, GFF/chromosome-map, NPZ
  fingerprint, MAF, and minimum-SNP validation.
• Safe decomposition of panels with four or more subgenomes into pairwise or
  triad subsets; no unsupported four-way interaction test.
• Agent and MCP workflows that generate and validate configs from biological
  inputs.
• 417 passing tests across Python 3.10, 3.11, and 3.12.

Important upgrade note:

Releases through v1.0.2 used a per-contrast threshold in group scans with three
or more subgenomes. Re-evaluate affected rejection calls under v2.0.0. Existing
interaction SNP-to-gene NPZ files should be regenerated with prep-snps so
their provenance fingerprint can be validated.

Paper analysis code, configs, figure sources, and result fingerprints are kept
in the separate
HomoeoGWAS-reproducibility
repository.

v1.0.1

HomoeoGWAS v1.0.1