epistasis-v2 1.0.0

High-performance Python library for fitting high-order epistatic interactions in genotype-phenotype maps.

epistasis-v2

High-performance Python library for fitting high-order epistatic interactions in genotype-phenotype maps. A clean-break rewrite of harmslab/epistasis.

Status: alpha. Phase 1 port complete; Phase 2 Rust kernel and Phase 3 FWHT / sparse paths still to come.

What changed from v1

• Rust hot-path kernels via PyO3 (epistasis._core) instead of a shipped Cython .c blob.
• uv + maturin build. pyproject.toml only; no setup.py.
• Python 3.10 through 3.13. Older interpreters dropped.
• Type hints on the public API; mypy --strict in CI.
• Composition over @use_sklearn MRO injection. Concrete models hold an sklearn estimator as an attribute and forward calls explicitly, which unlocks modern sklearn (>=1.2) that broke the v1 trick when normalize= was removed.
• Walsh-Hadamard fast-path for Hadamard-encoded OLS fits (Phase 3, not yet landed).
• Sparse design matrix path for Lasso / ElasticNet at high order (Phase 3).
• Coordinated rewrite of the gpmap dependency as gpmap-v2. Consumes binary_packed (uint8 2D) and encoding_table with site_index instead of the deprecated genotype_index.
• No backward compatibility with v1. Pin the v1 package if you need that behavior.

Repository layout

epistasis-v2/
├── pyproject.toml          uv + maturin build, ruff + mypy + pytest config
├── Cargo.toml              Rust workspace
├── python/epistasis/       Python source (installed as `epistasis`)
├── crates/epistasis-core/  Rust crate, exposed as `epistasis._core`
├── tests/                  pytest suite
├── benches/                pytest-benchmark + criterion (Phase 2+)
├── docs/                   Sphinx docs (Phase 5)
├── .github/workflows/      CI (lint, test, matrix) + release (semantic-release, maturin wheels, PyPI OIDC)
├── CHANGELOG.md            generated by python-semantic-release
└── CONTRIBUTING.md         commit conventions, dev workflow

Installation (dev)

Requires Python >= 3.10 and a Rust toolchain. gpmap-v2 is pulled from PyPI.

uv sync
uv run maturin develop --release
uv run pytest

For lint and type-check:

uv run ruff check .
uv run ruff format --check .
uv run mypy python/epistasis

Current progress

Phase 0 (scaffold) and Phase 1 (port) complete.

Ported modules:

• epistasis.mapping (sites, coefficients, EpistasisMap)
• epistasis.matrix (encoded vectors, design matrix, NumPy backend)
• epistasis.exceptions (EpistasisError, XMatrixError, FittingError)
• epistasis.utils (genotypes_to_X)
• epistasis.models.base (AbstractEpistasisModel, EpistasisBaseModel)
• epistasis.models.linear (EpistasisLinearRegression with analytic coefficient standard errors, EpistasisRidge, EpistasisLasso, EpistasisElasticNet)
• epistasis.models.nonlinear (EpistasisNonlinearRegression, FunctionMinimizer; power and spline variants deferred)
• epistasis.models.classifiers (EpistasisLogisticRegression; LDA, QDA, Gaussian Process, and GMM deferred)
• epistasis.simulate (simulate_linear_gpm, simulate_random_linear_gpm)
• epistasis.stats (Pearson, R^2, RMSD, SS residuals, AIC, split_gpm)
• epistasis.validate (k_fold, holdout)
• epistasis.sampling.bayesian (BayesianSampler via emcee 3)

Pending:

• Rust kernels for build_model_matrix, encode_vectors, FWHT fast path (Phase 2)
• Sparse design matrix path for Lasso / ElasticNet (Phase 3)
• power.py and spline.py nonlinear variants
• Remaining classifier implementations if demand surfaces
• ReadTheDocs build

Contributing

See CONTRIBUTING.md. Commits follow Conventional Commits; releases and the changelog are automated by python-semantic-release.

License

Unlicense (public domain). See UNLICENSE.