jaxQTL

jaxQTL is a JAX-based command-line tool and Python library for cell-type-specific eQTL mapping from donor-level single-cell pseudobulk expression. It provides Poisson and Negative Binomial count models and also supports Gaussian molecular phenotypes.

Zhang, Z., Kim, A., Suboc, N., Mancuso, N., and Gazal, S. (2025). Efficient count-based models improve power and robustness for large-scale single-cell eQTL mapping. medRxiv (https://www.medrxiv.org/content/10.1101/2025.01.18.25320755v2)

Read the documentation

Installation

jaxQTL requires Python 3.11 or newer.

pip install jaxqtl
jaxqtl --help

Quick example

From a repository checkout, run a SPA + ACAT cis scan over ten genes from the bundled tutorial data:

jaxqtl cis \
  --bfile tutorial/input/chr22_N100 \
  --pheno tutorial/input/CD4_NC.N100.bed.gz \
  --covar tutorial/input/donor_features.tsv \
  --gene-list tutorial/input/genelist_10 \
  --model nb \
  --test score \
  --set-offset-from-libsize \
  --normalize-covar \
  --spa \
  --acat \
  --out tutorial/output/quickstart_spa_acat

The command writes tutorial/output/quickstart_spa_acat.cis.score.spa.acat.parquet.gz.

For your own data, compute library-size offsets from the full gene matrix; see Offsets before using a restricted input file. Check convergence and apply FDR correction across genes with either method.

Beta permutation remains available when a permutation reference is desired: replace --spa --acat with --nperm 1000. The methods can yield different discoveries; see Calibration tradeoffs.

The documentation covers the single-cell cis-eQTL workflow, the tutorial, input formats, mapping workflows, and output interpretation.

Development

See the development setup for environment, test, and documentation build instructions.

Citation and support

See the citation page when using jaxQTL in published work. Report bugs and feature requests through the GitHub issue tracker.