spacr.settings_advisor

Inspect screen tables and propose regression settings.

The advisor separates measured choices, settings that remain undecided, and questions the data cannot answer. Each proposed value includes its reason, and this module never writes settings itself.

Count-table summaries use every available well. Object-level score tables may be large, so response diagnostics use a capped sample and mark the resulting Reading accordingly. Family, control, and fraction choices reuse the same analysis helpers as the regression pipeline.

Classes

Advice	What the data decided, what it would not, and what it was read from.
Choice	One setting the data decided, and what decided it.
Question	Something the data cannot answer.
Reading	What was measured, before any advice is derived from it.
Undecided	A setting this module will not guess, and why not.

Functions

advise(→ Advice)	Build a regression-setting proposal from measurements and answers.
advise_that_runs(→ Advice)	Build advice and withdraw choices that fail runtime preflight.
advise_the_screen(, scores, dependent_variable, ...)	Read screen inputs and return a regression-settings recommendation.
questions_for(→ Tuple[Question, ...])	Return questions that cannot be answered from this screen's data.
read_the_counts(→ Dict[str, Any])	Measure plates, wells, guides, genes, and replication from count data.
read_the_last_run(→ Dict[str, Any])	Read a finished run's own diagnostics off disk.
read_the_response(→ Dict[str, Any])	Measure response range, shape, and per-well support.
read_the_screen(, scores, dependent_variable, *, row_cap)	Measure both halves of the input and return one Reading.
refusals(→ Tuple[str, ...])	Return reasons a regression settings mapping cannot be run.
requirements_for_unit(→ Dict[str, Any])	Return settings required by an analysis unit.

Module Contents

class spacr.settings_advisor.Advice

What the data decided, what it would not, and what it was read from.

Parameters:

• chosen – ordered setting proposals carrying their keys, values, and evidence; as_settings() converts them to a mapping.

• undecided – unresolved or withdrawn proposals with explanations returned by why() and displayed to the user.

• reading – optional measured screen and completed-run evidence from which the proposals were derived.

as_settings() → Dict[str, Any]

{key: value} – what would be written if this is accepted.

why(key: str) → str

The reason for one key, or ''.

Parameters:

key – chosen or unresolved setting name to look up.

class spacr.settings_advisor.Choice

One setting the data decided, and what decided it.

Parameters:

• key – the setting name, exactly as the panel spells it.

• value – what to put in it.

• why – the reason, naming the measurement. Not “recommended” – a reason a user cannot check against their own data is a slogan.

class spacr.settings_advisor.Question

Something the data cannot answer.

Parameters:

• key – an identifier for the answer, not a setting name – one answer can move several settings.

• prompt – the question shown to the user.

• kind – 'number' or 'choice'.

• options – for 'choice', ((value, label), ...).

• default – the starting value, which is a position and is defended in why_it_matters rather than left as an unexplained number.

• why_it_matters – what changes in the settings depending on the answer. Shown beside the question, because a user who cannot see what a question buys cannot answer it well.

class spacr.settings_advisor.Reading

What was measured, before any advice is derived from it.

Separate from Advice on purpose: the reading is checkable against the user’s own data, and the advice is an argument FROM it. A reader who disagrees with a choice can see which number produced it.

sample_note() → str

How the response numbers should be qualified, or ''.

property read_a_run: bool

Whether a previous run’s diagnostics were read.

property read_the_counts: bool

Whether count-table wells and guides were measured.

property read_the_response: bool

Whether the response count and numeric range were measured.

class spacr.settings_advisor.Undecided

A setting this module will not guess, and why not.

Parameters:

• key – setting name or advisory topic left unresolved; Advice.why() uses it to retrieve this record’s explanation.

• why – evidence-based explanation of why no value was proposed or why a refused proposal was withdrawn.

spacr.settings_advisor.advise(reading: Reading, answers: Dict[str, Any] | None = None) → Advice

Build a regression-setting proposal from measurements and answers.

This function has no settings side effects. The caller decides whether and how to display or apply the returned Advice.

Parameters:

reading – measured screen properties from which settings are derived.

spacr.settings_advisor.advise_that_runs(reading: Reading, answers: Dict[str, Any] | None = None) → Advice

Build advice and withdraw choices that fail runtime preflight.

A choice named by refusals() moves from chosen to undecided with the validation message. The function does not silently substitute a different value.

