spacr.settings

Defaults, types, categories, descriptions, and validation for settings.

Classes

BarcodeEntry	One barcode type that a run decodes.
BarcodeSet	The barcode types a run decodes, in order.

Functions

advanced_object_of(key)	Which object a family member belongs to, or None.
barcode_set_from_settings(settings)	Return the barcode set a Map Barcodes run was configured with.
bundled_barcode_path(kind)	Return the installed CSV path for a bundled barcode reference.
canonical_feature_selection(value)	Return channel_of_interest in the one form spaCR stores.
cellpose_live_model_menu([block, refresh])	cellpose_model_menu() without the retired pre-SAM spellings.
cellpose_model_choices([block, refresh])	Every Cellpose model on this machine, read from the Cellpose API.
cellpose_model_menu([block, refresh])	cellpose_model_choices() plus the legacy spellings.
check_settings(vars_dict, expected_types[, q])	Validate and coerce GUI-collected settings against expected types.
deep_spacr_defaults(settings)	Populate default settings for the end-to-end deep_spacr training pipeline.
default_settings_analyze_percent_positive(settings)	Populate default settings for the "percent positive" per-well analysis.
defaults_for(app_key[, settings])	The registered defaults dict for app_key.
downloaded_zoo_models()	Paths of model-zoo Cellpose checkpoints already on this machine.
explain_organelle_measurements(settings)	Print the caveats above, in the voice the type preset already uses.
get_analyze_plaque_settings(settings)	Populate default settings for plaque analysis.
get_analyze_reads_default_settings(settings)	Populate default settings for analyzing FASTQ read barcodes.
get_analyze_recruitment_default_settings(settings)	Populate default settings for the recruitment-analysis pipeline.
get_automated_motility_assay_default_settings(settings)	Return default settings for the automated motility assay pipeline.
get_check_cellpose_models_default_settings(settings)	Populate default settings for the "check Cellpose models" utility.
get_default_apply_cellpose_model_settings(settings)	Populate default settings for applying a Cellpose model to a dataset.
get_default_generate_activation_map_settings(settings)	Populate default settings for generating model activation/CAM maps.
get_default_test_cellpose_model_settings(settings)	Populate default settings for testing a Cellpose model on a dataset.
get_identify_masks_finetune_default_settings(settings)	Populate default settings for fine-tuning mask identification.
get_map_barcodes_default_settings(settings)	Populate default settings for mapping barcodes to gRNAs and plates.
get_measure_crop_settings([settings])	Return the default settings for the measure-and-crop pipeline.
get_perform_regression_default_settings(settings)	Populate default settings for gRNA/score regression analysis.
get_plot_data_from_csv_default_settings(settings)	Populate default settings for plotting data pulled from a CSV file.
get_setting_dependencies()	Return reviewed rules for settings that currently have no effect.
get_timelapse_settings([settings])	Return default settings for the standalone Timelapse module.
get_train_cellpose_default_settings(settings)	Populate default settings for training a Cellpose model.
get_train_test_model_settings(settings)	Populate default settings for the train/test classifier settings dict.
has_registered_defaults(app_key)	Whether a module registered a defaults factory for app_key.
normalize_cellpose_model_name(value[, object_type, key])	Map a stored Cellpose model setting forward onto what Cellpose 4 has.
organelle_counting_is_meaningful(organelle_type)	Whether count-dependent measurements mean anything for a type.
organelle_measurement_caveats(settings)	What a measure run should say about its own organelle numbers.
organelle_slots_beyond_the_count(settings[, count])	Populate declarable organelle slots without changing the active count.
parse_list(value)	Parse a string literal into a homogeneous list of scalars.
register_defaults(app_key, fn, *[, replace, ...])	Register the defaults factory for app_key.
registered_default_apps()	Every app key with registered defaults, in registration order.
set_analyze_class_proportion_defaults(settings)	Populate default settings for class-proportion analysis across conditions.
set_analyze_endodyogeny_defaults(settings)	Populate default settings for endodyogeny (parasite division) analysis.
set_analyze_invasion_defaults(settings)	Populate default settings for the two-colour (red/green) invasion assay.
set_analyze_replication_defaults(settings)	Populate defaults for the parasites-per-vacuole replication assay.
set_annotate_default_settings(settings)	Populate default settings for the image annotation UI.
set_default_analyze_screen(settings)	Populate default settings for screen analysis (ML-based scoring).
set_default_classify(settings)	Populate defaults for the merged Classify module.
set_default_general([settings])	Return default settings for the general organize/stitch/multichannel run.
set_default_generate_barecode_mapping([settings])	Return default settings for the barcode-mapping pipeline.
set_default_multichannel([settings])	Return default settings for building multichannel per-well mosaics.
set_default_plot_data_from_db(settings)	Populate default settings for plotting data pulled from a measurements DB.
set_default_plot_merge_settings()	Return the default settings dict for plotting merged mask overlays.
set_default_settings_preprocess_generate_masks([settings])	Populate default settings for the preprocess/generate-masks pipeline.
set_default_settings_preprocess_img_data(settings)	Populate default settings for the image-preprocessing step.
set_default_stitch([settings])	Return default settings for the tile-stitching pipeline.
set_default_train_test_model(settings)	Populate default settings for the train/test classifier training pipeline.
set_default_umap_image_settings([settings])	Return the default settings for UMAP/tSNE image-embedding plots.
set_generate_dataset_defaults(settings)	Populate default settings for the generic dataset-generation step.
set_generate_training_dataset_defaults(settings)	Populate default settings for generating a labeled training dataset.
set_graph_importance_defaults(settings)	Populate default settings for the "graph importance" plot utility.
set_interpret_vision_model_defaults(settings)	Populate default settings for interpreting vision-model predictions.
surviving_setting_name(key)	What key is called TODAY, following renames to the end.
unregister_defaults(app_key)	Drop a registered defaults factory. True if there was one.

