Metadata-Version: 2.4
Name: pooledscreenid
Version: 0.1.2
Summary: Outcome-blind shortcut and separability diagnostics for pooled variant-effect screens
Author: Niu Niu, Fang Wei, Wenjuan Li, Yan Wang, Hu Liu, Bin Wu
License-Expression: MIT
Project-URL: Documentation, https://doi.org/10.5281/zenodo.22156510
Project-URL: Repository, https://doi.org/10.5281/zenodo.22156510
Keywords: deep mutational scanning,cold start,negative control,identifiability,variant effect
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
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
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PooledScreenID

PooledScreenID is a small, installable Python package for reporting four
quantities separately in cold-start pooled variant-effect analyses:

1. material predictive gain;
2. association with an outcome-blind control channel;
3. representation separability at a prespecified operating scale;
4. external calibration, kept distinct from the target estimand; and
5. the resulting allowed, restricted and prohibited claims.

The package does not infer a molecular mechanism and does not make treatment
recommendations. A cold split is treated as a transport test, not as proof of
the information source used by a model.

## Install

```bash
python -m pip install pooledscreenid-0.1.2-py3-none-any.whl
```

For a source checkout:

```bash
python -m pip install -e .
```

## Minimal Python API

```python
from pooledscreenid import run_audit

report, ledger = run_audit(
    config_path="examples/configs/egfr.json",
    output_dir="example_output/egfr",
)
print(report["claim_resolution"])
```

## Command line

```bash
pooledscreenid audit \
  --config examples/configs/egfr.json \
  --output-dir example_output/egfr

pooledscreenid audit \
  --config examples/configs/met.json \
  --output-dir example_output/met
```

Each run writes `report.json`, `report.md` and `claim_ledger.json`. Inputs,
configuration, source hashes and expected outputs are frozen in the release.
The ledger exposes `material_signal`, `control_association`, `separability` and
`external_calibration` as independent fields. `claim_resolution` is generated
from those fields under priority-ordered rules and never replaces them.

PooledScreenID 0.1.2 is the article-linked frozen release. The public API is
managed with semantic versioning. It supports Python 3.10-3.13 and has no
third-party runtime dependencies; the test suite uses pytest.

## Included end-to-end examples

- `EGFR`: ten frozen variant-cold folds from the L858R-background pooled EGFR
  inhibitor screen, plus the outcome-free geometry and conditional operating
  boundary used in the manuscript.
- `MET`: ten frozen variant-cold folds from an independently selected pooled
  MET inhibitor screen. The example demonstrates a result below the materiality
  gate and explicitly leaves separability unevaluated.

These examples begin with frozen, source-derived fold diagnostics rather than
raw sequencing reads. They reproduce the evidence-to-claim stage of the
framework; raw count processing and model fitting remain documented in the
accompanying analysis repository.

## Interpretation order

The software reports the four-axis evidence vector before returning a summary label. If
shared predictability exceeds its prespecified boundary, or lies inside a
prespecified boundary zone, fine-grained attribution is restricted before any
control-specific contrast is interpreted. Absence of a material increment is
not an equivalence or biological-null claim.

## Release integrity

`RELEASE_MANIFEST.json` and `SHA256SUMS.txt` bind the software, tests, continuous-integration configuration, examples,
configuration files and claim ledger to this release. The Zenodo record is the
permanent release series: <https://doi.org/10.5281/zenodo.22156510>.
