erlab.interactive.imagetool.provenance

Helpers for recording, displaying, and replaying ImageTool provenance.

The saved provenance model stores enough history to explain or rebuild an ImageTool without persisting runtime-only replay state. ToolProvenanceSpec has a small set of source forms:

1. Live single-parent source specs.

   • Use full_data() when the derived tool should begin from the parent ImageTool’s current array exactly as shown to the caller.

   • Use public_data() when the derived tool should begin from the parent ImageTool’s public data model, including restoration of non-uniform dimensions.

   • Use selection() when the derived tool should begin from the public ImageTool selection model, including restoration of non-uniform dimensions.

2. Durable replay specs.

   • Use file_load() for data that can be reloaded from a recorded file source and replayed through structured ReplayStage operations.

   • Use script() for console-derived and other multi-input results. Script specs may reference any number of ScriptInput records. Each input stores an immutable replay name, a historical display label, optional live manager node identity and node_snapshot_token, and an optional nested provenance snapshot.

Each transformation is represented by an immutable ToolProvenanceOperation subclass whose serialized fields are safe to persist in JSON. Persisted specs are the source of truth for workspace save/load. Runtime reload, copied code, and shared-input deduplication compile those specs on demand through erlab.interactive.imagetool._replay_graph; the graph itself is not saved.

Manager children opened from an ImageTool cursor or bin selection do not keep the first generated qsel arguments as their refresh state. They store the selected parent indices in ImageToolSelectionSourceBinding and rebuild qsel or isel operations from the current parent data each time they refresh.

Adding a new provenance-carrying operation follows the same pattern every time:

1. Define a new ToolProvenanceOperation subclass with a unique op discriminator literal. Subclasses register themselves automatically so serialized payloads can dispatch to the right model.

2. Prefer the annotated provenance field aliases defined in this module for hashable dimension identifiers and dim-keyed mappings so runtime values stay decoded while JSON dumps remain lossless.

3. If the operation needs already-encoded payloads such as xarray objects or array-like vertex data, validate them with ToolProvenanceOperation._validate_encoded_field() and expose decoded convenience properties for runtime use.

4. Implement ToolProvenanceOperation.apply() so it transforms a derived array using the recorded parameters. parent_data is provided when the operation needs access to parent coordinates or ordering.

5. Implement ToolProvenanceOperation.expression_code() and ToolProvenanceOperation.derivation_label() so copied code and manager derivation entries come from the same operation metadata. Override ToolProvenanceOperation.derivation_entry() only when the operation is not a structured transform, such as free-form script code.

6. If the operation maps cleanly from manager-console calls, declare ToolProvenanceOperation.console_patterns or implement ToolProvenanceOperation.from_console_call(). Unsupported or ambiguous console calls should return None so they remain valid script provenance instead of being recorded as lossy structured operations.

7. Make generated code executable in the replay namespace. Use the literal helpers in this module for persisted values, and make expression_code honor the input name it is given. The base replay_code wrapper assigns the caller-selected output name.

8. Export the operation class from this module so runtime call sites can instantiate it directly.

9. Add tests that cover round-trip validation, apply(), derivation text/code, console matching when supported, and any save/load or reload path that persists the new operation.

Parsing of serialized payloads happens only through parse_tool_provenance_spec() and parse_tool_provenance_operation(). Runtime authoring code should create specs with full_data(), public_data(), selection(), file_load(), or script(), then instantiate operation models from this module directly.

Functions

