PerturbResidual 0.1.0

PerturbResidual converts matched control, single-perturbation, and measured double-perturbation means into auditable pair-level functional-coupling scores. Score construction does not read STRING, KEGG, dataset names, or other functional labels.

The scientific object is the higher-order residual

R_AB = d_AB - d_A - d_B

where each effect is measured relative to the same control. PerturbResidual then separates recurrent source means from gene-scale heteroscedasticity and chooses a frozen nuisance-control branch using only the measured panel's median endpoint degree.

Scientific scope

PerturbResidual:

• ranks combinations that have already been measured;
• tests whether higher-order residual structure carries functional coupling;
• reports whether its selected branch contains a transductive component.

It is not a directed-edge estimator, a full-transcriptome response predictor, or a method for predicting arbitrary unmeasured combinations.

Frozen algorithm

For each measured pair, the software constructs:

1. the original pair-specific top-10 residual score;
2. a strict leave-one-pair-out source-mean correction;
3. an independently estimated gene-scale correction;
4. a sparse OPG-A score;
5. when required, a strict-LOPO spectral score and a bounded transductive PC5 tail.

The label-blind router is:

median endpoint degree < 5   -> sparse OPG-A
median endpoint degree >= 5  -> dense spectral-tail

The strict-LOPO description applies to the spectral component. The PC5 tail is unsupervised but transductive because its basis contains the scored pair; this fact is written to every dense-run audit. Dense scoring requires at least ten genes after the frozen HVG and perturbation-identity masks; smaller spaces stop with an explicit error instead of silently changing the low-rank formula.

Install the release artifact

PerturbResidual 0.1.0 supports Python 3.12. Compatibility will be broadened only after the corresponding runtime CI gates pass.

python -m pip install perturbresidual-0.1.0-py3-none-any.whl

After an eventual PyPI publication, the intended command is:

python -m pip install perturbresidual==0.1.0

The present release bundle prepares the wheel and source distribution but does not claim that either has already been uploaded to PyPI.

Python API

from perturbresidual import PerturbResidual

model = PerturbResidual(route="auto")
result = model.fit_score(
    control=control,          # shape: (genes,)
    singles=singles,          # dict[str, array of shape (genes,)]
    doubles=double_means,     # shape: (pairs, genes)
    pairs=pairs,              # list[tuple[str, str]]
    gene_names=gene_names,
)

scores = result.scores
audit = result.audit
frame = result.to_dataframe()

route="sparse" and route="dense" are available for diagnostics. Scientific use should normally retain route="auto". Changing route, hvg_quantile, top_k, or source_ridge marks the output NONCANONICAL_VARIANT, records the exact parameter differences, and removes the frozen-paper evidence claim. Set compute_all_components=True to compute dense diagnostics without changing the selected score or canonical status.

Command line

perturbresidual score \
  --control control.csv \
  --singles singles.csv \
  --doubles doubles.csv \
  --output results

Input files use a wide format:

• control.csv: exactly one row; every column is a gene;
• singles.csv: first column perturbation, followed by the same gene columns;
• doubles.csv: first columns source_a,source_b, followed by the same genes.

Perturbation names and pair endpoints must be nonempty. Duplicate single names are rejected rather than silently overwritten.

The output directory contains:

• pair_scores.csv;
• route_audit.json;
• nuisance_diagnostics.csv;
• run_config.json.

Reproducibility

Run fast tests from the source tree:

PYTHONPATH=src python -m unittest discover -s tests -v

Run the frozen Norman/Wessels regression when PerturbResidual_repo_v2 is available alongside the release:

PYTHONPATH=src python validation/run_frozen_regression.py \
  --repo-root ../PerturbResidual_repo_v2 \
  --out-dir validation/results

The regression finalizes both label-blind score vectors before evaluating the four STRING/KEGG metrics per panel.

Evidence boundary

The paper reports the strongest point estimates in the symmetrically evaluated external comparator fields across eight Norman/Wessels metrics. Both panels contributed to method development, and seven of eight source-endpoint intervals cross zero. This package therefore supports reproducibility and reuse; it does not turn the developmental result into confirmatory two-panel SOTA.

License

MIT.

Maintainer: Ziran Peng.