Metadata-Version: 2.4
Name: witnesscell
Version: 0.1.0
Summary: Evidence-gated condition-mean prediction for unmeasured genetic combinations
License-Expression: Apache-2.0
Keywords: single-cell,genetic-perturbation,gene-regulation,selective-prediction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.24
Requires-Dist: scipy<2,>=1.10
Requires-Dist: scikit-learn<2,>=1.3
Provides-Extra: anndata
Requires-Dist: anndata<1,>=0.10; extra == "anndata"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Dynamic: license-file

# WitnessCell

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)

WitnessCell is an evidence-gated predictor of **condition means** for unmeasured
two-endpoint genetic combinations. Version 0.1.0 implements the frozen v14
research contract as a typed Python API and command-line application.

The package is intentionally narrow. It does not claim cell-level generative
simulation, calibrated universal uncertainty, causal identification, or
automatic routing to another model. Its selective policy has exactly two
actions: `accept` or `abstain`.

## Installation

```bash
python -m pip install witnesscell==0.1.0
```

To use the optional AnnData adapter:

```bash
python -m pip install "witnesscell[anndata]==0.1.0"
```

## Input contract

WitnessCell consumes per-condition expression means, population variances and
cell counts. Conditions are `control`, single endpoints such as `A`, or
two-endpoint combinations such as `A+B`. Training and validation roles are
explicit; final-target outcomes are never accepted by `predict`.

```python
import numpy as np
from witnesscell import ConditionMoments, SplitSpec, WitnessCell

genes = ("A", "B", "C", "D")
means = {
    "control": np.zeros(4),
    "A": np.array([-1.0, 0.2, 0.0, 0.1]),
    "B": np.array([0.1, -1.1, 0.2, 0.0]),
    "C": np.array([0.0, 0.1, -0.8, 0.2]),
    "D": np.array([0.2, 0.0, 0.1, -0.9]),
    "A+B": np.array([-0.9, -0.8, 0.1, 0.1]),
}
variances = {condition: np.full(4, 0.2) for condition in means}
counts = {condition: 100 for condition in means}

moments = ConditionMoments.from_mappings(
    genes=genes, means=means, variances=variances, counts=counts
)
split = SplitSpec.create(
    train_conditions=("control", "A", "B", "C", "D", "A+B")
)
model = WitnessCell().fit(moments, split, gene2go={gene: [] for gene in genes})

prediction = model.predict(["A+C", "B+D"])
print(prediction.means.shape)  # (2, 4)
model.save("model.wcell")
```

For a dataset with validation doubles, include those labels in
`validation_conditions`; they calibrate the saturation, interaction-kernel
noise, and residual amplitude. Do not place final evaluation targets there.

## Command line

```bash
witnesscell validate --moments moments.npz
witnesscell fit --moments moments.npz --split split.json \
  --gene2go gene2go.json --output model.wcell
witnesscell predict --model model.wcell --conditions A+C B+D \
  --output predictions.npz
witnesscell inspect --model model.wcell
```

Both model and prediction files are pickle-free. A `.wcell` model is a
versioned ZIP with per-entry SHA-256 integrity checks; loading does not execute
serialized Python code.

## Algorithm contract

The frozen path combines:

1. an evidence-gated dense mean/GO endpoint head;
2. an evidence-gated one-coordinate sparse self head;
3. a response-fingerprint amplitude correction with two required lower-bound
   gates;
4. a saturating factorized backbone; and
5. an endpoint-incidence kernel over training-double residuals.

When a gate fails, WitnessCell uses the exact simpler fallback defined by the
contract. See [Algorithm contract](docs/ALGORITHM_CONTRACT.md),
[model card](docs/MODEL_CARD.md), and [file formats](docs/FORMATS.md).

## Reproducibility and release safety

The source distribution includes tests, an independent reference-parity
runner, anonymous-release scanning, and CI/release workflows. Production
publication should use PyPI Trusted Publishing with a protected `pypi`
environment; no long-lived API token is required by the provided workflow.

## License and attribution

Apache License 2.0. See [LICENSE](LICENSE). This double-blind review artifact
uses the neutral attribution **WitnessCell Authors** and contains no author,
institution, repository-account, DOI, or contact identifiers.