compose_display_provenance(parent, ...[, ...])	Compose streamlined display provenance from a live source spec.
compose_full_provenance(parent, local)	Compose canonical full provenance from parent and local provenance.
decode_provenance_value(value)	Decode values produced by encode_provenance_value().
direct_replay_input_name(value)	Return a direct input expression for simple replay seeds.
encode_provenance_value(value)	Encode non-JSON provenance values into a JSON-safe representation.
file_load(*, start_label, seed_code, ...[, ...])	Build structured file-backed provenance for runtime reload.
full_data(*operations)	Build a spec that starts from the parent's full current data.
mark_promoted_1d_source(data)	Return data tagged as originating from a promoted 1D source.
operations_expression_code(operations, ...)	Return chained expression code for structured operations.
parse_tool_provenance_spec(value)	Parse a serialized provenance payload into a validated spec instance.
public_data(*operations)	Build a spec that starts from the parent's restored public data.
rebase_default_replay_input(code, input_name)	Replace the generic data replay input in generated code.
rebase_script_input_node_uids(value, uid_map)	Return value with script input node UIDs remapped recursively.
replay_file_provenance(spec, *[, cache])	Replay structured file provenance without executing generated Python.
replay_script_provenance(spec, inputs)	Execute script provenance from already resolved input arrays.
require_live_source_spec(value)
script(*operations, start_label[, ...])	Build script provenance from code, structured steps, and named inputs.
script_input_dependency_refs(value)	Return all live manager dependency references stored in script inputs.
script_provenance_replayable(spec)	Return whether script provenance is self-contained enough to execute.
selection(*operations)	Build a spec that starts from the parent's public selection model.
to_replay_provenance_spec(value)	Parse value and normalize it into canonical replay provenance.
uses_default_replay_input(code)	Return whether generated replay code refers to the generic data input.

Classes

AffineCoordOperation(**data)
AssignAttrsOperation(**data)
AssignCoord1DOperation(**data)
AssignCoordsOperation(**data)
AssignScalarCoordOperation(**data)
AverageOperation(**data)
CoarsenOperation(**data)
CorrectWithEdgeOperation(**data)
DerivationEntry(label, code[, copyable])	One user-visible step in a provenance derivation listing.
DivideByCoordOperation(**data)
FileDataSelection(**data)	Serializable selection of one displayable array from a loaded file object.
FileLoadSource(**data)	Serializable file origin used by saved file-backed provenance.
FileReplayCall(**data)	Serializable call information used to reload file-backed provenance.
GaussianFilterOperation(**data)
ImageToolSelectionSourceBinding(**data)	ImageTool selection state stored for manager child refreshes.
InterpolationOperation(**data)
IselOperation(**data)
LeadingEdgeOperation(**data)
MaskWithPolygonOperation(**data)
NormalizeOperation(**data)
QSelAggregationOperation(**data)
QSelOperation(**data)
RenameDimsCoordsOperation(**data)
RenameOperation(**data)
ReplayStage(**data)	Structured transformation stage replayed against one parent data array.
RestoreNonuniformDimsOperation(**data)
RotateOperation(**data)
ScriptCodeOperation(**data)
ScriptInput(**data)	Named input captured by script or multi-tool provenance.
ScriptInputDependencyRef(name, label, node_uid)	Live manager dependency captured by a script input.
SelOperation(**data)
SelectCoordOperation(**data)
SliceAlongPathOperation(**data)
SortCoordOrderOperation(**data)
SqueezeOperation(**data)
SwapDimsOperation(**data)
SymmetrizeNfoldOperation(**data)
SymmetrizeOperation(**data)
ThinOperation(**data)
ToolProvenanceOperation(**data)	Base class for typed operations stored in ToolProvenanceSpec.
ToolProvenanceSpec(**data)	Saved provenance recipe for ImageTool data.
TransposeOperation(**data)

class erlab.interactive.imagetool.provenance.AffineCoordOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['affine_coord']

coord_name: str

scale: float

offset: float

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.AssignAttrsOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['assign_attrs']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

attrs: ProvenanceMapping

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.AssignCoord1DOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['assign_coord_1d']

coord_name: ProvenanceHashable

dim: ProvenanceHashable

values: typing.Any

classmethod from_console_call(call)

property decoded_values: ndarray

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.AssignCoordsOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['assign_coords']

coord_name: str

values: typing.Any

classmethod from_console_call(call)

