Skip to main content

ADAMIXTURE logo

Fast Biobank-Scale Population Genetics Clustering

Python Version PyPI Version License Status Downloads


ADAMIXTURE is a fast CPU/GPU implementation of ADMIXTURE for biobank-scale genetic clustering. .P and .Q outputs remain compatible with ADMIXTURE.

System requirements

Hardware & Platform compatibility

ADAMIXTURE runs cross-platform on Linux, macOS, and Windows, supporting CPU computation as well as GPU acceleration on NVIDIA GPUs (CUDA) and Apple Silicon (MPS).

Software requirements

We recommend creating a fresh Python 3.10+ virtual environment. For a faster installation experience, we highly recommend using uv.

As an example, using uv (recommended):

$ uv venv --python 3.10
$ source .venv/bin/activate
$ uv pip install adamixture

Installation Guide

The package can be installed using pip:

Basic Installation (CPU default)

Uses the pre-compiled C/Cython wheel and does not install PyTorch:

$ pip install adamixture

GPU Installation (NVIDIA CUDA / Apple Silicon MPS)

Includes PyTorch and Ninja for hardware-accelerated execution:

$ pip install "adamixture[gpu]"

The commands above use the binary wheel when one is available for the Python version and platform. Installing directly from a source checkout (for example, with pip install -e .) requires a local C/Cython build toolchain.

Running ADAMIXTURE

To train a model, simply invoke the following commands from the root directory of the project. For more info about all the arguments, please run adamixture --help. Note that BED, VCF, PGEN and BCF are supported.

Supported input files include:

  • PLINK BED: .bed, .bed.gz, .bed.zst, with .bim/.fam sidecars that may also be plain, .gz or .zst.
  • PLINK PGEN: .pgen or .pgen.zst, with .pvar/.psam sidecars that may be plain, .gz or .zst.
  • VCF: .vcf, .vcf.gz and .vcf.zst.
  • BCF: .bcf, .bcf.gz and .bcf.zst.

As an example, the following ADMIXTURE call

$ ./admixture snps_data.bed 8 -s 42

would be equivalent in ADAMIXTURE by running

$ adamixture -k 8 --data_path snps_data.bed --save_dir SAVE_PATH --name snps_data -s 42

By default, the following files will be output to the SAVE_PATH directory (the name parameter will be used to create the full filenames):

  • A .P file, similar to ADMIXTURE.
  • A .Q file, similar to ADMIXTURE.
  • A .png plot file containing the visualization of the inferred ancestry proportions (Q matrix).

Logs are printed to the stdout channel by default. If you want to save them to a file, you can use the command tee along with a pipe:

$ adamixture -k 8 ... | tee run.log

Running with multi-threading

To run ADAMIXTURE using multiple CPU threads, use the -t flag:

$ adamixture -k 8 --data_path data.bed --save_dir out/ --name test -t 8

Running with GPU acceleration

To leverage GPU acceleration (highly recommended for large datasets), use the --device flag:

  • NVIDIA GPU (CUDA):
    $ adamixture -k 8 --data_path data.bed --save_dir out/ --name test --device gpu
    
  • macOS Apple Silicon (MPS):
    $ adamixture -k 8 --data_path data.bed --save_dir out/ --name test --device mps
    

For a step-by-step guide on how to run a complete analysis workflow, see the 1000 Genomes Tutorial.

Multi-K Sweep

Instead of running ADAMIXTURE for a single K, you can automatically sweep over a range of K values using --min_k and --max_k. The data is loaded once, and each K is trained sequentially. K=1 is the no-structure null model and is a valid start for a sweep or a CV baseline:

$ adamixture --min_k 1 --max_k 10 --data_path snps_data.bed --save_dir SAVE_PATH --name snps_sweep

Cross-validation

Use --cv to estimate the optimal K by masking a fraction of genotype entries and measuring prediction error. → Full documentation

$ adamixture -k 8 --cv --data_path data.bed --save_dir out/ --name test

Plotting

By default, ADAMIXTURE automatically generates a png plot at 300 DPI without needing any additional flags. Following the method of Clumppling, it automatically aligns clusters across runs and K values. → Full documentation

