spacr.attribution_columns

Persist model-based guide attributions in png_list on explicit request.

The pooled design does not observe which guide each individual cell carries. These columns therefore store inferred attributions, their probabilities, and coverage diagnostics rather than genotypes. A database note records that interpretation beside the values. The module is GUI-independent and requires the caller to confirm every write.

Exceptions

AttributionWriteError

Raised when an attribution write cannot be completed safely.

Functions

describe(→ str)	Summarize a proposed attribution write for user confirmation.
rows_from(→ list)	Convert guide-attribution results into database records.
write(→ Dict[str, int])	Write model-based cell attributions to a png_list table.

Module Contents

exception spacr.attribution_columns.AttributionWriteError

Bases: RuntimeError

Raised when an attribution write cannot be completed safely.

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

spacr.attribution_columns.describe(rows: Sequence[Mapping]) → str

Summarize a proposed attribution write for user confirmation.

Parameters:

rows – proposed per-cell attribution rows.

spacr.attribution_columns.rows_from(attributions, keys, *, genes=None, coverage: float | None = None) → list

Convert guide-attribution results into database records.

Parameters:

• attributions (iterable) – One attribution per cell, in the same order as keys.

• keys (iterable) – Per-object database keys.

• genes (mapping, optional) – Guide-to-gene mapping. Without one, the guide prefix is used.

• coverage (float, optional) – Fraction of well reads covered by attributed guides. The well-level value is repeated per cell so it remains available after filtering.

Returns:

list of dict – Records ready for write().

spacr.attribution_columns.write(db_path: str, rows: Iterable[Mapping], *, key_column: str = 'prcfo', confirmed: bool = False) → Dict[str, int]

Write model-based cell attributions to a png_list table.

Parameters:

• db_path (str) – Measurement database containing png_list.

• rows (iterable of mappings) – Records carrying key_column and any fields in COLUMNS.

• key_column (str, default='prcfo') – Column used to match records to png_list. file_name supports databases created before the per-object prcfo key was available.

• confirmed (bool, default=False) – Must be True. The function refuses automatic or implicit writes.

Returns:

dict – Counts of matched rows and newly added columns.

Raises:

AttributionWriteError – If confirmation is absent, png_list is missing, or the match key is unavailable.