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, Phase 2 Rust kernel, the Phase 3 Walsh-Hadamard OLS fast path, sparse design matrices for high-order Lasso/ElasticNet, the power and spline nonlinear variants, a monotonic global-epistasis variant (MAVE-NN style), and the remaining classifiers (LDA / QDA / GP / GMM) are all in.

A multi-page Streamlit showcase lives under examples/ and is published at epistasis-v2.streamlit.app.

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: O(n log n) closed-form solve, no dense design matrix. Auto-engaged in EpistasisLinearRegression.fit when the attached GPM is a full-order biallelic library under global encoding; everything else falls back to the sklearn path.
Sparse design-matrix path for Lasso / ElasticNet via scipy.sparse.csc_matrix. sparse="auto" (default) engages for model_type="local" where the per-site product columns are 0/1; pass sparse=True / False to override. This is the memory fix for L >= 20 where the dense float64 design matrix used to OOM.
Monotonic global-epistasis variant EpistasisMonotonicGE modeled as a sum of K tanh sigmoids with b_k, c_k >= 0, following Tareen et al. 2022 (MAVE-NN). Identifiable by construction; modern alternative to the power transform when the nonlinearity isn't a clean Box-Cox shape.
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 suites (matrix kernels + FWHT)
├── 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

Plotting

Plotting support is optional. For matplotlib:

pip install "epistasis-v2[plot]"

epistasis.pyplot.plot_coefs draws fitted coefficients as a bar chart colored by interaction order, with a site-participation grid underneath (the signature figure from v1):

from epistasis.models.linear import EpistasisLinearRegression
from epistasis.pyplot import plot_coefs

model = EpistasisLinearRegression(order=3).add_gpm(gpm).fit()
fig, (bar_axis, grid_axis) = plot_coefs(model)

Current progress

Phase 0 (scaffold), Phase 1 (port), Phase 2 (Rust kernels), and Phase 3 (FWHT fast path + sparse design matrices for Lasso/ElasticNet) are complete.

Ported modules:

epistasis.mapping (sites, coefficients, EpistasisMap)
epistasis.matrix (encoded vectors and design matrix; Rust-backed)
epistasis.exceptions (EpistasisError, XMatrixError, FittingError)
epistasis.utils (genotypes_to_X)
epistasis.models.base (AbstractEpistasisModel, EpistasisBaseModel)
epistasis.models.linear (EpistasisLinearRegression with analytic coefficient standard errors and a Walsh-Hadamard fast path for full-order biallelic fits, EpistasisRidge, EpistasisLasso and EpistasisElasticNet with an auto-engaged scipy.sparse design-matrix path)
epistasis.models.nonlinear (EpistasisNonlinearRegression, FunctionMinimizer, EpistasisPowerTransform (Sailer & Harms 2017), EpistasisSpline (smoothing spline via scipy.interpolate.UnivariateSpline), EpistasisMonotonicGE (monotone tanh-sum global epistasis, Tareen et al. 2022))
epistasis.models.classifiers (EpistasisLogisticRegression, EpistasisLDA, EpistasisQDA, EpistasisGaussianProcess, EpistasisGaussianMixture)
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)
epistasis.fast (fwht_ols_coefficients: closed-form OLS via FWHT)

Rust hot-path kernels in epistasis._core:

encode_vectors (uint8 binary_packed to int8 Hadamard/local encoding)
build_model_matrix (parallel site-product over genotype rows; flat ragged sites layout)
fwht (iterative butterfly Fast Walsh-Hadamard Transform)

Benchmarks vs v1

Measured on Windows 11 against epistasis==0.7.5 + gpmap==0.7.0. Full biallelic space (AT alphabet), timeit best-of-5. See benchmarks/vs_v1.py for reproducible scripts and setup instructions.

Note on v1 times: the Cython extension in epistasis 0.7.5 requires MSVC to compile and produced no pre-built Windows wheel; times below use the pure-Python fallback, which is slower than actual v1+Cython. Even so, the FWHT fast path in v2 is orders of magnitude faster at full order.

fit() order=1 (sklearn lstsq path in both versions)

L	genotypes	v1 (ms)	v2 (ms)	speedup
8	256	12.98	1.81	7x
10	1,024	44.07	2.02	22x
12	4,096	183.13	2.61	70x
14	16,384	807.37	5.08	159x
16	65,536	3,771.14	19.35	195x

