pgen-polars 0.1.1

Alpha Rust-native PLINK and BGEN reader for Python and Polars.

pgen-polars

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

[!WARNING] Alpha software: pgen-polars is under active development. APIs, supported formats, and behavior are subject to change between releases. Pin the package version when using it in other projects.

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.