spacr.control_names

Resolve user-entered controls as gene or guide identifiers.

Controls may be bare genes (000000), bare guides (000000_1), prefixed genes (TGGT1_000000), or prefixed guides (TGGT1_000000_1). A leading token is treated as an organism or strain prefix only when it occurs in the configured share of distinct library identifiers. Matching uses complete identifiers rather than substrings.

Exceptions

ControlNotFound

Raised when a named control does not match any screen row.

Classes

ControlSpec

Resolved interpretation of a user-entered control.

Functions

common_prefix(→ str)

Return a leading token shared by enough distinct identifiers.

matches(spec, guides[, genes])

Return a Boolean mask for rows covered by a resolved control.

resolve_control(→ Optional[ControlSpec])

Read one typed control as a gene or as a guide.

resolve_controls(→ Tuple[ControlSpec, ...])

Resolve a sequence containing any mixture of genes and guides.

rows_for(typed, guides[, genes, names, prefix, ...])

Resolve a typed control and select the matching screen rows.

Module Contents

exception spacr.control_names.ControlNotFound[source]

Bases: ValueError

Raised when a named control does not match any screen row.

An empty control selection would invalidate normalization, reference baselines, and volcano annotations. rows_for() raises this exception when strict=True so callers can stop before computing those results.

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

class spacr.control_names.ControlSpec[source]

Resolved interpretation of a user-entered control.

Parameters:

  • typed – original trimmed nonblank identifier supplied by the user, retained for diagnostics and prefix-retry logic.

  • level – resolved identifier level, GENE or GUIDE, which selects gene-wide versus exact-guide matching.

  • value – normalized gene or guide identifier used for matching after any recognized organism prefix is removed.

  • prefix – inferred or explicit organism or strain token without the separator, retained so prefixed and unprefixed stored names both match; empty when none is known.

note(matched_guides: int = -1, matched_wells: int = -1) → str[source]

Return a console summary of the resolution and optional matches.

property is_gene: bool[source]

Return whether this specification selects every guide for a gene.

spacr.control_names.common_prefix(names: Iterable[str], share: float = COMMON_PREFIX_SHARE) → str[source]

Return a leading token shared by enough distinct identifiers.

Parameters:

  • names (iterable of str) – Guide identifiers in the loaded data.

  • share (float, default=COMMON_PREFIX_SHARE) – Required fraction of distinct identifiers carrying the token.

Returns:

str – Token without its separator, or an empty string when none reaches share.

spacr.control_names.matches(spec: ControlSpec | None, guides, genes=None)[source]

Return a Boolean mask for rows covered by a resolved control.

Parameters:

  • spec (ControlSpec or None) – Control to match. None matches no rows.

  • guides (array-like) – Guide identifier for each row.

  • genes (array-like, optional) – Gene identifier for each row. If omitted, gene membership is inferred from complete guide prefixes such as 000000_1.

Returns:

pandas.Series – Boolean mask aligned to guides.

spacr.control_names.resolve_control(typed, names: Iterable[str] | None = None, prefix: str | None = None) → ControlSpec | None[source]

Read one typed control as a gene or as a guide.

Parameters:

  • typed (Any) – Entered identifier. Blank values return None.

  • names (iterable of str, optional) – Library guide identifiers used to infer a common prefix.

  • prefix (str, optional) – Previously inferred prefix. When supplied, names is ignored.

Returns:

ControlSpec or None – Resolved gene or guide identifier, or None for no control.

spacr.control_names.resolve_controls(typed: Sequence | None, names: Iterable[str] | None = None, prefix: str | None = None) → Tuple[ControlSpec, ...][source]

Resolve a sequence containing any mixture of genes and guides.

Parameters:

typed – user-entered control identifiers; None means no controls.

The common prefix is measured once and applied independently to each nonblank entry.

spacr.control_names.rows_for(typed, guides, genes=None, *, names=None, prefix=None, strict: bool = False, label: str = 'control')[source]

Resolve a typed control and select the matching screen rows.

Guide controls use exact matches. Gene controls select every guide assigned to the gene. When the data omits an organism prefix that is present in the typed control, the prefix is removed before retrying the same whole-value match.

Parameters:

  • typed (object) – Control name or value accepted by resolve_control().

  • guides (array-like) – Guide names for the screen rows.

  • genes (array-like, optional) – Gene names aligned with guides. Guide prefixes are used when this column is unavailable.

  • names (iterable of str, optional) – Reference names used to distinguish organism prefixes from gene names.

  • prefix (str, optional) – Explicit organism prefix.

  • strict (bool, default=False) – Raise ControlNotFound when the control matches no rows.

  • label (str, default="control") – Name used in an error message when strict=True.

Returns:

tuple of pandas.Series and str – Boolean row mask and a concise description of the resolved control.

Raises:

ControlNotFound – If strict=True and no row matches the resolved control.