property decoded_values: ndarray

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.AssignScalarCoordOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['assign_scalar_coord']

coord_name: ProvenanceHashable

value: typing.Any

classmethod from_console_call(call)

property decoded_value: Any

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.AverageOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['average']

dims: ProvenanceHashableTuple

classmethod from_console_call(call)

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.CoarsenOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['coarsen']

dim: ProvenanceIntMapping

boundary: str

side: str

coord_func: str

reducer: str

classmethod from_console_call(call)

property coarsen_kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.CorrectWithEdgeOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['correct_with_edge']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

edge_fit: typing.Any

shift_coords: bool

property decoded_edge_fit: Dataset

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.DerivationEntry(label, code, copyable=False)

Bases: object

One user-visible step in a provenance derivation listing.

label: str

code: str | None

copyable: bool = False

class erlab.interactive.imagetool.provenance.DivideByCoordOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['divide_by_coord']

coord_name: ProvenanceHashable

divisor_code(data_name)

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.FileDataSelection(**data)

Bases: BaseModel

Serializable selection of one displayable array from a loaded file object.

New provenance stores stable Dataset variable names and DataTree data paths instead of the positional parsed-array index used by older workspaces.

kind: typing.Literal['dataarray', 'dataset_variable', 'datatree_path', 'parsed_index']

value: typing.Any

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.FileLoadSource(**data)

Bases: BaseModel

Serializable file origin used by saved file-backed provenance.

path: str

loader_label: str

loader_text: str

kwargs_text: str

replay_call: FileReplayCall | None

load_code: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.FileReplayCall(**data)

Bases: BaseModel

Serializable call information used to reload file-backed provenance.

kind: typing.Literal['erlab_loader', 'callable']

target: str

kwargs: dict[str, typing.Any]

selection: FileDataSelection

cast_float64: bool

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.GaussianFilterOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['gaussian_filter']

sigma: ProvenanceFloatMapping

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.ImageToolSelectionSourceBinding(**data)

Bases: BaseModel

ImageTool selection state stored for manager child refreshes.

Stores the parent dimension indices selected in an ImageTool plot. When a child refreshes after parent coordinates change, materialize() rebuilds qsel or isel operations from the current parent data so the child follows the same cursor or bin position instead of old coordinate labels.

Parameters:

• selection_mode (Literal['qsel', 'isel']) – Use "qsel" when selected hidden dimensions should be represented by current coordinate values, or "isel" when they must stay index-based.

• selection_indexers (Annotated[dict[Hashable, Any], BeforeValidator(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._coerce_hashable_mapping_field, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._json_encode_field, return_type=PydanticUndefined, when_used=json)]) – Parent dimension names mapped to integer indices or index slices from the cursor or bin selection.

• selection_binned_dims (Annotated[tuple[Hashable, ...], BeforeValidator(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._coerce_hashable_tuple_field, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._json_encode_field, return_type=PydanticUndefined, when_used=json)]) – Dimensions in selection_indexers whose slices should become qsel center and width arguments.

• crop_sel_indexers (Annotated[dict[Hashable, Any], BeforeValidator(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._coerce_hashable_mapping_field, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._json_encode_field, return_type=PydanticUndefined, when_used=json)]) – Index slice selections from visible axes that should be represented by current coordinate values during refresh.

• crop_isel_indexers (Annotated[dict[Hashable, Any], BeforeValidator(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._coerce_hashable_mapping_field, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._json_encode_field, return_type=PydanticUndefined, when_used=json)]) – Index slice selections from visible non-uniform axes.

• transpose_dims (Annotated[tuple[Hashable, ...] | None, BeforeValidator(func=~erlab.interactive.imagetool.provenance._coerce_nullable_hashable_tuple_field, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~erlab.interactive.imagetool.provenance.ToolProvenanceOperation._json_encode_field, return_type=PydanticUndefined, when_used=json)]) – Dimension order to apply after selection, if the opened tool expects a transposed input.