Module Contents

class spacr.settings.BarcodeEntry

One barcode type that a run decodes.

A run used to decode exactly three barcodes – a plate column, a guide and a plate row – because the regex, the settings and the read processors each spelled all three of them out by name. An entry is that same information written once, so that a screen carrying a fourth barcode, or only one, is a different collection of entries rather than a different code path.

Variables:

• name – the word a user would use for this barcode, such as column, row, grna or plate. It names the two output columns the run writes for the entry, so it has to be unique within a set.

• csv – the reference table that turns one of these sequences into a name. It needs a sequence column and a name column. Its sequences must be in the same orientation as the reads, because they are compared verbatim rather than reverse-complemented.

• group – the named group of the barcode regex whose captured text is this barcode. Left empty it is the entry’s own name, which is what a regex written for a new set will normally use.

• group_aliases – further spellings of that group name, accepted when the preferred one is absent from the regex. The column and row barcodes spaCR shipped accept the shorter column and row this way, which is why a pattern written before those names were settled still runs.

• sequence_column – the output column the extracted sequence is written to. Left empty it is the entry’s name followed by _sequence.

• id_column – the output column the resolved name is written to. Left empty it is the entry’s name followed by ID. The guide barcode spaCR shipped sets this to grna_name instead, because that is the header every count table already written and every reader of one expects.

accepted_groups()

Return every regex group name this barcode answers to.

Returns:

a tuple of group names, the preferred spelling first and any older accepted spellings after it.

group_in(names)

Return the spelling of this barcode’s group that a regex uses.

Parameters:

names – the group names a regex defines.

Returns:

the accepted group name the regex defines, or None when it defines none of them.

group_label()

Return this barcode’s accepted group names as one label.

Sorted rather than preferred first, because this label lands in the message a user reads when the regex is missing a group, and the message spaCR has always printed names the older spelling first.

Returns:

the accepted group names joined by slashes.

class spacr.settings.BarcodeSet

The barcode types a run decodes, in order.

A set replaces the three named reference settings the module started with. Iterating it is how the run reaches every barcode, so a run with one barcode and a run with ten differ only in what this holds.

The count columns can be set separately because the three barcodes spaCR shipped for years are counted by row, then column, then guide, while the reads list the column first. A set reproducing that run has to be able to say so, rather than quietly re-sort tables people already have.

Variables:

• entries – the barcode types, in the order the run lists them. Every entry adds a sequence column and a name column to each annotated read. Those columns come after the read, in the same order.

• count_columns – the name columns the per-well counts are grouped by, in the order they are grouped. Left empty it is every entry’s name column in entry order.

resolve_groups(regex)

