spacr.well_scope

Select object populations for cell-table visualizations.

Plots can show objects assigned to selected guides, those objects together with other objects from the same wells, or the complete table. The well set is derived from the guide selection and can then be restricted explicitly.

Functions

describe(→ str)	Format a concise description of the plotted population.
select(, wells, Dict[str, Any]])	Select the object population requested by a plot.
wells_of(→ List[str])	Return wells containing the selected guides in table order.

Module Contents

spacr.well_scope.describe(report: Dict[str, Any]) → str

Format a concise description of the plotted population.

Parameters:

report – well-scope selection report to summarize.

spacr.well_scope.select(frame: pandas.DataFrame, *, scope: str = 'guides', guides: Sequence[str] = (), wells: Sequence[str] | None = None) → Tuple[pandas.DataFrame, Dict[str, Any]]

Select the object population requested by a plot.

Parameters:

• frame (pandas.DataFrame) – Object table containing guide and well identifiers.

• scope ({"guides", "wells", "all"}, default="guides") – Population to retain.

• guides (sequence of str, optional) – Selected guide identifiers.

• wells (sequence of str, optional) – Explicit well subset for scope="wells". When omitted, wells are derived from guides.

Returns:

• pandas.DataFrame – Selected rows. The well scope adds MATE_COLUMN to distinguish selected-guide objects from their well-mates.

• dict – Scope, selections, row counts, and any explanatory note.

Raises:

ValueError – If scope is not supported.

spacr.well_scope.wells_of(frame: pandas.DataFrame, guides: Sequence[str]) → List[str]

Return wells containing the selected guides in table order.

Parameters:

• frame (pandas.DataFrame) – Object table containing guide and well identifiers.

• guides (sequence of str) – Guide identifiers selected for display.

Returns:

list of str – Unique well identifiers in their first-occurrence order. An empty list is returned when required columns or guide selections are absent.