spacr.annotation_power¶

Estimate which guide assignments a pooled screen can support.

The calculations combine each guide’s within-well fraction with classifier sensitivity and specificity. They report the minimum fraction required for a phenotype-positive call to reach a requested posterior probability, identify guides that never reach that fraction, and estimate the screen design needed to improve coverage.

Increasing the number of cells in a well increases the number of possible assignments but does not change the posterior probability for an individual cell. That probability changes when guide fractions or classifier performance change. The functions in this module therefore keep annotation coverage and assignment confidence as separate quantities.

Functions¶

`annotatable`(→ Dict[str, object])	Summarize the annotatable portion of a screen.
`posterior_for_prior`(→ float)	Return guide probability after a phenotype-positive classifier call.
`quality_report`(→ str)	Format annotation quality and power metrics as a text report.
`required_fraction`(→ float)	Return the minimum guide fraction for a requested posterior.
`screen_size_for`(→ Dict[str, object])	Estimate the screen design needed to improve guide reachability.

Module Contents¶

spacr.annotation_power.annotatable(fractions: Mapping[str, Mapping[str, float]], *, sensitivity: float, specificity: float, decision: float = 0.55, cells_per_well: Mapping[str, int] | None = None) → Dict[str, object][source]¶

Summarize the annotatable portion of a screen.

Parameters:

fractions (mapping) – Nested mapping {well: {guide: fraction}}.
sensitivity (float) – Classifier performance used to compute the minimum guide fraction.
specificity (float) – Classifier performance used to compute the minimum guide fraction.
decision (float, default=0.55) – Required posterior probability for a guide assignment.
cells_per_well (mapping, optional) – Cell count for each well. When supplied, the result includes an upper bound on the number of reachable cells.

Returns:

dict – Minimum fraction, reachable well-guide pairs and guides, and optional cell-count bounds. A guide is unreachable when it fails to meet the minimum fraction in every well.

spacr.annotation_power.posterior_for_prior(prior: float, sensitivity: float, specificity: float) → float[source]¶

Return guide probability after a phenotype-positive classifier call.

Parameters:

prior (float) – Guide fraction before observing the classifier call.
sensitivity (float) – Probability of a positive call for a guide-carrying cell.
specificity (float) – Probability of a negative call for a cell without the guide.

Returns:

float – Posterior guide probability, or nan when the call has zero total probability under the supplied rates.

spacr.annotation_power.quality_report(verdicts: Mapping[str, object], *, power: Mapping[str, object] | None = None, size: Mapping[str, object] | None = None, width: int = 78) → str[source]¶

Format annotation quality and power metrics as a text report.

Parameters:

verdicts (mapping) – Mapping from method name to spacr.annotation_validation.Verdict.
power (mapping, optional) – Result from annotatable().
size (mapping, optional) – Result from screen_size_for().
width (int, default=78) – Rule width used in the text layout.

Returns:

str – Report that presents coverage, precision, and recall separately, followed by optional reachability and screen-size estimates.

spacr.annotation_power.required_fraction(sensitivity: float, specificity: float, *, decision: float = 0.55) → float[source]¶

Return the minimum guide fraction for a requested posterior.

Parameters:

sensitivity – probability of a positive call for a guide-carrying cell.
specificity – probability of a negative call without the guide.

decision is the minimum probability that a phenotype-positive cell carries the guide. The calculation accounts for false positives among cells that do not carry the guide.

spacr.annotation_power.screen_size_for(fractions: Mapping[str, Mapping[str, float]], *, sensitivity: float, specificity: float, decision: float = 0.55, target: float = 0.8) → Dict[str, object][source]¶

Estimate the screen design needed to improve guide reachability.

Parameters:

fractions (mapping) – Nested mapping {well: {guide: fraction}}.
sensitivity (float) – Classifier performance used to compute the minimum guide fraction.
specificity (float) – Classifier performance used to compute the minimum guide fraction.
decision (float, default=0.55) – Required posterior probability for a guide assignment.
target (float, default=0.80) – Target share recorded in the result for reporting.

Returns:

dict – Current screen shape, estimated guides per well and wells required, size multiplier, and the specificity required at the current shape.

Notes

The estimate holds library size and mean wells per guide fixed. It raises typical guide fractions by placing fewer guides in each well and therefore increasing the number of wells proportionally.