Development

Environment

conda env create -f conda/dev-linux.yaml
conda activate admixture
makim setup.install

Use conda/dev-linux.yaml, conda/dev-macos.yaml, or conda/dev-win.yaml depending on your operating system. This project uses a src/ package layout and Python 3.10+. The conda environment includes juliaup; use juliaup add release and juliaup default release if julia --version fails.

Tests

Run the test suite:

makim tests.unit

Instantiate only the packaged OpenADMIXTURE.jl Julia project:

makim setup.julia

Run all tests:

makim tests.all

The default runtime test creates a tiny local PLINK data set and runs the wrapper against it. Runtime tests require Julia and OpenADMIXTURE.jl and fail when either is unavailable.

The malariagen-data compatibility test imports malariagen_data inside the test body only and skips only on Python 3.13+, where malariagen-data is unavailable. Default tests do not read from Google Cloud Storage.

For manual experiments against real MalariaGEN data, first request access to the relevant Google Cloud Storage bucket, then authenticate locally with:

makim gcloud.auth

For non-interactive local runs with a service-account JSON key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

For custom GitHub Actions workflows that need real MalariaGEN-GCS access, configure the GOOGLE_CREDENTIALS repository secret with a service-account JSON key with access to MalariaGEN data on Google Cloud Storage. A Google API key is not sufficient for this path because the data client uses Application Default Credentials. This is not required by the default CI test suite.

Lint and type checks

makim lint.all

Documentation

Render the Quarto website:

makim docs.build

Preview while editing:

makim docs.preview

Generated site files are written to docs/_site/ and should not be committed.

Design constraints

  • Do not reimplement the OpenADMIXTURE algorithm in Python.
  • Do not vendor OpenADMIXTURE.jl source code.
  • Keep Julia as an external runtime.
  • Use subprocess.run(args, shell=False, capture_output=True, text=True).
  • Treat PLINK input as a prefix with .bed, .bim, and .fam files.
  • Keep parsing and validation tests independent of Julia where possible.