EditorSession#

class superglm.editor.EditorSession(
model,
terms: dict[str, EditableTerm],
*,
n_points: int = 200,
centering: str = 'native',
reference_model=None,
evaluation_data: dict[str, Any] | None = None,
cv_report: Any = None,
)#

Bases: object

Stateful editor for fitted 1D main effects.

The session never mutates the source model. Edits are kept in memory until to_model() is called.

classmethod from_model(
model,
terms: list[str] | tuple[str, ...] | None = None,
*,
n_points: int = 200,
centering: str = 'native',
with_se: bool = True,
train_data=None,
validation_data=None,
test_data=None,
cv_report: Any = None,
) → EditorSession#

Build an editor session from fitted 1D main-effect inference.

property model_revision: int#

Semantic revision for prediction- or fit-evidence-changing state.

property edit_epoch: int#

Monotonic invalidation token for the current edited-model materialization.

selection(term: str) → NDArray[int64]#

Return selected point indices for a term.

select_indices(
term: str,
indices,
) → EditorSession#

Select explicit point or level indices.

select_x(
term: str,
start: float,
stop: float,
) → EditorSession#

Select grid points whose x values fall inside [start, stop].

select_levels(
term: str,
levels: list[str] | tuple[str, ...],
) → EditorSession#

Select categorical or ordered-categorical levels by label.

clear_selection(term: str) → EditorSession#

Clear the active selection for a term.

reset(term: str) → EditorSession#

Reset selected values to the original fit, or the whole term if nothing is selected.

shift(term: str, delta: float) → EditorSession#

Add a link-scale delta to the selected values.

set_value(
term: str,
value: float,
) → EditorSession#

Set selected values to one link-scale value.

set_values(
term: str,
indices,
values,
) → EditorSession#

Set explicit values on the internal link/log-effect scale.

weighted_average(term: str) → EditorSession#

Flatten the selected region to its weighted mean.

linear_interpolate(
term: str,
strength: float = 1.0,
) → EditorSession#

Move selected values toward a line between selected endpoints.

level_left(term: str) → EditorSession#

Set selected values to the left-most selected value.

level_right(term: str) → EditorSession#

Set selected values to the right-most selected value.

snap_highest(term: str) → EditorSession#

Set selected values to the highest selected value.

snap_lowest(term: str) → EditorSession#

Set selected values to the lowest selected value.

reorder_levels(
term: str,
direction: str | None = None,
*,
target_index: int | None = None,
) → EditorSession#

Move selected categorical levels in display order.

reset_level_order(term: str) → EditorSession#

Reset a categorical term’s display order to the fitted model order.

level_order_changed(term: str) → bool#

Return whether a categorical term has a custom display order.

isotonic(
term: str,
direction: str = 'increasing',
) → EditorSession#

Apply exposure-weighted isotonic regression to selected values.

Each contiguous run becomes the closest monotone sequence to itself, not tied to its unselected neighbours, so the edit can step at a selection edge. A categorical term clamps instead. If no points are selected, the operation applies to the whole term.

smooth(
term: str,
strength: float = 0.5,
) → EditorSession#

Apply light local smoothing to selected values.

Selected contiguous runs are anchored to adjacent unselected neighbors when available. This avoids visible jumps at edit boundaries. If no points are selected, the operation applies to the whole term.

control_points(
term: str,
n_handles: int | None = None,
) → dict[str, Any]#

Return fixed-x spline control handles for advanced curve editing.

move_control_point(
term: str,
handle_index: int,
log_effect: float,
*,
n_handles: int | None = None,
) → EditorSession#

Move one spline control handle vertically and refit the displayed curve.

undo(term: str | None = None) → EditorSession#

Undo the latest edit or, with none since it, the latest structural step.

Undoing a step puts back the whole editor state from before it, edits included, without refitting. term limits the undo to that term’s latest edit since the last structural step.

redo(term: str | None = None) → EditorSession#

Redo the latest undone edit or, with none, the latest undone structural step.

to_model(*, X=None, y=None, sample_weight=None, offset=None)#

Return an edited copy of the source model.

