pgen-polars

Rust-native reader for PLINK 2 .pgen, PLINK 1 .bed, and BGEN v1.2 genotype files, with Python and Polars integration.

Python package installation

Create or activate a Python 3.10 or newer virtual environment, then install the package from PyPI. Because the project is alpha software, pin the exact version in applications and reproducible environments:

python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install "pgen-polars==0.1.1"

With uv:

uv add "pgen-polars==0.1.1"

Verify the installation:

python -c "import pgen_polars; print(pgen_polars.__version__)"

Published wheels support CPython 3.10 and newer on Linux (x86-64 and ARM64), macOS (Intel and Apple Silicon), and 64-bit Windows. Building from the source distribution requires Rust 1.85 or newer. pgen-polars currently supports Polars 1.31 through 1.42.

Status: eager and lazy/chunked .bed, .pgen, and BGEN Layout 2 reading is implemented, including ordered sample/variant selection and long or samples-by-variants wide output. Statistics remain deferred. See the roadmap and product specification for details.

Python API

from pgen_polars import read_bgen, read_pgen, scan_bgen, scan_pgen

# read_pgen also accepts PLINK 1 .bed files and auto-detects sidecars.
features = read_pgen(
    "cohort.pgen",
    samples=["sample_42", "sample_7"],
    variants=["variant_1", "variant_2"],
)

lazy = scan_pgen("cohort.pgen", variants=["variant_1", "variant_2"])
selected = lazy.select("ID", "variant_2").collect()

# BGEN v1.2 Layout 2 requires an Oxford .sample file. BGEN does not
# identify the reference allele, so ref_allele must be explicit.
bgen_features = read_bgen(
    "cohort.bgen",
    ref_allele="last",
    samples=["sample_42", "sample_7"],
    rsids=["rs123", "rs456"],
)
bgen_lazy = scan_bgen("cohort.bgen", ref_allele="last")

Metadata readers are also available as read_psam, read_pvar, read_fam, read_bim, and read_sample. Eager readers return Polars DataFrames; scan functions return Polars LazyFrames. Wide output is the default, and output_format="long" enables row-oriented output.

Development

Development requires Rust, uv, and Python 3.10 or newer.

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
uv venv --python 3.10
uv pip install -e '.[dev]'
uv run pytest tests/python -q

Releases

The package version comes from Cargo.toml. A matching tag such as v0.1.1 builds and tests platform wheels and a source distribution, then publishes them to PyPI through Trusted Publishing.