ARGMix

ARGMix is a local ancestry inference tool trained on forward-in-time simulations. ARGMix uses features from the inferred ARG.

Install

Requirements: linux-64 and CUDA 12. On a machine without CUDA installed (for example a login node), set CONDA_OVERRIDE_CUDA=12.0 before pixi install.

First install Pixi, then:

pixi install
pixi run compile   # Python extension + Rust build_training binary

pixi run argmix --help

Where to run commands

Pixi must find this repository's pixi.toml before ARGMix can process --project. For projects created inside the clone, run from the repository root and pass the relative project path:

pixi run argmix validate --project my_project

For a project elsewhere, name both the Pixi manifest and the absolute project path:

pixi run --manifest-path /path/to/argmix/pixi.toml argmix validate \
  --project /absolute/path/to/my_project

--project locates the ARGMix project, it does not help Pixi locate pixi.toml.

On SLURM, put the same pixi run argmix ... command in your own batch script and submit it with sbatch. ARGMix does not submit jobs itself.

Workflow

pixi run argmix init --project my_project
# edit my_project/argmix.yaml and my_project/forward_config.yaml
# set relate.bin / parallel / recomb_map / ancestor_fasta / prepare_input
pixi run argmix validate --project my_project
pixi run argmix build-data --project my_project

pixi run argmix build-training --project my_project --split train
pixi run argmix build-training --project my_project --split val

pixi run argmix train --project my_project

pixi run argmix test --project my_project

build-training and train default to outputs/_work/{train,val}.pt. Run both build-training splits before train.

argmix init defaults to the forward_blank template and creates forward_config.yaml as the forward simulation config.

argmix build-data runs the forward-in-time simulation and Relate workflow.

Relate

argmix validate checks all required Relate paths together: relate.bin, relate.parallel, relate.recomb_map, relate.ancestor_fasta, and relate.prepare_input. The recombination map and ancestor FASTA must match the input chromosome and genome build.

relate.mask_fasta is optional. When it is absent, validation warns but does not fail. The workflow generates .dist from a configured mask, so there is no external .dist path to configure. With transversion: true, validation also warns unless the mask exists, use_dist: true, and mutation_rate: 4e-9.

Note on dropped_truth during build-training

build-training may log something like:

[truth labels] observed_position_filter ... truth_variants=N haps_variants=M kept=M dropped_truth=K missing_haps=0

That is expected: Relate filters many variants during preprocessing. Sites removed by the Relate path (especially PrepareInputFiles.sh) show up as dropped_truth. missing_haps=0 means every remaining .haps site was also in ground-truth variants.

CLI

pixi run argmix init [--template forward_blank] --project <dir>
pixi run argmix validate --project <dir>
pixi run argmix build-data --project <dir> [--unlock]
pixi run argmix build-training --project <dir> --split train|val [--output PATH]
pixi run argmix train --project <dir> [--train-pt PATH] [--val-pt PATH] [--reuse-compatible-checkpoint] [--force] [--run-val-test]
pixi run argmix test --project <dir> [--base-checkpoint PATH] [--split val|test] [--replicate N]
pixi run argmix infer --trees PATH --references PATH --recomb-map PATH --checkpoint PATH --output-dir DIR --predict-pops POP...
pixi run argmix export --h5 PATH --format msp|fb|lanc --output PATH

Project layout

my_project/
  argmix.yaml
  forward_config.yaml
  events.yaml
  reference_panel.tsv
  argmix.advanced.yaml
  manifests/
    dataset.yaml
    runs/
  outputs/
    data/
    models/
    eval/
    infer/

argmix.yaml is the main config. forward_config.yaml is the forward simulation config (founder VCF, events, founder split). See the docs below for details.

Documentation

For an end-to-end run please start with the HGDP+1kGP tutorial:

• HGDP+1kGP tutorial: guides/hgdp_1kgp.md
• Config reference: docs/config_reference.md
• Forward simulation config: docs/forward_config.md

License

ARGMix is released under the MIT License.

Citation

If you use ARGMix in research, please cite …

Contact

If you have any questions or bugs, please open an issue on the github.