Return the regex group each barcode is captured by.

A set of five barcodes needs five named groups, and the failure this answers is a regex that names four. That used to surface as a bare “no such group” from inside a worker process, several frames from anything a user configured, so the message here names the barcode that has no group and then lists the groups the regex does define.

Parameters:

regex – a compiled regular expression, or the pattern string of one.

Returns:

a dict from each barcode’s name to the group name the regex spells it with.

Raises:

ValueError – when the regex names no group for one or more of the barcodes in this set.

property id_columns

Return the output column each barcode’s resolved name lands in.

Returns:

a tuple of column names, in entry order.

property names

Return the name of each barcode, in entry order.

Returns:

a tuple of names.

property sequence_columns

Return the output column each barcode’s raw sequence lands in.

Returns:

a tuple of column names, in entry order.

spacr.settings.advanced_object_of(key)

Which object a family member belongs to, or None.

Both spellings are understood – cell_min_size and remove_background_cell – because the sub-heading a key is drawn under has to be the object it acts on whichever way round spaCR happens to name it.

Parameters:

key – a settings key.

Returns:

the object name from ADVANCED_OBJECT_ORDER, or None when the key names no object.

spacr.settings.barcode_set_from_settings(settings)

Return the barcode set a Map Barcodes run was configured with.

A settings file names its barcodes under barcode_set, as a list with one entry per barcode. An entry is a mapping of the fields of BarcodeEntry, or just a name when the reference table for that name is already in the settings. An entry that names no reference table takes the one under its own name followed by _csv, and failing that the reference of that name spaCR ships, so adding a fourth barcode to the three that ship is a one-entry addition rather than a re-declaration of all four.

An entry named after one of the three barcodes spaCR shipped keeps the spellings that barcode has always had, for every field the settings file does not spell out itself. That is what makes a set of those three the run they describe rather than a re-implementation of it: the same regex groups, the same output columns, and the same order of the count table. A barcode named anything else derives its spellings from its own name.

Parameters:

settings – a Map Barcodes settings mapping.

Returns:

the configured BarcodeSet, or None when the settings name no set. None is not an error and is the ordinary case: it means the run decodes the plate column, the guide and the plate row named by column_csv, grna_csv and row_csv, exactly as every run did before a set could be named at all.

Raises:

ValueError – when an entry is neither a name nor a mapping of entry fields, when a mapping carries a field no entry has, or when an entry names a reference table that cannot be resolved.

spacr.settings.bundled_barcode_path(kind)

Return the installed CSV path for a bundled barcode reference.

Parameters:

kind – 'column', 'grna' or 'row'.

Returns:

absolute path to the packaged CSV.

Raises:

ValueError – when kind is not a bundled reference type.

spacr.settings.canonical_feature_selection(value)

Return channel_of_interest in the one form spaCR stores.

None, an empty value and 'all' mean every feature. One channel is an integer, several channels are an order-preserving list, morphology is the literal 'morphology', and other strings are column-name filters. A one-member collection collapses to its member so the settings panel cannot turn channel 3 into a different results path named [3].

This function deliberately uses only the standard library. It runs while configuration widgets are collected, before the user starts a pipeline; importing numpy/torch/cv2 merely to normalise a combo-box answer made opening Classify allocate hundreds of megabytes.

Parameters:

value – scalar, string, or collection supplied by a settings widget, CSV, script or default.

Returns:

None, an integer, a string, or an order-preserving list.

Raises:

ValueError – when the value cannot name a feature selection.

spacr.settings.cellpose_live_model_menu(block=False, refresh=False)

cellpose_model_menu() without the retired pre-SAM spellings.

THE LIVE VIEW IS NOT A SETTINGS FILE. cellpose_model_menu keeps ‘cyto’, ‘cyto2’, ‘cyto3’ and ‘nuclei’ so a user whose SAVED settings name one can see their own value rather than have it silently replaced – that is a compatibility obligation and it is real.

A live preview has no such obligation: nothing is being loaded from disk, the user is choosing what to look at now. And all four resolve to cpsam, so offering them there is offering four labels for one model and inviting the question of which is better. The live view therefore exposes only the canonical model name.

Downloaded zoo checkpoints stay, because those ARE different models.

spacr.settings.cellpose_model_choices(block=False, refresh=False)

Every Cellpose model on this machine, read from the Cellpose API.

