spacr.organelle_types

One choice a biologist recognises, in front of fifty-three they do not.

organelle is the most over-configured object class in spaCR: 53 settings reach the mask pipeline, and a user who knows they are imaging lysosomes has to know what a ridge filter is, which of organelle_method’s seven values are legal for which morphology, and what organelle_network_threshold does when they are not segmenting a network.

WHAT THIS IS NOT. It is not a taxonomy compiled into a pipeline. The nine cell-biology categories do not map one-to-one onto the four organelle_morphology values:

‘spots’ punctate (vesicles, lipid droplets) ‘network’ filamentous (mitochondria, ER tubules) ‘irregular’ solid blobby (Golgi, lysosomes) ‘ring’ hollow (endosomes, autophagosomes)

“Vesicular” is a CELL-BIOLOGY category – a membrane-bound compartment that carries cargo – and spots/ring/network/irregular is an IMAGE-APPEARANCE category: what the segmentation has to find. They do not nest, because the same biological family looks different at different sizes. A 200 nm transport vesicle is a diffraction-limited dot. A 2 um vacuole is a visible ring. Both are Vesicular.

So the mapping is not type -> morphology. It is

(type, expected size) -> morphology

and hard-coding one morphology per type would be wrong for half the entries in the request’s own list, silently: the user picks Vesicular, gets a spot detector, and their lysosomes come out as rings of holes.

WHAT THIS IS. A named PRESET that sets several settings at once and says what it set and why. Choosing a type fills the advanced settings with recommended values and leaves every one of them editable. Nothing here overrides a value the user chose; preset_for() returns a recommendation and apply_preset() fills only what the user has not set.

Classes

OrganelleType

One named preset: what it is, what it looks like, what to run.

Functions

active_organelle_roles(→ Tuple[str, ...])	The slots settings currently has, in slot order.
apply_preset(→ Dict[str, object])	Fill unset organelle settings from the selected preset.
declared_organelle_roles(→ Tuple[str, ...])	Every slot settings has to keep values for, in slot order.
is_basic(→ bool)	True when setting belongs in the plain Organelle category.
known_types(→ Tuple[str, ...])	Every organelle_type, in the order the picker shows them.
method_guidance(→ str)	What method suits, as one sentence a picker can show.
morphologies_for_method(→ Tuple[str, ...])	The shapes method is a legal detector for.
organelle_count(→ int)	How many slots settings asks for, clamped to what can exist.
organelle_number(→ int)	The one-based slot number a role prefix stands for.
organelle_role(→ str)	The key prefix owned by slot number, counting from one.
organelle_role_of(→ Optional[str])	Which slot a settings key belongs to, or None.
organelle_roles(→ Tuple[str, ...])	The prefixes of the first count slots, in slot order.
organelle_slot_is_active(→ bool)	Whether key's slot is one of the ones this run has.
organelle_slot_label(→ str)	What the user calls a slot: Organelle 1, Organelle 2, ...
preset_for(→ Dict[str, object])	What this type RECOMMENDS. It does not apply anything.
primary_setting(→ str)	The primary organelle_* spelling of one slot's key.
resolve_type(→ OrganelleType)	The preset called name.
slot_setting(→ str)	One slot's spelling of a primary organelle_* key.

Module Contents

class spacr.organelle_types.OrganelleType

One named preset: what it is, what it looks like, what to run.

Parameters:

• label – what the user picks.

• members – the structures included under this name. Kept verbatim so the list a biologist recognises is the list they see.

• morphology – the organelle_morphology this maps to, or None when SIZE DECIDES – see size_split.

• size_split – (small_morphology, large_morphology), used when morphology is None. The split point is RING_RESOLVABLE_PX.

• method – the recommended organelle_method, which must be legal for the resulting morphology.

• params – further recommended settings.

• caveat – what is honestly weak about this preset. Shown to the user rather than hidden, because a preset that quietly does something adjacent to what its name says is worse than one that admits it.

morphology_for(diameter_px: float | None) → str | None

The morphology this type implies at diameter_px.

Parameters:

diameter_px – the expected object diameter in pixels, or None. Only used by size-split types: at or above RING_RESOLVABLE_PX (15) gives the large morphology, below it or None the small one.

Returns:

one of the four morphologies, or None for custom, which deliberately recommends nothing.

spacr.organelle_types.active_organelle_roles(settings: Mapping[str, object]) → Tuple[str, ...]

The slots settings currently has, in slot order.

What a panel shows. A slot outside this tuple is HIDDEN, not gone: its keys are still typed, still in the settings dict and still written back out, which is what makes lowering the number reversible.

Parameters:

settings – a run settings mapping; its slot count is read as in organelle_count().

spacr.organelle_types.apply_preset(settings: Mapping[str, object], *, explain: bool = False) → Dict[str, object]

Fill unset organelle settings from the selected preset.

Parameters:

• settings (mapping) – Run settings containing organelle_type and, when relevant, organelle_diameter. The input mapping is not modified.

• explain (bool, default=False) – Print the selected morphology, values filled by the preset, values retained from settings, and any preset caveat.

Returns:

dict – Copy of settings with missing or None preset keys filled. Existing non-None values are preserved so users can adjust the recommended method or thresholds.

Raises:

ValueError – If organelle_type does not name a known preset.

spacr.organelle_types.declared_organelle_roles(settings: Mapping[str, object]) → Tuple[str, ...]

Every slot settings has to keep values for, in slot order.

The active slots, PLUS any further slot the mapping already carries a key for. That union is the whole of “lowering it hides them and keeps their values”: a file written at seven and opened at two declares seven, so the defaults machinery leaves slots three to seven exactly as it found them instead of dropping them on the way back out.

Parameters:

