Metadata-Version: 2.4
Name: biobouncer
Version: 0.1.2
Summary: A gate for biological inputs: validate identifiers and inputs the same way in R and Python.
Project-URL: Homepage, https://github.com/samuelbharti/biobouncer
Project-URL: Documentation, https://www.samuelbharti.com/biobouncer/py/
Project-URL: Source, https://github.com/samuelbharti/biobouncer
Project-URL: Issues, https://github.com/samuelbharti/biobouncer/issues
Project-URL: Changelog, https://github.com/samuelbharti/biobouncer/blob/main/pkg-py/CHANGELOG.md
Author-email: Samuel Bharti <samuelbharti.io@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bioinformatics,identifiers,ontology,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: platformdirs>=3
Requires-Dist: pyyaml>=6
Provides-Extra: adapters
Requires-Dist: pandera[pandas]>=0.20; extra == 'adapters'
Requires-Dist: pydantic>=2; extra == 'adapters'
Provides-Extra: gx
Requires-Dist: great-expectations>=1; extra == 'gx'
Provides-Extra: narwhals
Requires-Dist: narwhals>=2; extra == 'narwhals'
Description-Content-Type: text/markdown

# biobouncer <img src="https://raw.githubusercontent.com/samuelbharti/biobouncer/main/pkg-r/man/figures/logo.png" align="right" height="150" alt="biobouncer logo" />

> A gate for biological inputs. Validate gene symbols, ontology terms, variant
> formats, and database identifiers, the same way, with the same answer, in
> both **R** and **Python**.

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21346522.svg)](https://doi.org/10.5281/zenodo.21346522)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/samuelbharti/biobouncer/blob/main/LICENSE)

This is the Python package. A companion [R package](https://www.samuelbharti.com/biobouncer/r/)
is built alongside it, and the two are held to the same verdict for the same
input by a shared conformance corpus.

> **Status: pre-1.0.** The public API is in use and documented. It may still
> change before the 1.0 release.

## Install

```sh
pip install biobouncer
```

The framework adapters are optional extras:

```sh
pip install "biobouncer[adapters]"   # pandera and pydantic
pip install "biobouncer[gx]"         # Great Expectations
pip install "biobouncer[narwhals]"   # column checks over pandas, polars, or pyarrow
```

## Usage

```python
import biobouncer

# List what can be checked.
biobouncer.sources()

# pattern mode: is the string well-formed?
biobouncer.check_id(["MONDO:0005148", "mondo:5148"], source_db="mondo")

# cache mode: does the id exist in a pinned snapshot, offline?
biobouncer.check_id("MONDO:0005148", source_db="mondo", how="cache", version="sample")
```

`check_id()` returns a list of `Result` records, one per input, in the order given.
A missing input stays missing rather than turning into a quiet `False`.

To validate and clean a whole column in one call:

```python
r = biobouncer.report(["MONDO:0005148", "mondo:5148", "NOTANID", None], source_db="mondo")

r.summary
# {'total': 4, 'valid': 1, 'invalid': 2, 'repairable': 1, 'missing': 1, 'indeterminate': 0}

r.repair()  # substitute the repairable values, leave everything else alone
# ['MONDO:0005148', 'MONDO:0005148', 'NOTANID', None]

r.to_frame()  # a verdict table (pandas, polars, or pyarrow via narwhals)
#            input  valid     normalized     suggestion error
# 0  MONDO:0005148   True  MONDO:0005148            NaN  None
# 1     mondo:5148  False            NaN  MONDO:0005148  None
# 2        NOTANID  False            NaN            NaN  None
# 3            NaN   None            NaN            NaN  None
```

Checks run in four modes: `pattern` (offline shape), `cache` (offline existence
against a pinned snapshot), `remote` (live existence against the source API), and
`existence` (snapshot first, then remote). Snapshots ship with the package, so the
offline modes work with no setup and no network. `biobouncer.pull()` refreshes one
to a newer dated release when you want it.

There is also a `biobouncer` command line tool that exits non-zero on any invalid
input, for use in a pipeline or in CI.

## Documentation

Full documentation is at
[samuelbharti.com/biobouncer/py](https://www.samuelbharti.com/biobouncer/py/),
including the source list, the caching and snapshot guide, and the adapter
reference.

## Contributing

The package is developed in the
[biobouncer monorepo](https://github.com/samuelbharti/biobouncer) alongside the R
package and the shared spec. See
[CONTRIBUTING.md](https://github.com/samuelbharti/biobouncer/blob/main/CONTRIBUTING.md)
to get set up, and
[open an issue](https://github.com/samuelbharti/biobouncer/issues) for a bug or a
source request.

## Citation

If you use biobouncer in your work, please cite it. The DOI above always resolves
to the latest release; see
[CITATION.cff](https://github.com/samuelbharti/biobouncer/blob/main/CITATION.cff)
for the current version and a per-version DOI. A preprint is in preparation.

## License

MIT. See
[LICENSE](https://github.com/samuelbharti/biobouncer/blob/main/LICENSE).