The list used to be a literal, which meant spaCR could be wrong in both directions: it offered models Cellpose 4 had removed, and it could not offer a checkpoint the user had registered.

Importing cellpose.models costs ~2.5 s — it pulls in torch — and this is called while a settings page is being built, so by default it reads the API only when Cellpose is already imported. This is the same bargain spacr.settings_spec._torchvision_model_names() strikes for the torchvision zoo, and for the same measured reason. By the time anything has segmented, Cellpose is loaded and the next dropdown built is live.

Parameters:

• block – import Cellpose if it is not loaded. For a caller that can afford the wait and wants the definitive answer.

• refresh – ignore the cache and ask again — for a caller that has just registered a model.

Returns:

a non-empty tuple, cpsam first. Never empty: a dropdown with nothing in it is worse than one that is out of date.

spacr.settings.cellpose_model_menu(block=False, refresh=False)

cellpose_model_choices() plus the legacy spellings.

What a dropdown offers, as opposed to what Cellpose has. The three pre-SAM names are not four choices — Cellpose resolves all of them to cpsam — but a user whose saved settings say cyto2 has to be able to see their own value in the combo rather than have it silently replaced the first time they open the panel.

Parameters:

• block – passed through to cellpose_model_choices() — import Cellpose (~2.5 s, it pulls in torch) instead of answering from the stock list when Cellpose is not loaded yet. Leave it off while a settings page is being built.

• refresh – passed through likewise — discard the cached answer and ask Cellpose again, for a caller that has just registered a model.

Returns:

the live choices followed by every legacy spelling not already among them, so the aliases are offered even with block off and the fallback list in play.

spacr.settings.check_settings(vars_dict, expected_types, q=None)

Validate and coerce GUI-collected settings against expected types.

Iterates the widget map produced by the settings panel, parses each raw string value into the type declared in expected_types (including tuple-typed “or None” fields, lists, dicts and lists-of-lists), and collects human-readable error messages instead of stopping at the first failure. Errors are also forwarded to q for GUI display.

Parameters:

• vars_dict – mapping key -> (label, widget, var, frame) from the settings panel.

• expected_types – mapping key -> type (or tuple of accepted types).

• q – optional queue used to surface error strings to the GUI. A private Queue is created if None.

Returns:

tuple (settings, errors) where settings is the parsed dict and errors is the list of collected error messages.

spacr.settings.deep_spacr_defaults(settings)

Populate default settings for the end-to-end deep_spacr training pipeline.

Covers dataset generation, model training/testing and applying the trained model to the dataset in a single settings dict.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.default_settings_analyze_percent_positive(settings)

Populate default settings for the “percent positive” per-well analysis.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.defaults_for(app_key, settings=None)

The registered defaults dict for app_key.

The read side of register_defaults(), and what a settings panel calls. Returns a fresh dict every time: the caller edits what it gets back, and a factory that hands out one shared dict would let one module’s screen edit another’s defaults.

Parameters:

• app_key – key some module passed to register_defaults(). Only that registry is consulted, so the set_default_* families defined below in this file are not reachable through it; the error lists the keys that are.

• settings – values to seed the factory with, exactly like the settings argument of every set_default_* in this file.

Raises:

• KeyError – when nothing is registered for app_key.

• TypeError – when the factory does not return a dict.

spacr.settings.downloaded_zoo_models()

Paths of model-zoo Cellpose checkpoints already on this machine.

The live preview builds its model from the combo value. Including local zoo checkpoints here keeps that preview aligned with a selected run model; otherwise it would silently render stock cpsam while the user tuned diameter and thresholds for a different checkpoint.

ONLY WHAT IS ALREADY DOWNLOADED. Listing a model that is not on disk would put an entry in a dropdown that cannot be selected without a 1.2 GB download starting from a combo box, which is not where anyone expects to begin one. The picker is where downloading happens; this is where the result of having done it shows up.

Never raises and never blocks on the network – true again as of 2026-09-05, and it was not for a while: the remote=True below reaches the community catalogue, which was fetched synchronously. See the comment on that call for what it cost.

Returns:

a tuple of filesystem paths, newest catalogue order.

spacr.settings.explain_organelle_measurements(settings)

Print the caveats above, in the voice the type preset already uses.