settings – a run settings mapping; its slot count and the slot prefixes of its keys are both read.

spacr.organelle_types.is_basic(setting: str) → bool

True when setting belongs in the plain Organelle category.

Parameters:

setting – a settings key, compared as a string against BASIC_SETTINGS.

spacr.organelle_types.known_types() → Tuple[str, ...]

Every organelle_type, in the order the picker shows them.

spacr.organelle_types.method_guidance(method: str) → str

What method suits, as one sentence a picker can show.

Parameters:

method – an organelle_method value.

Returns:

an English sentence naming the shapes the method is legal for, or a sentence saying it belongs to no morphology. Not translated: a caller showing it passes it through tr.

spacr.organelle_types.morphologies_for_method(method: str) → Tuple[str, ...]

The shapes method is a legal detector for.

Read out of LEGAL_METHODS, so this answer and the validator’s cannot come apart.

Parameters:

method – an organelle_method value.

Returns:

the morphology names, in LEGAL_METHODS order; empty for a method no morphology allows.

spacr.organelle_types.organelle_count(settings: Mapping[str, object]) → int

How many slots settings asks for, clamped to what can exist.

Parameters:

settings – a run settings mapping. A missing, blank or unparseable value means DEFAULT_NUMBER_OF_ORGANELLES – a settings file written before the count existed is not making a claim about it, and refusing to open one over a typo in a number would lose the whole file.

Returns:

an integer in 0..MAX_ORGANELLES.

spacr.organelle_types.organelle_number(role: str) → int

The one-based slot number a role prefix stands for.

Parameters:

role – 'organelle', 'organelleb', …

Raises:

ValueError – for anything that is not a slot prefix.

spacr.organelle_types.organelle_role(number: int) → str

The key prefix owned by slot number, counting from one.

Parameters:

number – the slot as the user counts it – 1 is Organelle 1.

Returns:

'organelle' for slot 1, 'organelle<letter>' for slots 2..26, and a CARRIED suffix from 27 up – organelleaa onward. This is the prefix every one of that slot’s settings carries.

Raises:

ValueError – outside 1..MAX_ORGANELLES, naming the bound.

SLOTS 1..26 ARE BYTE-IDENTICAL to what they have always been, which is how the arbitrary count is reached without migrating anything: no measurement database, settings CSV or run journal moves, because none of the names they contain change.

organellea IS NEVER MINTED – slot 1 is the bare word – so a single-letter suffix can never be confused with the first letter of a carried one, and _ROLE_MATCH (longest first) does the rest.

spacr.organelle_types.organelle_role_of(key: str) → str | None

Which slot a settings key belongs to, or None.

Parameters:

key – any settings key. 'organelle_channel' belongs to slot 1 and 'organelleb_channel' to slot 2; 'summarize_organelles_by' and 'number_of_organelles' belong to no slot, because they are decisions about the organelles collectively rather than settings OF one.

spacr.organelle_types.organelle_roles(count: int = MAX_ORGANELLES) → Tuple[str, ...]

The prefixes of the first count slots, in slot order.

Parameters:

count – how many slots. Zero is legal and means a run with no organelle at all – most runs – and returns an empty tuple.

Raises:

ValueError – for a count above MAX_ORGANELLES. Silently clamping would let a settings file ask for thirty slots and get twenty-six without being told which of its keys stopped existing; organelle_count() is where a value read from a file is clamped, and it says so.

spacr.organelle_types.organelle_slot_is_active(key: str, settings: Mapping[str, object]) → bool

Whether key’s slot is one of the ones this run has.

True for every key that belongs to no slot, so a caller can use it as a filter over a whole settings dict without having to know which keys are organelle settings.

Parameters:

• key – any settings key; a key belonging to no slot counts as active.

• settings – the run settings mapping whose slot count decides which slots are active.

spacr.organelle_types.organelle_slot_label(role: str) → str

What the user calls a slot: Organelle 1, Organelle 2, …

Parameters:

role – a slot prefix such as 'organelle' or 'organelleb'; anything else raises ValueError.

spacr.organelle_types.preset_for(name: str | None, diameter_px: float | None = None) → Dict[str, object]

What this type RECOMMENDS. It does not apply anything.

Parameters:

• name – organelle type name resolved by resolve_type(); blank or custom yields no recommended settings, while an unknown name raises instead of silently changing the segmentation.

• diameter_px – the value of organelle_diameter. It is half the mapping: the same type is a dot at one size and a ring at another.

Returns:

settings to their recommended values, empty for ‘custom’.

spacr.organelle_types.primary_setting(key: str) → str

The primary organelle_* spelling of one slot’s key.

The inverse of slot_setting(). A key belonging to no slot is returned unchanged, so a caller can run a whole settings dict through it.

Parameters:

key – any settings key, e.g. 'organelleb_channel', which becomes 'organelle_channel'.

spacr.organelle_types.resolve_type(name: str | None) → OrganelleType

The preset called name.

Parameters:

name – the preset name, matched case-insensitively after stripping whitespace; None or empty means DEFAULT_TYPE (custom).

Raises:

ValueError – for an unknown name, listing the known ones. Falling back to ‘custom’ would mean a typo silently segmented with different settings than the user asked for.

spacr.organelle_types.slot_setting(key: str, role: str) → str

One slot’s spelling of a primary organelle_* key.

Parameters:

• key – a primary key, e.g. 'organelle_diameter'.

• role – the prefix to translate it into. Any object’s prefix is accepted, not only a slot’s: the same translation answers “what is this decision called for the pathogen”, and the settings tables use it that way. What is checked is the KEY, because translating something that is not a primary organelle setting produces a key no reader has ever heard of.

Raises:

ValueError – if key is not a primary organelle setting.