Parameters:

• reading (Reading) – Measurements and metadata describing the screen.

• answers (dict, optional) – User answers to questions the screen data cannot settle.

Returns:

Advice – A proposal containing only choices that pass the preflight checks.

spacr.settings_advisor.advise_the_screen(counts: Sequence[str] = (), scores: Sequence[str] = (), dependent_variable: str = '', answers: Dict[str, Any] | None = None, *, row_cap: int = ROW_CAP, run_folder: str = '', settings: Mapping[str, Any] | None = None) → Advice

Read screen inputs and return a regression-settings recommendation.

Parameters:

• run_folder – optional completed run whose recorded diagnostics can refine the input-based recommendation. An empty value requires no prior fit.

• settings – current panel settings used to reject diagnostics from a run fitted with an incompatible model family.

Returns:

recommended and unresolved settings with the evidence used to derive them.

spacr.settings_advisor.questions_for(reading: Reading) → Tuple[Question, ...]

Return questions that cannot be answered from this screen’s data.

The direction question is omitted for a binary response, where only an increase can represent the positive outcome.

Parameters:

reading – measured screen properties used to omit answered questions.

spacr.settings_advisor.read_the_counts(paths: Sequence[str]) → Dict[str, Any]

Measure plates, wells, guides, genes, and replication from count data.

All count rows are used. Per-well fractions are calculated with spacr.cell_montage.fractions_from_counts(), matching the values used by the regression pipeline.

Parameters:

paths – count-table paths to read together as one screen design.

spacr.settings_advisor.read_the_last_run(folder: str, settings: Mapping[str, Any] | None = None) → Dict[str, Any]

Read a finished run’s own diagnostics off disk.

A READ OF WHAT ALREADY EXISTS, never a second diagnostic pass. The numbers are the ones regression_qc measured and printed onto its own report; recomputing them here would let the advisor and the QC panel disagree about the same fit, and the user would have no way to tell which was right.

Parameters:

• folder – the run folder, or the regression_qc folder inside it.

• settings – the settings now in the panel, so a run fitted under different ones is reported as STALE rather than used silently.

Returns:

the fields to merge into a Reading. Always includes run_folder when a run was found, and run_note when one was found and is not being used.

spacr.settings_advisor.read_the_response(paths: Sequence[str], dependent_variable: str = '', *, row_cap: int = ROW_CAP) → Dict[str, Any]

Measure response range, shape, and per-well support.

At most row_cap object rows are read across the supplied score tables. The returned mapping records whether that cap was reached so callers can qualify sample-derived recommendations.

Parameters:

• paths (sequence of str) – Score tables to inspect.

• dependent_variable (str, optional) – Response column. Common generated-score names are tried when omitted.

• row_cap (int, optional) – Maximum number of object rows to inspect.

Returns:

dict – Measured response properties and any non-fatal problems in "trouble".

spacr.settings_advisor.read_the_screen(counts: Sequence[str] = (), scores: Sequence[str] = (), dependent_variable: str = '', *, row_cap: int = ROW_CAP) → Reading

Measure both halves of the input and return one Reading.

spacr.settings_advisor.refusals(settings: Mapping[str, Any]) → Tuple[str, ...]

Return reasons a regression settings mapping cannot be run.

This check covers incompatible setting combinations that default filling and type coercion cannot resolve. Messages follow the runtime validation wording so an application can explain a refusal before starting a fit.

Parameters:

settings (mapping) – Proposed regression settings.

Returns:

tuple of str – One actionable message per refusal, or an empty tuple when the settings pass these preflight checks.

spacr.settings_advisor.requirements_for_unit(unit: str) → Dict[str, Any]

Return settings required by an analysis unit.

Parameters:

unit – 'cell' or 'well'.

Returns:

{setting: required value}, empty when the unit constrains nothing.

User interfaces can apply these values immediately and disable the corresponding controls, preventing incompatible combinations from reaching runtime validation.

Nested helpers

_from_the_run.replace(key: str, value: str, why: str) → None

Replace or append one recommendation in the captured choices.

Parameters:

• key – setting-choice key to update.

• value – value recommended from the completed run.

• why – user-facing evidence for the recommendation.

Returns:

None. The first same-key choice is replaced at its existing position; a key not already present is appended once.

spacr/settings_advisor.py:1015