Silent when there is nothing to say, so a run measuring punctate organelles is not given a paragraph telling it everything is fine.

Parameters:

settings – a measure settings dict.

Returns:

the caveats, so a caller can show them somewhere other than the console.

spacr.settings.get_analyze_plaque_settings(settings)

Populate default settings for plaque analysis.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_analyze_reads_default_settings(settings)

Populate default settings for analyzing FASTQ read barcodes.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_analyze_recruitment_default_settings(settings)

Populate default settings for the recruitment-analysis pipeline.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_automated_motility_assay_default_settings(settings)

Return default settings for the automated motility assay pipeline.

Combines array/filter parameters, XGBoost infection classifier settings, and PCA/UMAP/t-SNE embedding options into a single settings dict.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied.

spacr.settings.get_check_cellpose_models_default_settings(settings)

Populate default settings for the “check Cellpose models” utility.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_default_apply_cellpose_model_settings(settings)

Populate default settings for applying a Cellpose model to a dataset.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_default_generate_activation_map_settings(settings)

Populate default settings for generating model activation/CAM maps.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_default_test_cellpose_model_settings(settings)

Populate default settings for testing a Cellpose model on a dataset.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_identify_masks_finetune_default_settings(settings)

Populate default settings for fine-tuning mask identification.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_map_barcodes_default_settings(settings)

Populate default settings for mapping barcodes to gRNAs and plates.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_measure_crop_settings(settings=None)

Return the default settings for the measure-and-crop pipeline.

Enables test mode / plotting automatically when test_mode is True.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied.

spacr.settings.get_perform_regression_default_settings(settings)

Populate default settings for gRNA/score regression analysis.

Switches agg_type to None automatically when quantile regression is selected, so alpha is treated as the quantile.

Every key spacr.ml.perform_regression() reads with settings[...] is filled here. Six were not, and because both dispatchers (the Qt panel via qt.screens.settings_model.resolve_default_settings and spacr-run regression via cli.module_defaults) build the dict from this one function, regression could not be started from any entry point: it died on KeyError: 'verbose' at ml.py:1409, after both input CSVs had been read and settings/regression.csv had been written, so the failure looked like a run that had started cleanly.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_plot_data_from_csv_default_settings(settings)

Populate default settings for plotting data pulled from a CSV file.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_setting_dependencies()

Return reviewed rules for settings that currently have no effect.

Estimator rules are generated from ml.REGRESSION_SETTINGS_USED – the same inventory that rejects unused knobs at run time – so the GUI cannot drift into enabling a setting the selected backend refuses.

spacr.settings.get_timelapse_settings(settings=None)

Return default settings for the standalone Timelapse module.

The Timelapse module is mask generation run over a time series: the same preprocessing + Cellpose segmentation as the Mask module, followed by frame-to-frame linking of the objects named in timelapse_objects and per-channel movie export. It therefore takes the full set_default_settings_preprocess_generate_masks dict with timelapse forced on — the flag is what the module is, not something to configure.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied and timelapse True.

spacr.settings.get_train_cellpose_default_settings(settings)

Populate default settings for training a Cellpose model.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.get_train_test_model_settings(settings)

Populate default settings for the train/test classifier settings dict.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.has_registered_defaults(app_key)

Whether a module registered a defaults factory for app_key.

Parameters:

app_key – key to look up, coerced with str() as register_defaults() stored it. This registry holds only what registers itself, so the built-in set_default_* families in this file answer False — they are reached through the GUI dispatch instead. True only promises a factory is there, not that it works: defaults_for() still has to run it.

spacr.settings.normalize_cellpose_model_name(value, object_type=None, key=None)

Map a stored Cellpose model setting forward onto what Cellpose 4 has.

Cellpose 4 ships exactly one stock model, cpsam (cellpose.models.MODEL_NAMES == ['cpsam']), and CellposeModel(model_type=...) is accepted-and-ignored. So ‘cyto’, ‘cyto2’, ‘cyto3’ and ‘nuclei’ are not four choices, they are four spellings of cpsam — offering them in a dropdown invited users to tune a setting that does nothing.

They are kept as accepted-but-mapped ALIASES rather than removed outright: settings CSVs written years ago must still load. What changes is that they are mapped here, on the way in, instead of being carried around as if they still meant something. A path to a user-trained checkpoint is passed through untouched — that is the one model choice that is still real.

