Installation

Requirements

Locator requires Python 3.10 or higher and TensorFlow 2.16+.

Installing with pixi (recommended)

Pixi manages all dependencies including TensorFlow, CUDA, and the geospatial stack. This is the recommended approach:

git clone https://github.com/kr-colab/ReLocator.git
cd ReLocator
pixi install              # GPU environment (default)

This installs TensorFlow with CUDA support, Ray for multi-GPU parallelism, bio2zarr for fast VCF conversion, and all development tools.

Available environments:

pixi install              # GPU + ray + fast-vcf + dev (default)
pixi install -e cpu       # CPU + ray + fast-vcf + dev
pixi install -e test      # CPU + dev (minimal for testing)
pixi install -e docs      # CPU + sphinx
pixi install -e minimal   # CPU only, no extras

Running tasks:

pixi run test             # run tests
pixi run lint             # check linting
pixi run format           # auto-format code
pixi run docs             # build documentation

Installing with pip

Locator can also be installed with pip. Note that you must manage TensorFlow and CUDA installation separately when using pip.

pip install locator

For development:

pip install locator[dev,docs,ray,fast-vcf]

Optional pip extras:

• locator[dev] — pytest, ruff, pre-commit

• locator[docs] — sphinx and related packages

• locator[ray] — Ray for multi-GPU parallel analysis

• locator[fast-vcf] — bio2zarr + cyvcf2 for fast VCF-to-Zarr conversion

Fast VCF-to-Zarr Conversion

For large VCF files, we recommend converting to zarr format for fast loading. With pixi, bio2zarr is included in the default environment. With pip, install via pip install locator[fast-vcf].

bcftools index -t genotypes.vcf.gz
vcf2zarr convert -p 8 genotypes.vcf.gz genotypes.zarr

Locator supports zarr files from both bio2zarr and scikit-allel. See CLI Guide for usage with windowed analysis.

Installing from Source

git clone https://github.com/kr-colab/ReLocator.git
cd ReLocator

# With pixi (recommended)
pixi install

# Or with pip
pip install -e ".[dev]"

Verifying Installation

# With pixi
pixi run python -c "from locator import Locator; print('OK')"

# Or directly
python -c "from locator import Locator; print('OK')"

Next Steps

• Read the Usage Guide guide to learn how to use Locator

• Check the API Reference reference for detailed documentation