adamixture 1.8.3

Fast Biobank-Scale Population Genetics Clustering

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 easily installed in at most a few minutes using pip (make sure to add the --upgrade flag if updating the version):

$ pip install adamixture

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:

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.

The cluster alignment and mode detection used for plotting are a port of Clumppling (MIT License, Xiran Liu et al.), reimplemented on NumPy and Cython in adamixture/src/clumppling.py.

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}
}