Parameters:

• value – the stored setting, e.g. ‘cyto2’ or ‘/models/my_cells.pth’.

• object_type – ‘cell’/’nucleus’/’pathogen’/’organelle’ if known; used only to make the substitution notice name the right object.

• key – settings key the value came from, for the notice.

Returns:

‘cpsam’, or the checkpoint path unchanged.

spacr.settings.organelle_counting_is_meaningful(organelle_type)

Whether count-dependent measurements mean anything for a type.

Parameters:

organelle_type – a key of spacr.organelle_types.ORGANELLE_TYPES.

Returns:

True for a type that is many separable objects per cell, False for one connected structure, and True for ‘depends’ and ‘unknown’ – the measurement is still produced and the caveat is what carries the doubt. Refusing to measure on a maybe would delete a real number for half the structures in the category.

spacr.settings.organelle_measurement_caveats(settings)

What a measure run should say about its own organelle numbers.

One entry per enabled organelle slot whose type makes a count-dependent family read differently from the way it reads for cells: (slot label, setting name, reason).

A slot is ENABLED when it has a mask dimension to measure. A slot with no type set says nothing, because a settings file written before the type existed is not making a claim about what it imaged.

Parameters:

settings – a measure settings dict.

Returns:

a list of (label, setting, reason), empty when every enabled slot is a many-per-cell type or has no type at all.

spacr.settings.organelle_slots_beyond_the_count(settings, count=None)

Populate declarable organelle slots without changing the active count.

Extra slot keys allow the settings interface to reveal controls when number_of_organelles increases. Existing values take precedence.

Parameters:

• settings – Run-settings mapping; copied rather than modified.

• count – Number of slots to populate. None populates all roles, bounded by spacr.organelle_types.MAX_ORGANELLES.

Returns:

New settings dictionary. Mappings without organelle settings are returned unchanged.

spacr.settings.parse_list(value)

Parse a string literal into a homogeneous list of scalars.

Accepts Python-list or tuple literals and rejects mixed-type contents. Single-element tuples are returned as one-element lists.

Lives here, beside its only caller check_settings(), rather than in the GUI helpers it was written for: nothing about reading “[0, 1, 2]” out of a settings cell is a widget concern, and while it sat in the Tk helper module every settings value that arrives as text depended on a GUI toolkit being importable.

Parameters:

value – string representation of a list or tuple.

Returns:

parsed list containing only ints, floats, or strings.

Raises:

ValueError – if the string is not a valid literal or contains mixed / unsupported types.

spacr.settings.register_defaults(app_key, fn, *, replace=False, expected_types=None, tooltips=None, categories=None, description=None)

Register the defaults factory for app_key.

Parameters:

• app_key – the app key the factory belongs to — the same key the module registered with spacr.qt.app.register_app().

• fn – callable returning the module’s settings dict. Called as fn(settings) when it takes an argument and fn() when it does not, so both existing shapes in this file work unchanged.

• replace – allow overwriting an existing registration. Off by default: two modules quietly claiming one key is the failure this registry exists to make loud.

• expected_types – optional {key: type-or-tuple} merged into expected_types. Without it a new key is untyped and check_settings() cannot validate it.

• tooltips – optional {key: text} merged into tooltips. Without it the settings panel has no help for the key, which the GUI suite fails on.

• categories – optional {category: [key, ...]} merged into categories; unknown category names are created. A key already in that category is not added twice.

• description – optional module blurb for descriptions.

Raises:

• ValueError – on a re-registration without replace, or when a merged type/tooltip/description would change one that already exists — a module may add to the shared tables, never rewrite another module’s entry.

• TypeError – if fn is not callable.

spacr.settings.registered_default_apps()

Every app key with registered defaults, in registration order.

spacr.settings.set_analyze_class_proportion_defaults(settings)

Populate default settings for class-proportion analysis across conditions.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_analyze_endodyogeny_defaults(settings)

Populate default settings for endodyogeny (parasite division) analysis.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_analyze_invasion_defaults(settings)

Populate default settings for the two-colour (red/green) invasion assay.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_analyze_replication_defaults(settings)

Populate defaults for the parasites-per-vacuole replication assay.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_annotate_default_settings(settings)

Populate default settings for the image annotation UI.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_analyze_screen(settings)

