spacr.object_roles

Shared object-role vocabulary and role-aware settings helpers.

The schema defines membership in segmented, derived, child, and organelle roles. This module exposes those relationships to consumers that need labels, setting keys, table anchors, or join behavior. Consumers retain their own ordering where array planes, table layout, or crop modes require a specific sequence; the shared registry defines which names are valid and how their roles relate.

Functions

anchor_column(→ str)	The column in table that carries the cell it belongs to.
enabled_organelle_roles(→ Tuple[str, ...])	Organelle slots whose <role>_channel is enabled, in plane order.
is_one_row_per_cell(→ bool)	True when table holds one row per cell and needs no roll-up.
is_organelle(→ bool)	True when role is one of the closed organelle slots.
is_segmented(→ bool)	True when role is found in a channel rather than derived.
join_how(→ str)	Whether table keeps cells it has no rows for.
ordered(→ Tuple[str, ...])	Return roles as a tuple, checking each is a real object kind.
organelle_index(→ int)	Return the one-based user-facing index of an organelle slot.
organelle_label(→ str)	Human-readable label for a slot (Organelle 1, Organelle 2).
organelle_settings_view(→ Dict[str, Any])	Return a copy exposing one slot through the legacy organelle_* API.
role_setting(→ str)	Return the setting key for suffix in one segmented role.
setting_label(→ str)	Humanise a setting key, giving organelle slots numbered labels.
split_role_setting(key)	organellezz_min_area -> ("organellezz", "min_area").
withdrawn_setting_reason(key)	Why key is no longer read, or None if it is not withdrawn.

Module Contents

spacr.object_roles.anchor_column(table: str) → str

The column in table that carries the cell it belongs to.

Parameters:

table – an object table name.

Returns:

'object_label' or 'cell_id'.

Raises:

ValueError – for a table with no declared anchor, naming the ones that have. Guessing produces a join on a coincidence.

spacr.object_roles.enabled_organelle_roles(settings: Mapping[str, Any]) → Tuple[str, ...]

Organelle slots whose <role>_channel is enabled, in plane order.

Parameters:

settings – settings mapping carrying per-role channel assignments.

Returns:

Enabled organelle slots in schema and mask-plane order.

spacr.object_roles.is_one_row_per_cell(table: str) → bool

True when table holds one row per cell and needs no roll-up.

Parameters:

table – object-table name to classify.

Returns:

Whether the table needs no child-to-cell roll-up.

spacr.object_roles.is_organelle(role: str) → bool

True when role is one of the closed organelle slots.

Parameters:

role – object-role name to test.

Returns:

True only for roles in ORGANELLE_ROLES.

spacr.object_roles.is_segmented(role: str) → bool

True when role is found in a channel rather than derived.

Parameters:

role – object kind, e.g. "nucleus". Unknown names are False rather than an error, because callers use this to decide whether to look for a channel setting; an unknown kind has none.

Returns:

True only for roles in SEGMENTED_ROLES.

spacr.object_roles.join_how(table: str, *, keep_uninfected: bool = True) → str

Whether table keeps cells it has no rows for.

Parameters:

• table – an object table name.

• keep_uninfected – False restricts the analysis to cells that actually contain a pathogen (or organelle), turning those joins inner. It does not touch nucleus or png_list, which are inner regardless – a cell with no nucleus is not an uninfected cell, it is not a cell.

Returns:

'left' or 'inner', for pandas.DataFrame.merge().

spacr.object_roles.ordered(*roles: str) → Tuple[str, ...]

Return roles as a tuple, checking each is a real object kind.

For declaring a module’s own ORDER while still being told when a name is wrong. The point is that a module keeps its ordering – which may be a plane order or a table order and cannot be centralised – without also keeping its own private copy of what the names are.

Parameters:

roles – object kinds in this module’s required order.

Returns:

roles unchanged as a tuple.

Raises:

ValueError – if a name is not in ALL_ROLES, naming it and listing the valid kinds.

spacr.object_roles.organelle_index(role: str) → int

Return the one-based user-facing index of an organelle slot.

Parameters:

role – organelle role whose numeric slot is requested.

Returns:

The one-based slot encoded by role.

Raises:

ValueError – if role is not an organelle slot.

ANSWERED FROM THE LETTER, not from a list of the slots that happen to segment today. The suffix IS the number – organelle, organelleb, organellec – so a slot the schema has no mask plane for still has a name, and a settings file carrying seven slots renders as “Organelle 5” rather than as “Organellee”.

spacr.object_roles.organelle_label(role: str) → str

Human-readable label for a slot (Organelle 1, Organelle 2).

Parameters:

role – organelle role to render for users.

Returns:

The numbered user-facing organelle label.

Raises:

ValueError – if role is not an organelle slot.

spacr.object_roles.organelle_settings_view(settings: Mapping[str, Any], role: str) → Dict[str, Any]

Return a copy exposing one slot through the legacy organelle_* API.

Parameters:

• settings – complete settings mapping to adapt without mutating it.

• role – organelle slot to expose under legacy key names.

Returns:

A copied mapping exposing the selected slot through legacy organelle_* keys.

Raises:

ValueError – if role is not an organelle slot.

The classical organelle segmenter predates slots and reads roughly forty organelle_* keys. Keeping that well-tested implementation and adapting one settings view at its boundary prevents four copies of the algorithm.

spacr.object_roles.role_setting(role: str, suffix: str) → str

Return the setting key for suffix in one segmented role.

Parameters:

• role – segmented object role that owns the setting.

• suffix – role-relative setting suffix such as channel.

Returns:

The canonical <role>_<suffix> setting key.

Raises:

ValueError – if role is not segmented.

spacr.object_roles.setting_label(key: str) → str

Humanise a setting key, giving organelle slots numbered labels.

Parameters:

key – canonical setting key to turn into a display label.

Returns:

The canonical human-readable setting label.

spacr.object_roles.split_role_setting(key: str)

organellezz_min_area -> ("organellezz", "min_area").

The inverse of role_setting(), and the reason a suffix rename can cost six lines instead of 3,522. Every role is a single word with no underscore, so partitioning on the FIRST one separates the role from the suffix without scanning the 702 organelle slots.

NOT role_setting()’s validation: this accepts any role in ALL_ROLES, including cytoplasm, which is derived rather than segmented and still declares cytoplasm_min_size. Restricting to segmented roles here would silently skip it.

A BARE KEY IS NOT A ROLE KEY, and that matters: FT, CP_prob, Signal_to_noise and flow_threshold are all LIVE settings in their own right in the standalone apply/test-model submodules. A key with no underscore has no role, so it can never match a suffix rule.

Parameters:

key – a settings key.

Returns:

(role, suffix), or None when key names no role.

spacr.object_roles.withdrawn_setting_reason(key: str)

Why key is no longer read, or None if it is not withdrawn.

Parameters:

key – the key a settings file carries.

Returns:

a sentence naming what replaced it, or None.