spacr.refit

Re-fit a screen from its plot with a different statistical model.

The regression plot’s context menu can rerun an analysis with a different model, correction method, or FDR threshold.

A re-fit recalculates results rather than changing plot appearance. The menu therefore presents it separately from styling actions, and spacr.ml._next_results_folder() writes the result beside the original run without overwriting it.

The saved settings require three adjustments before reuse:

• plot is forced to False on the way out (spacr.utils.save_settings() does it so a reload reproduces the run headlessly), so re-running from the saved copy produces no figures at all, even though the action starts from a figure.

• the per-backend knobs are still set to what the old backend read. Handing alpha=0.3 to OLS does not quietly do nothing: _reject_unused_settings() raises, by design, so a lasso -> ols re-fit dies at the entry point.

• regression_type and random_row_column_effects can contradict each other, and the reconciliation between them refuses rather than guesses.

refit_settings() applies these adjustments and reports each change, including reset backend-specific parameters.

Functions

destination(→ Optional[str])	Return the output directory a run would use without executing it.
policed_settings(→ Dict[str, object])	{setting: the value that means "not asked for"}.
prune_for_type(→ Tuple[dict, List[str]])	Reset every knob regression_type cannot read, and name them.
refit_settings(→ Tuple[dict, List[str]])	Return settings for re-running a screen with a new model.
settings_of_run(→ Optional[dict])	The settings a finished run used, read back from beside its results.

Module Contents

spacr.refit.destination(settings: dict) → str | None

Return the output directory a run would use without executing it.

Parameters:

settings – regression settings used to resolve source and model kind.

Returns:

The predicted results directory, or None when no count-data path or writable folder choice can be resolved. PostgreSQL counts require an explicit local src.

The result uses the same folder-selection rule as the regression run.

spacr.refit.policed_settings() → Dict[str, object]

{setting: the value that means "not asked for"}.

Returns:

Backend-specific setting names mapped to their inactive defaults.

Values are read from spacr.regression_spec, the same source used by the regression implementation, so reset behavior tracks backend settings.

spacr.refit.prune_for_type(settings: dict, regression_type) → Tuple[dict, List[str]]

Reset every knob regression_type cannot read, and name them.

Parameters:

• settings – settings mapping; not mutated.

• regression_type – the backend about to be fitted. None means “choose from the data”, which reads none of the policed knobs – so it prunes as strictly as a named type, for the reason spacr.ml._reject_unused_run_settings() gives.

Returns:

(settings, [what was reset]).

Inapplicable settings are reset rather than deleted so the settings panel retains explicit default values.

spacr.refit.refit_settings(base: dict, *, regression_type=None, correction_method: str | None = None, fdr_alpha: float | None = None, level: str | None = None, alpha=None) → Tuple[dict, List[str]]

Return settings for re-running a screen with a new model.

Parameters:

• base – the settings the run on screen used.

• regression_type – the new backend, or None to keep the old one.

• correction_method – the new multiple-testing correction, or None to keep the old one. Written to CORRECTION_KEY.

• fdr_alpha – the new significance level, or None to keep it.

• level – 'grna', 'gene' or 'both', or None to keep the previous value. Mixed models treat guides as random effects and therefore provide shrunken predictions without per-guide p-values; a guide-level fixed-effect model provides coefficients and p-values.

• alpha – the new penalty weight, where the new backend reads one – a different number from fdr_alpha despite the name.

Returns:

(settings, [notes for the user]).

Raises:

ValueError – if base names no usable count-data path.

Returned notes identify every automatic settings change before execution.

spacr.refit.settings_of_run(results_path) → dict | None

The settings a finished run used, read back from beside its results.

Parameters:

results_path – the results CSV, or the folder holding it.

Returns:

the parsed settings, or None when the run left none.

Search proceeds from the run’s own folder to settings/ beside the results root. This prioritizes run-specific settings over the shared copy, which later runs may overwrite.