Metadata-Version: 2.4
Name: pgen-polars
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Dist: polars>=1.31,<1.43
Requires-Dist: numpy>=2.0 ; extra == 'benchmark'
Requires-Dist: pgenlib>=0.94.1,<0.95 ; extra == 'benchmark'
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: maturin>=1.7,<2.0 ; extra == 'dev'
Requires-Dist: numpy>=2.0 ; extra == 'dev'
Requires-Dist: twine>=6.0 ; extra == 'dev'
Provides-Extra: benchmark
Provides-Extra: dev
License-File: LICENSE
Summary: Alpha Rust-native PLINK and BGEN reader for Python and Polars.
Keywords: bioinformatics,genetics,pgen,plink,polars
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/idinsmore1/pgen_rs/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/idinsmore1/pgen_rs
Project-URL: Issues, https://github.com/idinsmore1/pgen_rs/issues
Project-URL: Repository, https://github.com/idinsmore1/pgen_rs

# 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:

```bash
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`](https://docs.astral.sh/uv/):

```bash
uv add "pgen-polars==0.1.1"
```

Verify the installation:

```bash
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](https://github.com/idinsmore1/pgen_rs/blob/main/docs/milestones.md)
> and [product specification](https://github.com/idinsmore1/pgen_rs/blob/main/docs/product-spec.md)
> for details.

## Python API

```python
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`](https://docs.astral.sh/uv/), and Python 3.10
or newer.

```sh
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.