Populate default settings for screen analysis (ML-based scoring).

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_classify(settings)

Populate defaults for the merged Classify module.

The union of Classify (CV) and Classify (ML), plus classifier_family to say which of the two a run uses. Built by CALLING both factories rather than by copying their keys: a list here would go stale the first time either module gained a setting, and the symptom would be a control missing from the merged screen only.

CV is applied second and wins on the six keys the two share, because the merged module’s default family is CV.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_general(settings=None)

Return default settings for the general organize/stitch/multichannel run.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied (a shallow copy of the input).

spacr.settings.set_default_generate_barecode_mapping(settings=None)

Return default settings for the barcode-mapping pipeline.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_multichannel(settings=None)

Return default settings for building multichannel per-well mosaics.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied (a shallow copy of the input).

spacr.settings.set_default_plot_data_from_db(settings)

Populate default settings for plotting data pulled from a measurements DB.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_plot_merge_settings()

Return the default settings dict for plotting merged mask overlays.

Returns:

dict populated with the default plot_merge parameters (channel dimensions, backgrounds, overlay behaviour, colormap, etc.).

spacr.settings.set_default_settings_preprocess_generate_masks(settings=None)

Populate default settings for the preprocess/generate-masks pipeline.

Fills channel, Cellpose, plot, timelapse, organelle and post-processing parameters used by preprocess_generate_masks.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_settings_preprocess_img_data(settings)

Populate default settings for the image-preprocessing step.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_stitch(settings=None)

Return default settings for the tile-stitching pipeline.

Covers feature detection, RANSAC, outline overlay, feature cache and per-well mosaic output parameters.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied (a shallow copy of the input).

spacr.settings.set_default_train_test_model(settings)

Populate default settings for the train/test classifier training pipeline.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_default_umap_image_settings(settings=None)

Return the default settings for UMAP/tSNE image-embedding plots.

Parameters:

settings – optional dict to fill in place; a new dict is created if None.

Returns:

the settings dict with defaults applied.

spacr.settings.set_generate_dataset_defaults(settings)

Populate default settings for the generic dataset-generation step.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_generate_training_dataset_defaults(settings)

Populate default settings for generating a labeled training dataset.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_graph_importance_defaults(settings)

Populate default settings for the “graph importance” plot utility.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.set_interpret_vision_model_defaults(settings)

Populate default settings for interpreting vision-model predictions.

Covers feature importance, permutation importance, and SHAP explanation options over the cell/nucleus/pathogen/cytoplasm tables.

Parameters:

settings – dict to fill in place.

Returns:

the settings dict with defaults applied.

spacr.settings.surviving_setting_name(key)

What key is called TODAY, following renames to the end.

ONE RESOLVER FOR ALL THREE CONSUMERS – the run’s fold, the doctor’s message and the Qt panel’s load.

They used to answer this question three different ways. The run consulted the rename table alone, the doctor the retirement table alone, and the Qt panel was the only one that knew the organelle suffix rule. A generated organelle key could therefore be migrated by the panel, ignored by the run and unmentioned by the doctor, all at once.

A CHAIN IS THE FAILURE THIS EXISTS FOR. A later rename takes <role>_min_split_area to <role>_minimum_area_to_split, and <role>_min_object_area was already renamed to _min_split_area – so the oldest files need two hops, and a resolver that takes one leaves the value on a key nothing reads.

LIVENESS IS CHECKED AT THE TERMINUS ONLY. Checking each hop would refuse the middle of a valid chain, because an intermediate name is by definition no longer live. Refusing when the old key is ITSELF still live is what stops a suffix rule retiring a working setting – seven _size keys are live and must not be touched.

Parameters:

key – the key a settings file carries.

Returns:

a tuple of the names read today – empty when key is current, withdrawn, unknown, or resolves through a cycle.

spacr.settings.unregister_defaults(app_key)

Drop a registered defaults factory. True if there was one.

Only the factory: the types, tooltips and categories it merged stay, because another module may already have added keys to the same category and unpicking a merge is guesswork.

Parameters:

app_key – key to drop, coerced with str() exactly as register_defaults() stored it. An unknown key is not an error — the call returns False — so a test teardown can run unconditionally. Dropping a key first is also how a module re-registers without reaching for replace=True.