Manager extensions¶

Use these procedures to create, register, and maintain lab-specific analysis routines and file loaders for ImageTool Manager. Review an extension as executable Python code before you approve it.

To write an extension, you must be able to create a Python module and have representative test data.

For extension types, signature rules, and workspace states, see Manager extensions.

Writing an analysis routine¶

Save the following code as gaussian_tools.py:

from typing import Literal

import xarray as xr

import erlab.analysis as era
from erlab.extensions import routine


@routine(
    name="Gaussian convolution",
    category="My Lab",
    summary="Apply a coordinate-aware Gaussian convolution.",
)
def gaussian_convolution(
    data: xr.DataArray,
    sigma: float = 0.01,
    mode: Literal["nearest", "reflect", "constant"] = "nearest",
) -> xr.DataArray:
    return era.image.gaussian_filter(data, sigma=sigma, mode=mode)

The first parameter receives the selected ImageTool data. Manager creates controls for sigma and mode. It opens the returned array in a new ImageTool.

Call the decorated function directly with an existing DataArray named data:

from gaussian_tools import gaussian_convolution

filtered = gaussian_convolution(data, sigma=0.02)

Then validate the saved source independently of the normal module import:

from erlab.extensions import load_script

gaussian_tools = load_script("gaussian_tools.py")
filtered = gaussian_tools.gaussian_convolution(data, sigma=0.02)

load_script() imports the saved source and validates all its decorated functions. If validation fails, use the reported function and parameter name to correct the signature.

Preserving a capability ID¶

Before you rename a function that saved workspaces use, set id to its existing function name:

@routine(id="normalize", name="Normalize", category="My Lab")
def normalize_data(data: xr.DataArray) -> xr.DataArray:
    return data / data.max()

This example keeps the capability ID normalize after the function is renamed to normalize_data.

Writing a file loader¶

Use a loader when one function can read the file and return one xarray object. Save the following code as lab_loaders.py:

from pathlib import Path

import numpy as np
import xarray as xr

from erlab.extensions import loader


@loader(
    name="Lab text matrix",
    category="My Lab",
    summary="Load a numeric text matrix.",
    extensions=(".txt",),
)
def load_lab_text(path: Path, delimiter: str = ",") -> xr.DataArray:
    values = np.atleast_2d(np.loadtxt(path, delimiter=delimiter))
    return xr.DataArray(values, dims=("row", "column"))

Test the saved script with a representative file:

from pathlib import Path

from erlab.extensions import load_script

lab_loaders = load_script("lab_loaders.py")
loaded = lab_loaders.load_lab_text(Path("scan.txt"), delimiter="\t")

Use Implementing a data loader plugin when the format needs scan identification, metadata normalization, multiple-file assembly, or reusable loader configuration.

Adding dependencies¶

Import a dependency in the extension script as you would in a normal module:

import xarray as xr

from erlab.extensions import routine
from some_package import do_something


@routine(name="Remove background", category="My Lab")
def remove_background(data: xr.DataArray) -> xr.DataArray:
    return do_something(data)

Install some_package in the environment that starts Manager. If you use the standalone Manager, use only bundled packages or build a standalone application that includes the dependency.

Put shared modules in an installed package. Manager does not add the extension script directory to the Python import path, so an implicit import from a neighboring file does not work.

Registering a script¶

Start ImageTool Manager.
Select Extensions ‣ Add Script….
Select the .py file.
Review the complete source.
Select OK to approve and register it.

Each registered script must have a unique file name. Manager compares file names without case differences. For example, you cannot register both gaussian_tools.py and GAUSSIAN_TOOLS.py.

Running an analysis routine¶

Select one ImageTool in Manager.
Select the routine from the Extensions menu or the selected row’s Extensions submenu.
Enter the routine parameters.
Select OK.

Manager opens the result in a new ImageTool and records the extension operation in its provenance.

Loading a file¶

Open a Manager file dialog or Data Explorer.
Select the file filter supplied by the extension loader.
Select the file and enter any loader parameters.
Open the file.

Use Loading data files into Manager for drag-and-drop, batch loading, and Data Explorer workflows.

Approving a script update¶

After you edit a registered script, Manager stops running that changed source until you approve it.

Select Extensions ‣ Manage Extensions.
Select the script with the Approval required state.
Select Review Update….
Review the complete source and select OK.

If validation fails, select Show Error Details. Correct the source file, then review the update again.

Locating a moved script¶

If Manager reports that a registered script is missing:

Select the script in the Extension Scripts Not Found dialog.
Select Locate Script….
Select the script at its new location.

The selected file must have the same file name and the same contents as the approved script. To use changed contents, restore the approved file first, then follow the script update procedure.

Selecting workspace embedding¶

Select Extensions ‣ Manage Extensions.
Select the script.
Set Workspace embedding to one of these values:
- Embed when referenced stores the script when a saved operation uses it.
- Always embed stores the script even when no saved operation uses it.
- Never embed omits the source from the workspace.

Use Never embed only when another recovery method preserves the exact approved source.

Recovering a script from a workspace¶

If a workspace contains an embedded copy of an unavailable extension:

Select Extensions ‣ Workspace Requirements.
Select the unavailable extension.
Select Save and Register Script….
Review the embedded source.
Save it as a local .py file.

Manager registers the saved file and updates the workspace requirement. It never runs the embedded source directly.

See Stored code for stored-code behavior and Reviewing stored workspace code for the review procedure.

Troubleshooting a script¶

If the script does not load:

Run load_script() to display import and signature errors.
Confirm that each imported package is in the Manager environment.
Compare the decorated functions with the signature requirements.