Plots can include hierarchical population labels if you provide the arguments (--labels, --labels2, --labels3).

If you want to customize the format and resolution (e.g., to generate a PDF), use --plot (or --plot_single for individual per-K plots in multi-K sweeps):

  • Single K runs (-k): Use --plot.

    $ adamixture -k 8 --data_path data.bed --save_dir out/ --name test --plot pdf 300
    
  • Multi-K sweeps (--min_k and --max_k): Use --plot to configure the combined sweep plot (or --plot_single for individual plots per K).

    $ adamixture --min_k 2 --max_k 10 --data_path data.bed --save_dir out/ --name test --plot pdf 300
    

Projection Mode

Estimate ancestry proportions for new samples using a pre-trained, fixed P matrix (Q-only optimisation). K is detected automatically from P. → Full documentation

$ adamixture-project \
    --data_path new_samples.bed \
    --p_path trained_model/results.8.P \
    --save_dir projection_out/ \
    --name projected

Supervised Mode

Anchor the model with known population labels for a subset of samples while estimating Q freely for unlabeled ones. Labels use the same format as --labels (population name or -). → Full documentation

$ adamixture-supervised \
    --data_path all_samples.bed \
    --labels labels.txt \
    --save_dir supervised_out/ \
    --name supervised_run \
    -k 8

Other options

All hyperparameters and flags can be explored with:

$ adamixture --help

Key arguments:

Argument                                          Default Description
--init als Initialization method: SVD+ALS (als) or random EM priming (em).
--tol 0.1 Convergence tolerance for log-likelihood changes.
--max_iter 10000 Maximum optimization iterations.
-t 1 Number of CPU threads.
-s 42 Random seed.
--device cpu Device to use: cpu, gpu, or mps.
--chunk_size 8192 Number of SNPs in chunk operations.
--n_inits 1 Number of independent initializations (keeps run with best log-likelihood).
--chrom_mode autosomes Chromosome filter: autosomes keeps autosomes 1 to --autosomes; all keeps every chromosome.
--autosomes 22 Number of autosomes kept when --chrom_mode autosomes (equivalent to --specific_chrom 1 2 ... 22).
--specific_chrom None List of specific chromosomes to analyze when --chrom_mode autosomes (overrides --autosomes).
--no_freqs False Do not save the .P allele-frequency matrix.

Algorithm note

The ADAMIXTURE paper introduced Adam-EM as an adaptive first-order optimizer for admixture inference. The package still includes this solver via --algorithm adamem.

In the current implementation, the default is --algorithm brqn. Empirical benchmarking showed that block relaxation with ZAL quasi-Newton acceleration, when paired with our improved SVD+ALS initialization, reaches high-quality solutions in fewer iterations and better wall-clock time. For that reason, BR-QN is the default solver, while Adam-EM remains available for experimentation and reproducibility. Adam-EM tuning parameters are documented in Troubleshooting and Tips.

Troubleshooting and Tips

Common issues and platform notes:

  • macOS: Install libomp via Homebrew (brew install libomp) before compiling.
  • Windows: Pre-compiled wheels are provided on PyPI (pip install adamixture). If compiling from source (pip install -e .), install Build Tools for Visual Studio with Desktop development with C++.
  • CUDA: Set CUDA_HOME or install nvcc via Conda (conda install -c nvidia nvcc).

→ Full documentation

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Cite

When using this software, please cite the following paper:

@article{saurina2026adamixture,
  title={ADAMIXTURE: adaptive first-order optimization for biobank-scale genetic clustering},
  author={Saurina-i-Ricos, Joan and Mas Montserrat, Daniel and Ioannidis, Alexander G.},
  journal={Bioinformatics},
  volume={42},
  number={Supplement\_1},
  pages={btag236},
  year={2026},
  doi={10.1093/bioinformatics/btag236},
  url={https://doi.org/10.1093/bioinformatics/btag236}
}

Metadata

Release files for adamixture 1.8.8

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

Source distribution (sdist)

Source distribution for adamixture 1.8.8
File Size Uploaded Provenance Actions
adamixture-1.8.8.tar.gz 21.7 MB Without provenance Details for adamixture-1.8.8.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for adamixture 1.8.8
File Actions
adamixture-1.8.8-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for adamixture-1.8.8-cp312-cp312-win_amd64.whl
adamixture-1.8.8-cp312-cp312-manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details for adamixture-1.8.8-cp312-cp312-manylinux_2_28_x86_64.whl
adamixture-1.8.8-cp312-cp312-macosx_14_0_x86_64.whl CPython 3.12 CPython 3.12 macOS 14.0+ x86-64 Details for adamixture-1.8.8-cp312-cp312-macosx_14_0_x86_64.whl
adamixture-1.8.8-cp312-cp312-macosx_14_0_arm64.whl CPython 3.12 CPython 3.12 macOS 14.0+ ARM64 Details for adamixture-1.8.8-cp312-cp312-macosx_14_0_arm64.whl
adamixture-1.8.8-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for adamixture-1.8.8-cp311-cp311-win_amd64.whl
adamixture-1.8.8-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details for adamixture-1.8.8-cp311-cp311-manylinux_2_28_x86_64.whl
adamixture-1.8.8-cp311-cp311-macosx_14_0_x86_64.whl CPython 3.11 CPython 3.11 macOS 14.0+ x86-64 Details for adamixture-1.8.8-cp311-cp311-macosx_14_0_x86_64.whl
adamixture-1.8.8-cp311-cp311-macosx_14_0_arm64.whl CPython 3.11 CPython 3.11 macOS 14.0+ ARM64 Details for adamixture-1.8.8-cp311-cp311-macosx_14_0_arm64.whl
adamixture-1.8.8-cp310-cp310-win_amd64.whl CPython 3.10 CPython 3.10 Windows x86-64 Details for adamixture-1.8.8-cp310-cp310-win_amd64.whl
adamixture-1.8.8-cp310-cp310-manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64 Details for adamixture-1.8.8-cp310-cp310-manylinux_2_28_x86_64.whl
adamixture-1.8.8-cp310-cp310-macosx_14_0_x86_64.whl CPython 3.10 CPython 3.10 macOS 14.0+ x86-64 Details for adamixture-1.8.8-cp310-cp310-macosx_14_0_x86_64.whl
adamixture-1.8.8-cp310-cp310-macosx_14_0_arm64.whl CPython 3.10 CPython 3.10 macOS 14.0+ ARM64 Details for adamixture-1.8.8-cp310-cp310-macosx_14_0_arm64.whl

Total release size: 171.6 MB

Release files / adamixture-1.8.8.tar.gz

Download URL adamixture-1.8.8.tar.gz
Size 21.7 MB
Tags Source
SHA-256 checksum
How to use checksums
9472bbb3a120d42351c559f433bc4a828b55e2fddbcd94e9b9fb75329b9194a9
BLAKE2b-256 checksum
How to use checksums
e0aab4d1c7f9e4f7abdc7304d9db4db3280d90f10e7a59306266d3578b1161a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp312-cp312-win_amd64.whl

Download URL adamixture-1.8.8-cp312-cp312-win_amd64.whl
Size 12.3 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
0d224396ad3923180c0d51f7359c2732cb57e24b8839400f8737c2ed75059b9d
BLAKE2b-256 checksum
How to use checksums
91028b960b418f6230615e37cfe5f74acd94c5e5caadef5e5703976eb16b9964
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL adamixture-1.8.8-cp312-cp312-manylinux_2_28_x86_64.whl
Size 12.7 MB
Tags CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
3bf55cf7643f1074783bb3a32fc573073596d4d91aa7bf9635fc6b262950efec
BLAKE2b-256 checksum
How to use checksums
d6cb961cab0ce813cc8bb07c52d56e557163deee01ee5ccfbdef1b5482cbb7b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp312-cp312-macosx_14_0_x86_64.whl

Download URL adamixture-1.8.8-cp312-cp312-macosx_14_0_x86_64.whl
Size 12.4 MB
Tags CPython 3.12 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
988c08765957a50ce462c999f9bc8d1726c9dacce696d4152071f7f6adc7d223
BLAKE2b-256 checksum
How to use checksums
22ef36e08aff0901e06fb6dee2783b6a0a52700443a90e52572f08f0f5ecb61f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp312-cp312-macosx_14_0_arm64.whl

Download URL adamixture-1.8.8-cp312-cp312-macosx_14_0_arm64.whl
Size 12.6 MB
Tags CPython 3.12 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
38faa7e17d12bdbb420a4982d8ab438bc1871be40a70c0bad7a39f41c7cc00a6
BLAKE2b-256 checksum
How to use checksums
b3a6778685f034a6e83a9aef05602cb646f37e40f3a90e0fb975ea5400d79b1a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp311-cp311-win_amd64.whl

Download URL adamixture-1.8.8-cp311-cp311-win_amd64.whl
Size 12.3 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
6a0e3db72fa4ccb120d0568a3164e95c47243abfc2ba40b8e4bd4ec571f5584b
BLAKE2b-256 checksum
How to use checksums
d2bbe834596d68c82eb5e7812a699ceed90d6f23995c1150ff4fbeb36b6f3335
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL adamixture-1.8.8-cp311-cp311-manylinux_2_28_x86_64.whl
Size 12.7 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
fa8bca062fe83976d2ddc8f502b2609d49fdb1832fdfd1b30044f4f91fcfc9f1
BLAKE2b-256 checksum
How to use checksums
2c3774268a8e9e32806f15a4ff63aaf022f5b4c4fe4a8a544b1fc018eb432e11
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp311-cp311-macosx_14_0_x86_64.whl

Download URL adamixture-1.8.8-cp311-cp311-macosx_14_0_x86_64.whl
Size 12.4 MB
Tags CPython 3.11 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
8daa9f53d0f51728677f099ac30eda44861e6caa920fe64267baff41e3421c36
BLAKE2b-256 checksum
How to use checksums
a5eb9fd8899eee62543860cf030e94866dd386a3e2ca1df3e7c40e471f0da9b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp311-cp311-macosx_14_0_arm64.whl

Download URL adamixture-1.8.8-cp311-cp311-macosx_14_0_arm64.whl
Size 12.5 MB
Tags CPython 3.11 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
6340c491e3959ea0ef970101addd428ef7342a817c0c8c7440227a81cd68a6b3
BLAKE2b-256 checksum
How to use checksums
a0277e8a38a1b1783ae98ea8cbd636de2da32d828e587f6b68347eb2de5ed34a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp310-cp310-win_amd64.whl

Download URL adamixture-1.8.8-cp310-cp310-win_amd64.whl
Size 12.3 MB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
abdadc79c0676dd416fdb35cfc4e19dcc8879e3b65e16777f4265c503762ec2e
BLAKE2b-256 checksum
How to use checksums
90d20cabde179b7bff06b66442b2fbb953e1ddfd6a0bf3ccee87948e001429cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL adamixture-1.8.8-cp310-cp310-manylinux_2_28_x86_64.whl
Size 12.8 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
998c8dda2155bbc8a98ba259a2a2a2d812ba17886e0ef0b553c0c9adb40d1807
BLAKE2b-256 checksum
How to use checksums
0e048f0194be1235ff23de7ed60fdbb786974ddca4bc0baf055e81445b74f6ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp310-cp310-macosx_14_0_x86_64.whl

Download URL adamixture-1.8.8-cp310-cp310-macosx_14_0_x86_64.whl
Size 12.4 MB
Tags CPython 3.10 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
f8856ab6a385e50c4b8b23656173549ddd0831982814761ff925fb0531bb03d8
BLAKE2b-256 checksum
How to use checksums
cc090cef3e7facfea4df2a3a2513819ff667502ee4e0e9e3ede94fc3aaf1aa0d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / adamixture-1.8.8-cp310-cp310-macosx_14_0_arm64.whl

Download URL adamixture-1.8.8-cp310-cp310-macosx_14_0_arm64.whl
Size 12.6 MB
Tags CPython 3.10 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
f5d6372293ede8b39ce3584f6a0d56a7c65118853dc1c1af1031138e379b51f5
BLAKE2b-256 checksum
How to use checksums
7292557484b61b03811e52aaa6807baa52b0987ce575d17b59d608d2183b39d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for adamixture 1.8.8

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

1.8.8 This release

13 release files No provenance

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