WitnessCell

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

python -m pip install witnesscell==0.1.0

To use the optional AnnData adapter:

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.

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

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, model card, and file formats.

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. This double-blind review artifact uses the neutral attribution WitnessCell Authors and contains no author, institution, repository-account, DOI, or contact identifiers.