If explicit evaluation data is supplied, scalar fit statistics on the copy are refreshed against that data. Otherwise the fitted model’s retained fit data is used when available.

capture_materialization_request(
*,
dataset=None,
include_unchanged: bool = False,
) → EditMaterializationRequest | None#

Capture plot-scale state and immutable evaluation references.

materialization_request_is_current(
request: EditMaterializationRequest,
) → bool#

Return whether a captured model snapshot still identifies this session state.

cached_materialized_model(
edit_epoch: int,
*,
model_revision: int | None = None,
base_model=None,
)#

Return the cached model only for matching live session identity.

publish_materialized_model(
request: EditMaterializationRequest,
model,
) → bool#

Publish a private model only if its entire snapshot is still current.

edited_terms() → list[str]#

Names of terms whose edited values differ from the source fit.

edited_offset(
terms: str | list[str] | tuple[str, ...] | None = None,
*,
X=None,
) → NDArray#

Return the link-scale offset implied by edited term curves.

This is the additive offset to pass to fit/fit_reml when the edited terms should be treated as fixed rating factors. If terms is omitted, all changed terms in the session are used.

edited_offset_factor(
terms: str | list[str] | tuple[str, ...] | None = None,
*,
X=None,
) → NDArray#

Return the multiplicative factor represented by edited_offset.

refit_with_edited_offset(
terms: str | list[str] | tuple[str, ...] | None = None,
*,
X=None,
y=None,
sample_weight=None,
offset=None,
method: str = 'auto',
lambda1=Ellipsis,
lambda2=Ellipsis,
**fit_kwargs: Any,
)#

Refit a copy with edited terms fixed as an offset.

The returned model excludes the offset terms from its feature set and fits the remaining terms conditional on the edited offset. Inference on the returned model is therefore for the refitted remaining terms, not for the manually edited offset curves.

reprofile_distribution(
parameter: str,
*,
X=None,
y=None,
sample_weight=None,
offset=None,
fit_mode: str = 'inherit',
progress_callback=None,
**profile_kwargs: Any,
)#

Explicitly re-estimate a distribution parameter for the in-force model.

refit_with_collapsed_levels(
term: str,
*,
group_label: str | None = None,
**refit_kwargs: Any,
)#

Collapse selected categorical levels and refit a full model copy.

refit_kwargs are X, y, sample_weight, offset, method, lambda1, lambda2 and fit keywords.

replace_with_collapsed_levels(term: str, **kwargs: Any)#

Collapse selected levels, refit, and make the refit the in-force edit model.

refit_with_ungrouped_levels(term: str, **refit_kwargs: Any)#

Remove selected levels from collapsed groups and refit a model copy.

replace_with_ungrouped_levels(term: str, **kwargs: Any)#

Ungroup selected levels and put the result in force as one structural step.

When this ungroup removes the model’s last collapsed group and the model before the latest step had none, that earlier fit is exactly the result, so it is reused instead of refitting.

replace_with_reference_level(
term: str,
level: str,
**refit_kwargs: Any,
)#

Pin level as term’s reference, refit, and put the refit in force.

replace_with_shaped_range(
term: str,
*,
lo,
hi,
degree: int,
join: str = 'tangent',
**refit_kwargs: Any,
)#

Pin term to a degree polynomial on [lo, hi], refit, put it in force.

lo and hi are values on a numeric term (snapped outward to three significant figures of the fitted span) and band labels on an ordered one. join is "tangent" or "kink" (Corner).

revert_to_reference_model()#

Put the opened model back in force, in its own level order, as one structural step.

replace_in_force_model(
model,
*,
with_se: bool = True,
level_orders: dict[str, list[str]] | None = None,
) → EditorSession#

Replace the editable in-force model while retaining the original reference model.

Display level reorders carry over unless level_orders replaces them.

save(path: str | Path) → None#

Write an auditable JSON edit artifact.

classmethod load(
path: str | Path,
*,
model,
) → EditorSession#

Load an edit artifact against a fitted model.

widget()#

Return an optional notebook widget for this session.

On this page