fastrho

Fine-scale recombination maps from population genotypes, without per-dataset training.

fastrho is a research package for amortized, fine-scale recombination-map inference. A bidirectional Mamba-2 encoder-decoder reads one order-invariant feature token per SNP and estimates the population-scaled recombination rate for every adjacent-SNP interval.

What it does

Installation

Clone the public source repository and create the locked environment:

git clone https://github.com/kevinkorfmann/fastrho.git
cd fastrho
uv sync --frozen --extra inference --extra io
source .venv/bin/activate

Inference is tested on Python 3.10 and 3.12 and requires Linux, an NVIDIA GPU, and a CUDA toolchain compatible with the locked PyTorch and Mamba-SSM builds. uv is recommended because the lockfile also records the extension build requirements. CPU-only VCF inspection, simulation, and data conversion do not load the model. Record the environment used for a run with its checkpoint IDs.

Download the verified model bundle

The domain-randomized-v1 release contains the checkpoint and its required feature-statistics companion. Keep the two files together; feat_stats.npz is part of the trained model and must not be recomputed from a prediction cohort.

python3 scripts/fetch_model_release.py \
  --model-id domain-randomized-v1 \
  --output-dir downloaded-models

The public, checksummed model artifacts are also available from the domain-randomized-v1 release.

Make a map

fastrho predict \
  --vcf cohort.vcf.gz \
  --chrom chr1 \
  --checkpoint downloaded-models/domain-randomized-v1/model.ckpt \
  --stats downloaded-models/domain-randomized-v1/feat_stats.npz \
  --mutation-rate 1.5e-8 \
  --ne 10000 \
  --input-mode auto \
  --missing drop-site \
  --window-size 50000 \
  --out chr1.50kb.bed

VCF input is restricted to one contig per prediction call. Missing sites are dropped rather than imputed as reference, and positions are converted to 0-based, half-open BED coordinates. input_mode="auto" distinguishes phased from unphased genotype separators; it cannot establish ancestral polarization.

Python API

from pathlib import Path
import fastrho

bundle = Path("downloaded-models/domain-randomized-v1")

pred = fastrho.quick_map_from_vcf(
    "cohort.vcf.gz",
    bundle / "model.ckpt",
    bundle / "feat_stats.npz",
    contig="chr1",
    mutation_rate=1.5e-8,
    Ne=10_000,
    input_mode="auto",
    missing="drop-site",
    device="cuda:0",
)

df = fastrho.to_dataframe(pred, chrom="chr1")
fastrho.write_bed(pred, "chr1.50kb.bed", chrom="chr1", window_size=50_000)

Before interpreting a map

An LD-based estimate is a population recombination map, not a direct observation of contemporary crossovers. Demographic history, structure, inversions, selection, relatedness, selfing, and gene conversion can change the signal. For a new cohort, record the checkpoint and statistics hashes, input view, filtering, mutation rate, effective population size, coordinates, and reporting window; then evaluate split-sample repeatability, realistic simulations, or an independent map.

Documentation

The public documentation contains the software guide, method schematic, and synthetic example.

• Quickstart
• Python API
• Use fastrho with your dataset
• Interpret the output
• Checkpoints
• Known-answer simulation

Verification

python -m pytest tests/test_io_api.py tests/test_phase1_target.py \
  tests/test_phase2_features.py tests/test_stitching.py
python scripts/release_check.py
python -m build

Citation and license

Citation metadata are provided in CITATION.cff. Code is licensed under the MIT License; external datasets and pretrained weights retain their own licenses and terms.