Skip to main content

AdmixPy

Fast population-genetic f-statistics, qpAdm, qpWave, and single-pulse admixture dating in Python. Requires Python 3.10 or newer.

For function signatures, options, result objects, and method details, see the API reference. See the changelog for changes.

Installation

Using a virtual environment is recommended:

python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install admixpy

Upgrade an existing installation with python -m pip install --upgrade admixpy. To install a source checkout, run python -m pip install -e . from its root. Check the installed version with:

python -c "import admixpy; print(admixpy.__version__)"

Input data

Use a dataset prefix without a file extension. Supported layouts are EIGENSTRAT text, packed AncestryMap, TGENO, and SNP-major PLINK binary files. Population names must match the .ind population column or PLINK .fam FID. Genotype layout detection is automatic.

Most f-statistic and ancestry-model functions also accept precomputed f2 blocks. Admixture dating requires individual genotypes and a genetic map. See input conventions and missingness and resampling before comparing analyses with different input types.

Quick start

The population names below are placeholders, replace them with labels in your data.

import admixpy as ap

prefix = "/path/to/dataset_prefix"

# f4 statistic
stats = ap.f4(prefix, "Outgroup", "Reference", "Source", "Target")
print(stats)

# qpAdm: sources on the left, reference populations on the right
model = ap.qpadm(
    prefix,
    target="Target",
    sources=["SourceA", "SourceB"],
    right=["Outgroup", "ReferenceA", "ReferenceB", "ReferenceC"],
)
print(model)
model.weights.to_csv("ancestry_weights.csv", index=False)

qpAdm tests a proposed ancestry model relative to the selected references. A model that is not rejected is not uniquely established as the historical model. See qpAdm and qpWave for rank tests, source subsets, rotating models, batching, and result fields.

Admixture dating

date = ap.admixture_date(
    prefix,
    target="Target",
    sources=["SourceA", "SourceB"],
    # target_iids=["sample_id"],  # Optional individual selection
)
print(date)
date.curve.to_csv("admixture_covariance.csv", index=False)

This DATES-inspired estimator fits a single exponential to within-individual ancestry covariance. It supports a single target individual or a group. Use one representation per person and group individuals with similar sampling ages and ancestry histories. Dates are in generations before sampling. A resolved result summarizes numerical checks, it does not test whether the chosen references describe a valid demographic model.

See admixture dating for every option, map units, generation conventions, uncertainty, result tables, and diagnostic flags.

Exploratory source screening

screen = ap.screening(
    prefix,
    target="Target",
    candidates=["SourceA", "SourceB", "SourceC"],
    refs=["Outgroup", "ReferenceA", "ReferenceB", "ReferenceC", "ReferenceD"],
    # outgroup="Outgroup",  # Defaults to the first entry of refs
    source_sizes=[2, 3],
    # allsnps=True,  # Optional: use available SNPs per contrast with genotype input
)
print(screen)  # Five closest models per source count, with a source key
screen.models.to_csv("screen_models.csv", index=False)
screen.weights.to_csv("screen_weights.csv", index=False)

Screening loads one joint f4 basis and fits constrained source mixtures. Lower covariance-aware scores indicate closer fits relative to estimated uncertainty, these are descriptive scores, with no model-fit p-values. Compare models within source count and check selected models with qpAdm. Screening uses qpAdm's f4(source, target; reference, outgroup) contrast basis. See screening for scoring and output.

Available analyses

Analysis Functions Reference
f-statistics and differentiation f2, fst, f3, f4 Statistics
Relative affinity and ancestry ratios f4_proximity, f4_ratio Statistics
Exploratory source mixtures screening Screening
Ancestry models and rank tests qpadm, qpwave, batch and rotation helpers Models
Single-pulse dating admixture_date Dating
Genotype conversion and filtering Readers, allele-frequency conversion, SNP selection Genotypes
Reusable statistics f2 IO, f4 caches, block and jackknife helpers Caches and blocks

License

MIT License.

Metadata

Release files for admixpy 1.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for admixpy 1.1.2
File Size Uploaded Provenance Actions
admixpy-1.1.2.tar.gz 118.9 kB With provenance Details for admixpy-1.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for admixpy 1.1.2
File Interpreter ABI Platform Actions
admixpy-1.1.2-py3-none-any.whl Python 3 none any Details for admixpy-1.1.2-py3-none-any.whl

Total release size: 188.3 kB

Release files / admixpy-1.1.2.tar.gz

Download URL admixpy-1.1.2.tar.gz
Size 118.9 kB
Tags Source
SHA-256 checksum
How to use checksums
bb0542ed3326010d65905e9f634afae696618a95324af2672d6e9bb923363b19
BLAKE2b-256 checksum
How to use checksums
ba4fafeda671d635a03c829b10c808ec2558446b238257ec69e061189d25cd5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / admixpy-1.1.2-py3-none-any.whl

Download URL admixpy-1.1.2-py3-none-any.whl
Size 69.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
53ad2b1b4f252669976f96e8c6d44eb5a7c3e460523169216b816cf32921e6f9
BLAKE2b-256 checksum
How to use checksums
88268c7cd47e3ba6db89da7262f87e14ab4ab3c64433e06e705089f63d18775d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for admixpy 1.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for admixpy-1.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page