fit() full order (v1: dense lstsq, v2: FWHT O(N log N))

L	genotypes	v1 (ms)	v2 (ms)	speedup
8	256	195.16	1.75	111x
10	1,024	3,004.81	3.10	969x
12	4,096	59,344.00	8.97	>6,000x
14	16,384	(hours)	35.50
16	65,536	(hours)	154.15

Rust kernel vs NumPy reference (internal; release build, 16 threads; see `benches/`)

kernel	input	Rust	NumPy reference	speedup
`build_model_matrix`	L=12, order=3	1.7 ms	10.1 ms	~6x
`build_model_matrix`	L=16, order=3	50 ms	283 ms	~5.7x
`encode_vectors`	L=16 (65k genotypes)	1.06 ms	3.24 ms	~3x
`EpistasisLinearRegression.fit`	full-order L=10	0.78 ms	292 ms (lstsq)	~375x
`EpistasisLinearRegression.fit`	full-order L=12	3.4 ms	15.4 s (lstsq)	~4500x

Contributing

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

License

Unlicense (public domain). See UNLICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

epistasis_v2-1.3.0.tar.gz (47.9 kB view details)

Uploaded May 30, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

epistasis_v2-1.3.0-cp310-abi3-win_amd64.whl (248.2 kB view details)

Uploaded May 30, 2026 CPython 3.10+Windows x86-64

epistasis_v2-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (385.7 kB view details)

Uploaded May 30, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

epistasis_v2-1.3.0-cp310-abi3-macosx_11_0_arm64.whl (345.7 kB view details)

Uploaded May 30, 2026 CPython 3.10+macOS 11.0+ ARM64

epistasis_v2-1.3.0-cp310-abi3-macosx_10_12_x86_64.whl (351.2 kB view details)

Uploaded May 30, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file epistasis_v2-1.3.0.tar.gz.

File metadata

Download URL: epistasis_v2-1.3.0.tar.gz
Upload date: May 30, 2026
Size: 47.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for epistasis_v2-1.3.0.tar.gz
Algorithm	Hash digest
SHA256	`42a8db08ba47116359b93bd54afcc2d655e08fbb3dafafe8685e2f86b2a024ab`
MD5	`bd1e4a3f1123eeffb0794dfc1df552d7`
BLAKE2b-256	`2a4c7cd8f3d8180130fd60ca29e8269e23e977c76bac642cf786de88d4e6d166`

See more details on using hashes here.

Provenance

The following attestation bundles were made for epistasis_v2-1.3.0.tar.gz:

Publisher: release.yml on lperezmo/epistasis-v2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: epistasis_v2-1.3.0.tar.gz
- Subject digest: 42a8db08ba47116359b93bd54afcc2d655e08fbb3dafafe8685e2f86b2a024ab
- Sigstore transparency entry: 1674523532
- Sigstore integration time: May 30, 2026
Source repository:
- Permalink: lperezmo/epistasis-v2@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Branch / Tag: refs/heads/main
- Owner: https://github.com/lperezmo
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Trigger Event: push

File details

Details for the file epistasis_v2-1.3.0-cp310-abi3-win_amd64.whl.

File metadata

