Installation¶
anqchor is a Python package (Python ≥ 3.10) plus the qpgen C++ toolkit, which is vendored as
a git submodule (extern/qpgen, branch dev) and built from the checkout. anqchor is not on
PyPI yet; install it from a clone.
1. Clone with submodules¶
git clone --recursive https://github.com/statgen/anqchor.git
cd anqchor
# already cloned without --recursive?
git submodule update --init --recursive
The second command also fetches qpgen's own submodules (htslib, qgenlib, Eigen).
2. Install the Python package¶
Runtime dependencies: typer, pydantic (v2), pyyaml, pandas, numpy, scipy, plotly,
jinja2. anqchor also needs GNU make (3.81 or later; the macOS default works) on PATH, or
in $ANQCHOR_MAKE.
3. Build qpgen¶
This runs qpgen's documented three-stage build inside extern/qpgen: htslib (autoreconf -i,
./configure, make), qgenlib (cmake, make), then qpgen itself (cmake, make). Stages
whose artefacts already exist are skipped; --force rebuilds htslib and qgenlib too. The output
is extern/qpgen/bin/qpgentools, and the full log is extern/qpgen/anqchor-build.log.
Build requirements: a C++14 compiler with OpenMP, cmake, make, autoreconf, and the
compression libraries htslib uses (zlib, bzip2, lzma; optionally libdeflate, libcurl,
libcrypto). LAPACK/BLAS are optional.
macOS
Apple Clang has no OpenMP. Install it and Homebrew LLVM before building:
qpgen's CMake configuration selects Homebrew LLVM automatically. anqchor qpgen build
warns before building when libomp or a Homebrew LLVM is missing. Extra CMake settings can
be passed with --cmake-arg (repeatable), for example
--cmake-arg=-DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++.
Using a qpgen binary built elsewhere
You do not have to build from the submodule. anqchor looks for qpgentools in this order:
--qpgen PATH(root option) orqpgen.binaryin the config;- the
ANQCHOR_QPGENenvironment variable; qpgentoolsonPATH;extern/qpgen/bin/qpgentoolsof the source checkout.
An explicit path or ANQCHOR_QPGEN that does not name an executable is an error (exit
code 4); anqchor does not silently fall back to another binary.
4. Check the installation¶
binary: /path/to/anqchor/extern/qpgen/bin/qpgentools (found via submodule)
sha256: <sha256 of your build>
commit: 5b811e250591931cd80f9a7dfae80d47eb8381e2
status: ok (pair-prs, match-prs-pheno, pair-assoc, rect-assoc available)
The command checks that the four subcommands anqchor uses exist. It prints the binary's
sha256 and the git commit of the checkout the binary sits in. The same information is recorded
in every run's run.json.
Then check the qpgen version:
anqchor needs qpgen 0.2.0 or later
qpgen 0.2.0 fixed several problems in the association and matching tools that change
anqchor's numbers. The most important: pair-assoc now adjusts the genotypes for the
covariates as well as the phenotypes, all association tools use df = N - 2 - k with k
covariates, and non-numeric covariate values such as XX/XY are an error (unless the
covariate is named with --cat-cov-names) instead of being read as 0. Older builds give
different, and with many covariates optimistic, results.
anqchor also passes --cat-cov-names for categorical covariates such as sex, which
needs qpgen commit 5b811e2 or later (the pinned submodule); an older 0.2.0 build does not
accept that option, and anqchor qpgen check reports it as missing options.
anqchor qpgen check does not read the version, so run qpgentools --version yourself.
Builds before 0.2.0 have no --version option at all. Details:
qpgen integration.
5. Run the example¶
The repository ships a small example dataset in examples/mage/data/. The
quickstart runs the quickest analysis on it in about 10 seconds; if that
works, the installation is complete.
Other tools¶
bgzipandtabix(htslib) are needed byanqchor prepare index-pvarto create indexed pvar files, and make the reference presence check faster (withouttabixanqchor reads the whole pvar instead). anqchor looks for them in$ANQCHOR_BGZIP/$ANQCHOR_TABIX, then onPATH, then in the htslib built insideextern/qpgen/submodules/htslib.zstdonPATHis needed only to index a.pvar.zst.