spacr.hit_attribution

Resolve a well-level CRISPR hit back to candidate single cells.

Sequencing says which guide reads were present in a well. It does not say which cell carried a guide, and a read fraction is not automatically an infection fraction. This module keeps that distinction explicit:

• build_hit_cell_frame() builds the review queue: target-well cells ranked in the hit’s phenotype direction.

• fit_hit_attribution() adds a cross-fitted two-component hierarchical mixture. Guide fraction changes a learned well-level prior; it is never imposed as the mean cell probability.

• write_hit_attribution() records versioned probabilities in their own tables. Hand annotations are untouched until an explicit promotion call.

The output is named hit_like_probability, not guide identity. Only a cell-resolved barcode or arrayed perturbation turns that inference into ground truth.

Exceptions

HitAttributionError	The requested cell attribution is ambiguous or not identifiable.
InsufficientDesignError	Raised when there are too few independent wells or plates to cross-fit.

Classes

HitAttributionResult	Cross-fitted hit-like probabilities and independent-unit evidence.
HitInvestigationResult	Portable result bundle used by the GUI and database persistence.
HitRunContext	The exact regression result a cell investigation came from.

Functions

build_hit_cell_frame(→ pandas.DataFrame)	Join exact cells to well guide fractions and build a review ranking.
crossfit_candidate_probabilities(...)	Cross-fit a conservative morphology classifier from bag labels.
fit_hit_attribution(→ HitAttributionResult)	Estimate cross-fitted target-hit-like probabilities.
promote_calls(→ str)	Promote stored calls while recording every previous annotation value.
promote_hit_calls(→ str)	Explicitly promote positive calls to a fresh, reversible annotation.
quantify_candidate_enrichment(...)	Quantify candidate prevalence at the well experimental unit.
quantify_hit_enrichment(→ Dict[str, Any])	Per-well enrichment, well bootstrap CI, and a within-plate null.
revert_promotion(→ int)	Restore exactly the values replaced by promote_calls().
store_attribution(→ int)	Store the GUI investigation bundle under its immutable run context.
undo_hit_promotion(→ int)	Clear values written by one promotion; preserve the audit record.
write_hit_attribution(→ str)	Persist a versioned attribution without touching annotation columns.

Module Contents

exception spacr.hit_attribution.HitAttributionError

Bases: ValueError

The requested cell attribution is ambiguous or not identifiable.

Initialize self. See help(type(self)) for accurate signature.

exception spacr.hit_attribution.InsufficientDesignError

Bases: HitAttributionError

Raised when there are too few independent wells or plates to cross-fit.

Initialize self. See help(type(self)) for accurate signature.

class spacr.hit_attribution.HitAttributionResult

Cross-fitted hit-like probabilities and independent-unit evidence.

Variables:

• cells – cell-level frame with cross-fitted probabilities, calls, uncertainties, and fold assignments.

• wells – well-level probability, prevalence, score, and guide-fraction summaries.

• guide_evidence – per-guide dose-response and probability contrasts.

• threshold_sensitivity – well-level prevalence contrasts across the evaluated probability thresholds.

• validation – well-resampling and permutation validation statistics.

• feature_columns – morphology features used to fit the mixture.

• well_columns – columns that form the well identity.

• object_columns – columns that form the stable cell-object identity.

• target_gene – gene whose hit-like morphology was attributed.

• target_guides – guides treated as evidence for target_gene.

• score_column – input column holding the original phenotype score.

• direction – phenotype direction, "positive" or "negative".

• threshold – probability cutoff used for hit_like_call.

• split_level – held-out grouping level used for cross-fitting.

• random_seed – seed used for validation resampling.

• source_regression_run – source regression run identifier persisted with the attribution so the morphology evidence remains traceable.

• warnings – circularity or design caveats that must accompany the probabilities and summary rather than being lost after fitting.

summary() → str

Return a multi-line text summary of the effect and its interval.

The bootstrap interval is always included, because a prevalence difference quoted without one can make a noisy estimate look like a finding.

Returns:

a multi-line summary.

class spacr.hit_attribution.HitInvestigationResult

Portable result bundle used by the GUI and database persistence.

Parameters:

• attribution_run_id – unique identifier under which this investigation is persisted.

• context – source regression hit and run-provenance contract.

• cells – cell-level candidate probabilities, uncertainty, calls, and held-out fold assignments.

• wells – well-level candidate-prevalence summary.

• enrichment – well-level effect estimates, confidence intervals, and resampling statistics.

• feature_columns – morphology-feature columns used by the cross-fitted classifier.

• split_level – grouping level held out during cross-fitting, normally "plate" or "well".

• warnings – design and fit caveats retained for display and persistence.

class spacr.hit_attribution.HitRunContext

The exact regression result a cell investigation came from.

Parameters:

• regression_results_folder – folder containing the regression result from which this investigation was launched.

• regression_run_sha256 – SHA-256 digest identifying that source regression run.

• gene – selected hit-gene identifier.

• phenotype – regression phenotype for which the gene was selected.

• effect – regression effect estimate for the selected gene and phenotype.

• guides – guide identifiers assigned to the selected hit gene.

• fdr – multiple-testing-adjusted significance of the selected hit, or nan when unavailable.

