erlab.interactive.imagetool.provenance

Public ImageTool provenance API.

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.
operation_from_console_call(call)	Return the structured operation represented by a console call, if known.
operations_expression_code(operations, ...)	Return chained expression code for structured operations.
parse_tool_provenance_operation(value)	Parse one serialized operation payload.
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_input_name(value)
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)
ConsoleCall(*[, func, dataarray_method, ...])	Normalized runtime call observed by the ImageTool manager console.
ConsoleOperationPattern(*[, target, ...])	Declarative matcher for direct console-to-operation mappings.
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_framework.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.ConsoleCall(*, func=None, dataarray_method=None, accessor_path=(), args=(), kwargs=None, display_code, has_extra_tracked_inputs, receiver_data=None)

Bases: object

Normalized runtime call observed by the ImageTool manager console.

Console proxies create this descriptor after unwrapping provenance-aware tool handles to raw xarray.DataArray arguments. Operation classes inspect the invoked callable, DataArray method/accessor context, and raw arguments to decide whether the call can be represented as structured provenance.

accessor_path

args

dataarray_method

display_code

func

has_extra_tracked_inputs

kwargs

receiver_data

class erlab.interactive.imagetool.provenance.ConsoleOperationPattern(*, target=None, dataarray_method=None, accessor_path=(), fields=(), field_aliases=None, kwargs_field=None, mapping_kwarg=None, defaults=None, ignored_defaults=None)

Bases: object

Declarative matcher for direct console-to-operation mappings.

Use this for calls where public arguments map directly onto operation model fields. Store module-function targets as strings so importing this module does not resolve lazy ERLab analysis modules; the matcher compares those strings with the callable that the console actually invoked. More complex calls should implement ToolProvenanceOperation.from_console_call().

accessor_path

dataarray_method

defaults

field_aliases

fields

ignored_defaults

kwargs_field

mapping_kwargs

targets

match(call)

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_framework.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.

copyable: bool = False

label: str

code: str | None

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.

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].

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

value: typing.Any

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

Bases: BaseModel

Serializable file origin used by saved file-backed provenance.

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].

path: str

loader_label: str

loader_text: str

kwargs_text: str

replay_call: FileReplayCall | None

load_code: str | None

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

Bases: BaseModel

Serializable call information used to reload file-backed provenance.

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].

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

target: str

kwargs: dict[str, typing.Any]

selection: FileDataSelection

cast_float64: bool

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.

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.

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_framework.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_framework.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_framework.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_framework.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.

classmethod from_source_spec(source)

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].

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

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

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_framework.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.

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()

name: str

label: str

node_uid: str | None

node_snapshot_token: str | None

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

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

Bases: object

Live manager dependency captured by a script input.

node_snapshot_token: str | None = None

name: str

label: str

node_uid: str

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

Bases: ToolProvenanceOperation

op: typing.Literal['sel']

console_patterns: typing.ClassVar[tuple[ConsoleOperationPattern, ...]] = (<erlab.interactive.imagetool._provenance_framework.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_framework.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_framework.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_framework.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_framework.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.

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.

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

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

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

live_applicable: typing.ClassVar[bool] = True

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].

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

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.

append_display_operation(operation)

Append a live display operation without making a final name stale.

append_final_rename(name)

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.

append_replacement_operations(*operations)

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

append_replay_stage(source)

Append one live-source transformation stage to file provenance.

apply(parent_data)

derivation_code()

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.

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().

drop_trailing_rename()

property is_live_source: 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].

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().

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, ...]

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.operation_from_console_call(call)

Return the structured operation represented by a console call, if known.

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_operation(value)

Parse one serialized operation payload.

This is the deserialize boundary for saved JSON. Runtime call sites should build concrete operation instances directly instead of passing raw mappings around.

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_input_name(value)

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.