Metadata-Version: 2.4
Name: pertkit
Version: 0.1.0.dev0
Summary: Pseudo-bulk, perturbation baselines, calibrated metrics and bootstrap statistics for evaluating virtual-cell models.
Keywords: single-cell,perturbation,virtual-cell,evaluation,ai-safety
Author: albertlieyingadrian
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: pandas>=2.2
Requires-Dist: anndata>=0.11
Requires-Dist: scanpy>=1.11
Requires-Dist: pooch>=1.8
Requires-Dist: torch>=2.4 ; extra == 'models'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/albertlieyingadrian/playground-biology-ai
Project-URL: Source, https://github.com/albertlieyingadrian/playground-biology-ai/tree/main/packages/pertkit
Project-URL: Changelog, https://github.com/albertlieyingadrian/playground-biology-ai/blob/main/packages/pertkit/CHANGELOG.md
Provides-Extra: models
Description-Content-Type: text/markdown

# pertkit

The small toolkit behind [playground-biology-ai](https://github.com/albertlieyingadrian/playground-biology-ai): pseudo-bulk, perturbation baselines, calibrated metrics and bootstrap statistics for evaluating virtual-cell models honestly. Every number comes with a baseline or an interval, and the unit you resample is a perturbation, a donor or a cell line, never a cell.

Not on PyPI yet (the registry decision is made at the `0.1.0.dev0` release). Install from this repository:

```bash
uv add "pertkit @ git+https://github.com/albertlieyingadrian/playground-biology-ai#subdirectory=packages/pertkit"
# base: numpy, scipy, pandas, anndata, scanpy, pooch; add `[models]` to the name for torch
```

Inside this repo, `uv sync --extra cpu` installs it editable.

```python
from pertkit import pseudobulk, stats
from pertkit.io import iter_cells

bulk = pseudobulk.pseudobulk(adata, "perturbation")  # one row per condition, obs["n_cells"]
bulk = pseudobulk.pseudobulk_chunks(iter_cells("big.h5ad"), "perturbation")  # same, streaming

ci = stats.bootstrap_ci(scores, groups=perturbation_labels)  # resample perturbations, not cells
```

| module | what it holds |
|---|---|
| `pertkit.stats` | `bootstrap_ci` (optionally grouped), `wilson_ci`, `auroc`, `permutation_test`, `shuffled_baseline` |
| `pertkit.device` | `get_device()`: `PERTKIT_DEVICE`, then cuda, mps, cpu; `device_flags()` |
| `pertkit.pseudobulk` | `pseudobulk()` and `pseudobulk_chunks()` |
| `pertkit.io` | `iter_cells()`: row chunks from a backed h5ad (parquet shards arrive with the readiness kit) |
| `pertkit.data.fetch` | per-part TOML manifests, hash-verified `fetch()`, `pickle_to_npz()` through a restricted unpickler |
| `pertkit.header` | `manifest_prefixes()` for the lesson header |

Later units add `baselines`, `metrics`, `evals`, `models` and `screen`. The statistics functions were copied from [sandbagkit](https://github.com/albertlieyingadrian/playground-ai-sandbagging) (MIT), see the repo's `NOTICE.md`.

Tests: `uv run pytest packages/pertkit/tests` from the repo root. Markers: `slow` (excluded by default), `download` (needs `--download-tests`), `gpu`.

MIT, see `LICENSE`.