• direction – phenotype direction used to rank candidate cells, normally "positive" or "negative".

spacr.hit_attribution.build_hit_cell_frame(cells: pandas.DataFrame, guide_fractions: pandas.DataFrame, *, target_guides: Sequence[str], score_column: str, direction: str = 'positive', guide_column: str = 'grna', fraction_column: str = 'fraction', well_columns: Sequence[str] = WELL_COLUMNS, object_columns: Sequence[str] = OBJECT_COLUMNS) → pandas.DataFrame

Join exact cells to well guide fractions and build a review ranking.

The returned candidate_percentile ranks cells only within their well. It is deliberately not named a probability or infection call.

Parameters:

• cells – cell-level measurements with the phenotype score and stable well and object identifiers.

• guide_fractions – one sequencing-fraction row per guide and well.

• target_guides – guide identifiers assigned to the hit gene.

• score_column – column in cells containing the phenotype score.

spacr.hit_attribution.crossfit_candidate_probabilities(frame: pandas.DataFrame, *, feature_columns: Sequence[str] | None = None, target_column: str = 'target_well', prefer_plate: bool = True, random_seed: int = 0, n_splits: int = 5, threshold: float = 0.5) → Tuple[pandas.DataFrame, List[str], str, List[str]]

Cross-fit a conservative morphology classifier from bag labels.

This is the non-parametric alternative to fit_hit_attribution()’s hierarchical mixture. It predicts candidate_probability and never calls it infection probability. Model outputs, guide fractions, object identifiers and annotations are excluded from the default feature set.

Parameters:

frame – cell-level candidate frame with target-well labels and plate, row, and column identifiers.

spacr.hit_attribution.fit_hit_attribution(frame: pandas.DataFrame, *, target_gene: str, feature_columns: Sequence[str] | None = None, include_original_score: bool = False, threshold: float = 0.8, split_by: str = 'auto', random_seed: int = 0, n_bootstrap: int = 1000, n_permutations: int = 1000, n_pipeline_permutations: int = 0, source_regression_run: str = '') → HitAttributionResult

Estimate cross-fitted target-hit-like probabilities.

frame must be the output of build_hit_cell_frame(). Every cell is predicted by a mixture fitted without its well, or without its plate when at least three plates make that split identifiable.

Parameters:

• frame – ranked cell frame produced by build_hit_cell_frame().

• target_gene – gene name to attach to the attribution result.

spacr.hit_attribution.promote_calls(db_path: str, attribution_run_id: str, annotation_column: str) → str

Promote stored calls while recording every previous annotation value.

Parameters:

• db_path – path to the SQLite measurements database to update.

• attribution_run_id – stored investigation whose calls to promote.

• annotation_column – png_list column to create or update.

spacr.hit_attribution.promote_hit_calls(db_path: str, result: HitAttributionResult, *, run_id: str, annotation_column: str, positive_value: Any = 1) → str

Explicitly promote positive calls to a fresh, reversible annotation.

Parameters:

• db_path – path to the SQLite measurements database to update.

• result – attribution result containing the positive object calls.

• run_id – attribution-run identifier to record in the audit.

• annotation_column – fresh png_list column to receive the calls.

spacr.hit_attribution.quantify_candidate_enrichment(scored: pandas.DataFrame, *, target_column: str = 'target_well', bootstrap_iterations: int = 1000, permutation_iterations: int = 1000, random_seed: int = 0) → Tuple[pandas.DataFrame, Dict[str, Any]]

Quantify candidate prevalence at the well experimental unit.

Parameters:

scored – cell-level frame containing cross-fitted candidate probabilities and well identifiers.

spacr.hit_attribution.quantify_hit_enrichment(wells: pandas.DataFrame, *, random_seed: int = 0, n_bootstrap: int = 1000, n_permutations: int = 1000) → Dict[str, Any]

Per-well enrichment, well bootstrap CI, and a within-plate null.

Parameters:

wells – well-level frame containing target-guide fractions, hit-like prevalence, and mean hit-like probabilities.

spacr.hit_attribution.revert_promotion(db_path: str, promotion_id: str) → int

Restore exactly the values replaced by promote_calls().

Reverting something that was never promoted does nothing and returns 0 – including on a database where nothing has ever been promoted. The audit table is created by promote_calls(); when it does not exist yet, this function returns 0 instead of raising sqlite3.OperationalError.

Parameters:

• db_path – path to the SQLite measurements database to update.

• promotion_id – identifier returned by promote_calls().

spacr.hit_attribution.store_attribution(db_path: str, result: HitInvestigationResult) → int

Store the GUI investigation bundle under its immutable run context.

Parameters:

• db_path – path to the existing SQLite measurements database.

• result – investigation bundle to persist.

spacr.hit_attribution.undo_hit_promotion(db_path: str, promotion_id: str) → int

Clear values written by one promotion; preserve the audit record.

Parameters:

• db_path – path to the SQLite measurements database to update.

• promotion_id – identifier returned by promote_hit_calls().

spacr.hit_attribution.write_hit_attribution(db_path: str, result: HitAttributionResult, *, run_id: str | None = None) → str

Persist a versioned attribution without touching annotation columns.

Parameters:

• db_path – path to the existing SQLite measurements database.

• result – attribution result whose run metadata and cell scores will be stored.