• squeeze (bool) – Whether to squeeze singleton dimensions after selection.

schema_version: typing.Literal[1]

kind: typing.Literal['imagetool_selection']

selection_mode: typing.Literal['qsel', 'isel']

selection_indexers: ProvenanceMapping

selection_binned_dims: ProvenanceHashableTuple

crop_sel_indexers: ProvenanceMapping

crop_isel_indexers: ProvenanceMapping

transpose_dims: NullableProvenanceHashableTuple

squeeze: bool

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

materialize(parent_data)

Build a source spec for the current parent data.

Parameters:

parent_data (DataArray) – Current data from the parent ImageTool.

Returns:

ToolProvenanceSpec – Source spec whose qsel, isel, and sel operations match this binding on parent_data.

Return type:

ToolProvenanceSpec

class erlab.interactive.imagetool.provenance.InterpolationOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['interpolate']

dim: ProvenanceHashable

values: typing.Any

method: typing.Literal['linear', 'nearest']

classmethod from_console_call(call)

property decoded_values: ndarray

apply(data, *, parent_data)

expression_code(input_name, *, source_name=None)

derivation_label()

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.IselOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['isel']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

kwargs: ProvenanceMapping

property decoded_kwargs: dict[Hashable, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.LeadingEdgeOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['leading_edge']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

fraction: float

dim: ProvenanceHashable

direction: typing.Literal['positive', 'negative']

property kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.MaskWithPolygonOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['mask_with_polygon']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

vertices: typing.Any

dims: ProvenanceHashableTuple

invert: bool

drop: bool

property kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.NormalizeOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['normalize']

dims: ProvenanceHashableTuple

mode: typing.Literal['area', 'minmax', 'min', 'min_area']

denominator_rtol: float

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.QSelAggregationOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['qsel_aggregate']

dims: ProvenanceHashableTuple

func: typing.Literal['mean', 'min', 'max', 'sum']

classmethod from_console_call(call)

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.QSelOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['qsel']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

kwargs: ProvenanceMapping

property decoded_kwargs: dict[Hashable, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.RenameDimsCoordsOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['rename_dims_coords']

mapping: ProvenanceHashableMapping

classmethod from_console_call(call)

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.RenameOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['rename']

name: str

classmethod from_console_call(call)

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.ReplayStage(**data)

Bases: BaseModel

Structured transformation stage replayed against one parent data array.

source_kind: typing.Literal['full_data', 'public_data', 'selection']

operations: tuple[pydantic.SerializeAsAny[ToolProvenanceOperation], ...]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod from_source_spec(source)

class erlab.interactive.imagetool.provenance.RestoreNonuniformDimsOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['restore_nonuniform_dims']

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.RotateOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['rotate']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

angle: float

axes: ProvenanceHashablePair

center: tuple[float, float]

reshape: bool

order: int

property kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.ScriptCodeOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['script_code']

label: str

code: str | None

copyable: bool

live_applicable: typing.ClassVar[bool] = False

apply(data, *, parent_data)

derivation_entry()

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.ScriptInput(**data)

Bases: BaseModel

Named input captured by script or multi-tool provenance.

name is the immutable replay variable, label is the historical display label, node_uid and node_snapshot_token identify the live manager input that was used, and provenance_spec stores the historical replay source used when that live input is unavailable.

name: str

label: str

node_uid: str | None

node_snapshot_token: str | None

provenance_spec: dict[str, typing.Any] | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parsed_provenance_spec()

class erlab.interactive.imagetool.provenance.ScriptInputDependencyRef(name, label, node_uid, node_snapshot_token=None)

Bases: object

Live manager dependency captured by a script input.

name: str

label: str

node_uid: str

node_snapshot_token: str | None = None

class erlab.interactive.imagetool.provenance.SelOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['sel']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

kwargs: ProvenanceMapping

property decoded_kwargs: dict[Hashable, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.SelectCoordOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['select_coord']

coord_name: ProvenanceHashable

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.SliceAlongPathOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['slice_along_path']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

vertices: ProvenanceFloatSequenceMapping

step_size: float

dim_name: str

property kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.SortCoordOrderOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['sort_coord_order']

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.SqueezeOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['squeeze']

classmethod from_console_call(call)

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.SwapDimsOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['swap_dims']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

mapping: ProvenanceHashableMapping

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.SymmetrizeNfoldOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['symmetrize_nfold']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

fold: int

axes: ProvenanceHashablePair

center: typing.Any

reshape: bool

order: int

property kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.SymmetrizeOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['symmetrize']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool.provenance.ConsoleOperationPattern object>,)

dim: ProvenanceHashable

center: float

subtract: bool

mode: typing.Literal['full', 'valid']

part: typing.Literal['both', 'below', 'above']

property kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.ThinOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['thin']

mode: typing.Literal['global', 'per_dim']

factor: int | None

factors: ProvenanceIntMapping

classmethod from_console_call(call)

property kwargs: dict[str, Any]

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class erlab.interactive.imagetool.provenance.ToolProvenanceOperation(**data)

Bases: BaseModel

Base class for typed operations stored in ToolProvenanceSpec.

New operations should keep runtime fields in their decoded Python form, prefer the annotated provenance field aliases in this module for lossless JSON serialization, implement apply() to replay the transformation, implement expression_code() to emit the public Python expression for the same transformation, and implement derivation_label() to describe the step in manager UI.

Operation instances store the exact arguments used by live refresh, replay graph execution, copied code, and derivation display. If a public console call maps exactly to an operation, expose it with console_patterns or from_console_call(); ambiguous calls should return None so script provenance records the original code instead.

live_applicable: typing.ClassVar[bool] = True

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = ()

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

apply(data, *, parent_data)

Apply this operation to the current derived array.

Subclasses that participate in live refresh or executable provenance replay should reimplement this method. The implementation must be deterministic for the operation’s stored model fields and must not mutate data or parent_data in place.

Parameters:

• data (DataArray) – Array produced by the preceding replay step.

• parent_data (DataArray) – Parent ImageTool data for the enclosing provenance spec. Operations may inspect it for coordinates, dimension order, or metadata.

Returns:

xarray.DataArray – Array after this operation has been applied.

Return type:

DataArray

Notes

Operations that only emit generated code should set live_applicable = False and raise from this method.

derivation_entry()

Return the user-visible derivation entry for this operation.

Structured transform subclasses should normally reimplement derivation_label() and expression_code() instead of overriding this method. Override this method only for operations whose display entry cannot be represented as a label plus parameterized operation code, such as stored free-form script code.

Returns:

DerivationEntry – Label, replay code, and copyability flag shown in derivation UI and used by legacy derivation-code paths.

Return type:

DerivationEntry

Notes

The base implementation keeps the legacy derived replay contract while letting concrete operations emit expression code for any input variable.

Use DerivationEntry(..., code=None) instead when the step should remain visible in the derivation list but code generation should stop and return None.

derivation_label()

Return the derivation-list label for this operation.

Subclasses should reimplement this for every structured operation that uses the base derivation_entry() implementation.

Returns:

str – Human-readable operation label for derivation/history UI. Include the operation’s meaningful parameters when they help explain the produced data.

Return type:

str

expression_code(input_name, *, source_name=None)

Return a Python expression applying this operation to an input name.

Subclasses should reimplement this for every structured operation that can be represented as ordinary user-facing Python code. The emitted expression should be complete, public-API-based, and free of assignment to hardcoded temporary names.

Parameters:

• input_name (str) – Python expression or identifier for the array produced by the previous replay step. Use this exact value as the operation receiver/input instead of assuming a variable name such as derived.

• source_name (str | None, default: None) – Python expression or identifier for the original public input array for the enclosing replay sequence. Operations that need parent/source context, such as coordinate-order restoration, should use this name for that context. Operations that only transform input_name may ignore it.

Returns:

str – Python expression that evaluates to the transformed DataArray.

Return type:

str

replay_code(input_name, *, output_name=None, source_name=None)

Return replay code for this operation with caller-selected names.

This method usually should not be reimplemented by subclasses. Implement expression_code() instead so replay graph emission, dialog copy code, and derivation entries all share the same operation expression.

Parameters:

• input_name (str) – Python expression or identifier for the array produced by the previous replay step.

• output_name (str | None, default: None) – Variable name to assign the transformed value to. If None, return only the expression from expression_code().

• source_name (str | None, default: None) – Python expression or identifier for the original public input array for the enclosing replay sequence. Passed through to expression_code().

Returns:

str – Either an assignment statement when output_name is provided, or a bare expression when it is None.

Return type:

str

classmethod from_console_call(call)

Build an operation from a normalized manager-console call.

Subclasses should reimplement this when a console call maps cleanly to the operation but cannot be expressed with declarative console_patterns alone. Return None for unsupported, ambiguous, or lossy calls so the original console code remains recorded as script provenance.

Parameters:

call (ConsoleCall) – Normalized descriptor for the function, method, or accessor call observed by the ImageTool manager console, including unwrapped arguments, keyword arguments, display code, and receiver data when available.

Returns:

ToolProvenanceOperation or None – Operation instance when the call is exactly representable by this operation class; otherwise None.

Return type:

ToolProvenanceOperation | None

class erlab.interactive.imagetool.provenance.ToolProvenanceSpec(**data)

Bases: BaseModel

Saved provenance recipe for ImageTool data.

Live child-tool refresh uses single-parent specs from full_data(), public_data(), or selection(). Durable reload and copied code use file and script specs, including multi-input script_inputs for console or UI actions that combine several ImageTools. Deserialize saved payloads with parse_tool_provenance_spec().

A spec records exact operation arguments for live refresh, runtime replay, copied code, and derivation display. Manager children opened from ImageTool cursor or bin selections should keep ImageToolSelectionSourceBinding as their refresh state; that binding builds a spec before refresh so edited parent coordinates are used.

schema_version: typing.Literal[2]

kind: typing.Literal['full_data', 'public_data', 'selection', 'script', 'file']

start_label: str | None

seed_code: str | None

active_name: str | None

operations: tuple[pydantic.SerializeAsAny[ToolProvenanceOperation], ...]

file_load_source: FileLoadSource | None

replay_stages: tuple[ReplayStage, ...]

script_inputs: tuple[ScriptInput, ...]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property is_live_source: bool

append_operations(*operations)

Append operation instances to the spec.

Runtime code should pass operation instances from this module. Saved mappings should be normalized with parse_tool_provenance_spec() before calling this method.

drop_trailing_rename()

append_replacement_operations(*operations)

Replace a final rename, if present, then append new operation instances.

append_final_rename(name)

append_replay_stage(source)

Append one live-source transformation stage to file provenance.

to_replay_spec()

Return the durable replay form for this spec.

Replay specs are the canonical, composable form used for derivation metadata, copied code, workspace save/load, and manager dependency status. Structured file provenance remains structured so runtime reloads can replay typed operations without exec. Live ImageTool refresh uses the original single-parent spec via require_live_source_spec().

apply(parent_data)

derivation_entries()

derivation_code()

display_entries(*, parent_data=None)

Return streamlined derivation entries for UI and copy-code output.

The display path hides internal ImageTool normalization steps while keeping the recorded replay steps available through derivation_entries().

display_code(*, parent_data=None)

Return streamlined replay code for UI and clipboard actions.

The display path preserves exact live-source behavior while omitting user-facing no-op and normalization steps from copied provenance code.

class erlab.interactive.imagetool.provenance.TransposeOperation(**data)

Bases: ToolProvenanceOperation

op: typing.Literal['transpose']

dims: NullableProvenanceHashableTuple

classmethod from_console_call(call)

apply(data, *, parent_data)

derivation_label()

expression_code(input_name, *, source_name=None)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

erlab.interactive.imagetool.provenance.compose_display_provenance(parent, source_spec, *, parent_data=None)

Compose streamlined display provenance from a live source spec.

erlab.interactive.imagetool.provenance.compose_full_provenance(parent, local)

Compose canonical full provenance from parent and local provenance.

parent represents the replay provenance for the current input data. local represents the additional steps performed by the current node. File-backed parents remain structured when composed with live-source specs so runtime reloads can avoid executing generated Python.

erlab.interactive.imagetool.provenance.decode_provenance_value(value)

Decode values produced by encode_provenance_value().

erlab.interactive.imagetool.provenance.direct_replay_input_name(value)

Return a direct input expression for simple replay seeds.

This only applies to non-default single-line seeds such as watched variables. Generic replay aliases like derived = data continue to use derived so existing non-watched code generation remains stable.

erlab.interactive.imagetool.provenance.encode_provenance_value(value)

Encode non-JSON provenance values into a JSON-safe representation.

erlab.interactive.imagetool.provenance.file_load(*, start_label, seed_code, file_load_source, active_name='derived', replay_stages=())

Build structured file-backed provenance for runtime reload.

erlab.interactive.imagetool.provenance.full_data(*operations)

Build a spec that starts from the parent’s full current data.

erlab.interactive.imagetool.provenance.mark_promoted_1d_source(data)

Return data tagged as originating from a promoted 1D source.

erlab.interactive.imagetool.provenance.operations_expression_code(operations, input_name, *, source_name=None)

Return chained expression code for structured operations.

source_name is the public/source array name passed to operations that need context beyond the transformed input, such as coordinate-order restoration.

erlab.interactive.imagetool.provenance.parse_tool_provenance_spec(value)

Parse a serialized provenance payload into a validated spec instance.

This is the deserialize boundary for saved tool and workspace metadata. Runtime authoring code should pass ToolProvenanceSpec instances directly.

erlab.interactive.imagetool.provenance.public_data(*operations)

Build a spec that starts from the parent’s restored public data.

erlab.interactive.imagetool.provenance.rebase_default_replay_input(code, input_name)

Replace the generic data replay input in generated code.

Manager clipboard actions use this when a concrete source is known, such as a watched variable, a load snippet target, or a user-provided variable name.

erlab.interactive.imagetool.provenance.rebase_script_input_node_uids(value, uid_map)

Return value with script input node UIDs remapped recursively.

erlab.interactive.imagetool.provenance.replay_file_provenance(spec, *, cache=None)

Replay structured file provenance without executing generated Python.

erlab.interactive.imagetool.provenance.replay_script_provenance(spec, inputs)

Execute script provenance from already resolved input arrays.

The caller is responsible for trust and input resolution. This function only validates the provenance shape, compiles it through the replay graph, and returns the replayed xarray.DataArray.

erlab.interactive.imagetool.provenance.require_live_source_spec(value)

erlab.interactive.imagetool.provenance.script(*operations, start_label, seed_code=None, active_name=None, file_load_source=None, script_inputs=())

Build script provenance from code, structured steps, and named inputs.

erlab.interactive.imagetool.provenance.script_input_dependency_refs(value)

Return all live manager dependency references stored in script inputs.

erlab.interactive.imagetool.provenance.script_provenance_replayable(spec)

Return whether script provenance is self-contained enough to execute.

This checks the saved code and structured operations. It does not mean live manager inputs are present; callers still need to resolve script_inputs.

erlab.interactive.imagetool.provenance.selection(*operations)

Build a spec that starts from the parent’s public selection model.

erlab.interactive.imagetool.provenance.to_replay_provenance_spec(value)

Parse value and normalize it into canonical replay provenance.

erlab.interactive.imagetool.provenance.uses_default_replay_input(code)

Return whether generated replay code refers to the generic data input.