Download URL: epistasis_v2-1.3.0-cp310-abi3-win_amd64.whl
Upload date: May 30, 2026
Size: 248.2 kB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for epistasis_v2-1.3.0-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`813f209c3977f445e94c2bbe8418a3a6719fbe1eb6279a95c36c590e7b150063`
MD5	`2d48a17c6bb05e7c2e6aa1dfeba8fa29`
BLAKE2b-256	`82a56ab31c2363a97b6c9e1206814d62b5e17148b526ba57130472ddcaa55e9a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for epistasis_v2-1.3.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on lperezmo/epistasis-v2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: epistasis_v2-1.3.0-cp310-abi3-win_amd64.whl
- Subject digest: 813f209c3977f445e94c2bbe8418a3a6719fbe1eb6279a95c36c590e7b150063
- Sigstore transparency entry: 1674523558
- Sigstore integration time: May 30, 2026
Source repository:
- Permalink: lperezmo/epistasis-v2@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Branch / Tag: refs/heads/main
- Owner: https://github.com/lperezmo
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Trigger Event: push

File details

Details for the file epistasis_v2-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: epistasis_v2-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: May 30, 2026
Size: 385.7 kB
Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for epistasis_v2-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`e5d0e1cd3bc99a253c4edd86b44452f3d1dc1c54b309b9b686b07f2d9605cb90`
MD5	`d93f0aa5d08b25c66c834bc2dff5854a`
BLAKE2b-256	`ede15b0bdcb09920ac4089672ff4c3f2b5b7e7e7acd067e41d6dc0fd1d707784`

See more details on using hashes here.

Provenance

The following attestation bundles were made for epistasis_v2-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on lperezmo/epistasis-v2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: epistasis_v2-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: e5d0e1cd3bc99a253c4edd86b44452f3d1dc1c54b309b9b686b07f2d9605cb90
- Sigstore transparency entry: 1674523561
- Sigstore integration time: May 30, 2026
Source repository:
- Permalink: lperezmo/epistasis-v2@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Branch / Tag: refs/heads/main
- Owner: https://github.com/lperezmo
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Trigger Event: push

File details

Details for the file epistasis_v2-1.3.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: epistasis_v2-1.3.0-cp310-abi3-macosx_11_0_arm64.whl
Upload date: May 30, 2026
Size: 345.7 kB
Tags: CPython 3.10+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for epistasis_v2-1.3.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`1398933d3ce6b8396084a70b7142f5fd81b14c2ed96e144abeaba03c0e313368`
MD5	`92c74dc9af3855780b07cd1c1f1a9239`
BLAKE2b-256	`47f4e37e9869bd30f95d2cd74597fed6f871e3d4da86187606985cbccd96787b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for epistasis_v2-1.3.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on lperezmo/epistasis-v2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: epistasis_v2-1.3.0-cp310-abi3-macosx_11_0_arm64.whl
- Subject digest: 1398933d3ce6b8396084a70b7142f5fd81b14c2ed96e144abeaba03c0e313368
- Sigstore transparency entry: 1674523549
- Sigstore integration time: May 30, 2026
Source repository:
- Permalink: lperezmo/epistasis-v2@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Branch / Tag: refs/heads/main
- Owner: https://github.com/lperezmo
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Trigger Event: push

File details

Details for the file epistasis_v2-1.3.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: epistasis_v2-1.3.0-cp310-abi3-macosx_10_12_x86_64.whl
Upload date: May 30, 2026
Size: 351.2 kB
Tags: CPython 3.10+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for epistasis_v2-1.3.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`40d6d8568a15e3564787e5baf05032be6a60ddb30361bfb088712bddc47f81cf`
MD5	`c87aad9aebd46c718f38eb740c34ef09`
BLAKE2b-256	`18aae012ba879ed8541cf94e3c8868255a3ced4412aab69623dbc3d549cbd822`

See more details on using hashes here.

Provenance

The following attestation bundles were made for epistasis_v2-1.3.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on lperezmo/epistasis-v2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: epistasis_v2-1.3.0-cp310-abi3-macosx_10_12_x86_64.whl
- Subject digest: 40d6d8568a15e3564787e5baf05032be6a60ddb30361bfb088712bddc47f81cf
- Sigstore transparency entry: 1674523545
- Sigstore integration time: May 30, 2026
Source repository:
- Permalink: lperezmo/epistasis-v2@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Branch / Tag: refs/heads/main
- Owner: https://github.com/lperezmo
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@63b32d6dd508b56277e5a2bb52a71b203df3d8ca
- Trigger Event: push

Release history Release notifications | RSS feed

This release

1.3.0 This release

May 30, 2026 5 files

May 16, 2026 5 files

May 3, 2026 5 files

Apr 20, 2026 5 files

Apr 20, 2026 5 files

epistasis-v2 1.3.0

epistasis-v2

What changed from v1

Repository layout

Installation (dev)

Plotting

Current progress

Benchmarks vs v1

fit() order=1 (sklearn lstsq path in both versions)

fit() full order (v1: dense lstsq, v2: FWHT O(N log N))

Rust kernel vs NumPy reference (internal; release build, 16 threads; see benches/)

Contributing

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed

Rust kernel vs NumPy reference (internal; release build, 16 threads; see `benches/`)