spacr.read_background

Measure and correct guide-read background using control wells.

Control wells with known guide composition provide direct observations of reads assigned to guides that should be absent. Background is estimated per guide because barcode-specific effects can differ substantially. The module also separates two operations with different interpretations:

• exclusion removes sequences that cannot be present in cells, such as primer or plasmid carry-over, before fractions are calculated;

• background subtraction removes an estimated spurious component from a real guide and then optionally renormalizes the remaining fractions.

Control-well measurements provide an upper bound for ordinary wells when cross-sample contamination scales with source abundance. Candidate outliers are reported for imaging-based review rather than automatically classified as sequencing artefacts.

Functions

background_from_controls(→ Dict[str, object])	Measure each guide's fraction where it should be absent.
drop_guides(→ Dict[str, float])	Remove excluded sequences from a guide-fraction mapping.
resolve_exclusions(→ Set[str])	Resolve guide and gene exclusions to guide identifiers.
subtract_background(→ Dict[str, float])	Subtract guide-specific background from one well.
suggest_threshold(→ Dict[str, float])	Estimate a global fraction threshold from diffuse background.
suspicious(→ List[Dict[str, object]])	Return guides with high, recurrent control-well background.
unmatched_exclusions(→ List[str])	Return exclusion entries that match no guide in the screen.

Module Contents

spacr.read_background.background_from_controls(fractions: Mapping[str, Mapping[str, float]], intended: Mapping[str, Iterable[str]], *, exclude: Iterable[str] | None = None, statistic: str = 'median') → Dict[str, object]

Measure each guide’s fraction where it should be absent.

Parameters:

• fractions (mapping) – Nested mapping {well: {guide: fraction}} for control wells.

• intended (mapping) – Guides known to be present in each well. Wells missing from this mapping are skipped rather than treated as empty.

• exclude (iterable of str, optional) – Sequences to remove and renormalize before measuring background.

• statistic ({'median', 'mean'}, default='median') – Summary applied across eligible control wells for each guide.

Returns:

dict – Per-guide background, occurrence counts, per-well spurious mass, aggregate mass statistics, and the number of controls used.

spacr.read_background.drop_guides(fractions: Mapping[str, float], exclude: Iterable[str], *, renormalise: bool = True) → Dict[str, float]

Remove excluded sequences from a guide-fraction mapping.

Parameters:

• fractions (mapping of str to float) – Guide fractions for one well.

• exclude (iterable of str) – Guide or gene identifiers to remove.

• renormalise (bool, default=True) – Rescale retained finite fractions to sum to one when their total is positive.

Returns:

dict – Retained guide fractions. Exclusion is applied before downstream background correction so removed sequences do not remain in the denominator.

spacr.read_background.resolve_exclusions(exclude: Iterable[str] | None, guides: Sequence[str], genes: Sequence[str] | None = None) → Set[str]

Resolve guide and gene exclusions to guide identifiers.

Parameters:

• exclude – guide or gene identifiers requested for exclusion, or None.

• guides – available guide identifiers, aligned with genes when provided.

Gene names select every associated guide. Matching uses the same organism-prefix handling as the control settings. If the shared resolver cannot run, exact guide-name matches are returned as a conservative fallback; unmatched inputs are omitted and can be reported with unmatched_exclusions().

spacr.read_background.subtract_background(fractions: Mapping[str, float], background: Mapping[str, float], *, scale: float = 1.0, renormalise: bool = True) → Dict[str, float]

Subtract guide-specific background from one well.

Parameters:

• fractions – guide-fraction mapping for one well.

• background – guide-specific, control-derived background fractions.

scale multiplies the control-derived background before subtraction; values are clipped at zero. When renormalise is true, corrected values are rescaled to preserve the original finite total. Use a scale below one when control-well abundance is known to overstate contamination in ordinary wells.

spacr.read_background.suggest_threshold(measurement: Mapping[str, object], *, quantile: float = 0.99, outlier_factor: float = 20.0) → Dict[str, float]

Estimate a global fraction threshold from diffuse background.

Parameters:

measurement – background summary returned by background_from_controls().

Guides at least outlier_factor times the median are excluded from the quantile calculation and counted separately because a single threshold does not describe them. The result reports the threshold, sample counts, and the number of guides that require guide-specific review or correction.

spacr.read_background.suspicious(measurement: Mapping[str, object], *, factor: float = 20.0, everywhere: float = 0.9) → List[Dict[str, object]]

Return guides with high, recurrent control-well background.

Parameters:

measurement – background summary returned by background_from_controls().

Candidates must reach factor times the median background and appear in at least everywhere of eligible control wells. Results are sorted by decreasing background. Read counts alone cannot distinguish a sequencing artefact from a genuinely over-represented guide, so the returned verdict explicitly recommends imaging-based review.

spacr.read_background.unmatched_exclusions(exclude: Iterable[str] | None, guides: Sequence[str], genes: Sequence[str] | None = None) → List[str]

Return exclusion entries that match no guide in the screen.

Parameters:

• exclude – guide or gene identifiers requested for exclusion, or None.

• guides – available guide identifiers, aligned with genes when provided.