API reference#

The modules below contain the public building blocks used by the anywidget toolkit integration.

custom_widgets#

Reusable anywidget widget classes for hyperspy_gui_anywidget.

Each class is an anywidget.AnyWidget subclass with an inline _esm JavaScript string. No build step is required.

class hyperspy_gui_anywidget.custom_widgets.BoundedFloatTextWidget(*args: t.Any, **kwargs: t.Any)[source]#: A bounded float input widget with min/max validation.

class hyperspy_gui_anywidget.custom_widgets.ButtonWidget(*args: t.Any, **kwargs: t.Any)[source]#: A button widget that increments a clicks trait on press.

class hyperspy_gui_anywidget.custom_widgets.CheckboxWidget(*args: t.Any, **kwargs: t.Any)[source]#: A checkbox widget with a label.

class hyperspy_gui_anywidget.custom_widgets.FlatContainer(*args: t.Any, **kwargs: t.Any)[source]#

close()[source]#

Close method.

Closes the underlying comm. When the comm is closed, all of the widget views are automatically removed from the front-end.

class hyperspy_gui_anywidget.custom_widgets.FloatRangeSliderWidget(*args: t.Any, **kwargs: t.Any)[source]#: A two-number input widget for low/high range values.

class hyperspy_gui_anywidget.custom_widgets.FloatSliderWidget(*args: t.Any, **kwargs: t.Any)[source]#: A float range slider widget with a label and readout.

class hyperspy_gui_anywidget.custom_widgets.FloatTextWidget(*args: t.Any, **kwargs: t.Any)[source]#: A float input widget with a label.

class hyperspy_gui_anywidget.custom_widgets.HTMLWidget(*args: t.Any, **kwargs: t.Any)[source]#: A widget that renders HTML content.

class hyperspy_gui_anywidget.custom_widgets.IntProgressWidget(*args: t.Any, **kwargs: t.Any)[source]#: A progress bar widget with a label and readout.

class hyperspy_gui_anywidget.custom_widgets.IntSliderWidget(*args: t.Any, **kwargs: t.Any)[source]#: An integer range slider widget with a label and readout.

class hyperspy_gui_anywidget.custom_widgets.IntTextWidget(*args: t.Any, **kwargs: t.Any)[source]#: An integer input widget with a label.

class hyperspy_gui_anywidget.custom_widgets.LabelWidget(*args: t.Any, **kwargs: t.Any)[source]#: A simple text label widget.

class hyperspy_gui_anywidget.custom_widgets.OddIntSliderWidget(*args: t.Any, **kwargs: t.Any)[source]#: An integer slider that only accepts odd values.

class hyperspy_gui_anywidget.custom_widgets.TextWidget(*args: t.Any, **kwargs: t.Any)[source]#: A text input widget with a label.

class hyperspy_gui_anywidget.custom_widgets.ToggleButtonWidget(*args: t.Any, **kwargs: t.Any)[source]#: A toggle button widget with a boolean value trait.

utils#

Utility functions and base widgets for hyperspy_gui_anywidget.

This module provides small AnyWidget subclasses used as building blocks throughout the package, plus helper functions for labeling, trait-to-widget conversion, and the add_display_arg decorator.

hyperspy_gui_anywidget.utils.add_display_arg(f)[source]#

Decorator that adds a display keyword argument to a widget function.

When display=True (the default):

In Jupyter: the root widget is shown via IPython.display.display and None is returned.
In Marimo: the widget is displayed via IPython.display.display. If the root widget is a VBox/HBox, it is flattened to a FlatContainer first so Marimo can render it correctly.

When display=False: the raw {"widget": ..., "wdict": ...} dictionary is always returned unchanged.

Parameters:: f (callable) – Widget builder function that returns a dict with "widget" and "wdict" keys.
Returns:: Wrapped function with an extra display keyword argument.
Return type:: callable

hyperspy_gui_anywidget.utils.enum2dropdown(trait, description=None, **kwargs)[source]#

Convert an Enum trait into a _Dropdown widget.

Parameters:

trait (traits.api.TraitType) – Trait whose trait_type.values defines the dropdown options.
description (str, optional) – Description text for the widget.
**kwargs – Ignored. Kept for API compatibility.

Returns:

A dropdown widget if the trait has enumerated values, otherwise a plain text widget.

Return type:

_Dropdown or _Text

hyperspy_gui_anywidget.utils.float2floattext(trait, label)[source]#

Convert a float trait into a labeled _FloatText widget.

Parameters:

trait (traits.api.TraitType) – Trait to convert.
label (str) – Label text for the widget.

Returns:

A labeled float text widget.

Return type:

_Labeled

hyperspy_gui_anywidget.utils.get_label(trait, label)[source]#

Return a human-readable label for a trait.

If the trait defines a label, it is used. Otherwise the supplied label is formatted (underscores become spaces, first letter capitalised).

Parameters:

trait (traits.api.TraitType) – The trait object to inspect.
label (str) – Fallback label text.

Returns:

Formatted label string.

Return type:

str

hyperspy_gui_anywidget.utils.labelme(label, widget)[source]#

Wrap a widget with a left-side label using _Labeled.

Parameters:

label (str) – Text to display on the left of the widget.
widget (anywidget.AnyWidget) – Widget instance whose value and description_tooltip are copied into the wrapper.

Returns:

A labeled AnyWidget instance.

Return type:

_Labeled

hyperspy_gui_anywidget.utils.labelme_sandwich(label1, widget, label2)[source]#

Wrap a widget with labels on both sides using _LabeledSandwich.

Parameters:

label1 (str) – Text to display on the left of the widget.
widget (anywidget.AnyWidget) – Widget instance whose value and description_tooltip are copied into the wrapper.
label2 (str) – Text to display on the right of the widget.

Returns:

A sandwich-labeled AnyWidget instance.

Return type:

_LabeledSandwich

hyperspy_gui_anywidget.utils.set_title_container(container, titles)[source]#

Set titles on a container widget.

Tries container.set_title(index, title) first, and falls back to setting container.titles as a tuple.

Parameters:

container (anywidget.AnyWidget) – Container widget that supports titles.
titles (list of str) – Titles to assign to each child.

hyperspy_gui_anywidget.utils.str2text(trait, label)[source]#

Convert a string trait into a labeled _Text widget.

Parameters:

trait (traits.api.TraitType) – Trait to convert.
label (str) – Label text for the widget.

Returns:

A labeled text widget.

Return type:

_Labeled

roi#

ROI widgets for HyperSpy using anywidget.

Each function follows the same pattern:

Apply @add_display_arg for environment-aware display.
Create input widgets (e.g. FloatTextWidget) and populate wdict.
Link HyperSpy object attributes to widgets via link_traits.link.
Wrap everything in a ContainerWidget.
Return {"widget": container, "wdict": wdict}.

hyperspy_gui_anywidget.roi.circle_roi_aw(obj, **kwargs)[source]#

Build a widget for CircleROI.

Parameters:

obj (hyperspy.roi.CircleROI) – The ROI instance to link against.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.roi.line2d_roi_aw(obj, **kwargs)[source]#

Build a widget for Line2DROI.

Parameters:

obj (hyperspy.roi.Line2DROI) – The ROI instance to link against.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.roi.point1d_roi_aw(obj, **kwargs)[source]#

Build a widget for Point1DROI.

Parameters:

obj (hyperspy.roi.Point1DROI) – The ROI instance to link against.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.roi.point_2d_aw(obj, **kwargs)[source]#

Build a widget for Point2DROI.

Parameters:

obj (hyperspy.roi.Point2DROI) – The ROI instance to link against.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.roi.rectangular_roi_aw(obj, **kwargs)[source]#

Build a widget for RectangularROI.

Parameters:

obj (hyperspy.roi.RectangularROI) – The ROI instance to link against.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.roi.span_roi_aw(obj, **kwargs)[source]#

Build a widget for SpanROI.

Parameters:

obj (hyperspy.roi.SpanROI) – The ROI instance to link against.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

axes#

Axis and navigation slider widgets for HyperSpy using anywidget.

hyperspy_gui_anywidget.axes.aw_axes_gui(obj, **kwargs)[source]#

Build a tabbed GUI for an AxesManager.

Parameters:

obj (hyperspy.axes.AxesManager) – Axes manager to build the GUI for.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.axes.aw_navigation_sliders(obj, **kwargs)[source]#

Display navigation sliders for an AxesManager.

Parameters:

obj (hyperspy.axes.AxesManager) – Axes manager containing navigation axes.
**kwargs – Passed to get_aw_navigation_sliders.

Returns:

Result of get_aw_navigation_sliders with display handling.

Return type:

dict or None

model#

Model, component, and parameter widgets for HyperSpy using anywidget.

hyperspy_gui_anywidget.model.fit_component_aw(obj, **kwargs)[source]#

Build a widget for fitting a single component in a selected range.

Parameters:

obj (hyperspy.model.ComponentFit) – The component fit tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.model.get_component_widget(obj, **kwargs)[source]#

Build a widget for a HyperSpy model component.

Parameters:

obj (hyperspy.component.Component) – The component to build a widget for.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.model.get_eelscl_widget(obj, **kwargs)[source]#

Build a widget for an EELS core-loss edge component.

Parameters:

obj (hyperspy.component.Component) – The EELS core-loss edge component.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.model.get_model_widget(obj, **kwargs)[source]#

Build a widget for a HyperSpy model.

Parameters:

obj (hyperspy.model.BaseModel) – The model to build a widget for.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.model.get_parameter_widget(obj, **kwargs)[source]#

Build a widget for a HyperSpy component parameter.

Parameters:

obj (hyperspy.component.Parameter) – The parameter to build a widget for.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.model.get_scalable_fixed_patter_widget(obj, **kwargs)[source]#

Build a widget for a ScalableFixedPattern component.

Parameters:

obj (hyperspy.component.Component) – The ScalableFixedPattern component.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

preferences#

Preferences widgets for HyperSpy using anywidget.

hyperspy_gui_anywidget.preferences.bool2checkbox(trait, label)[source]#

Convert a boolean trait into a checkbox widget.

Parameters:

trait (traits.api.TraitType) – The trait to convert.
label (str) – Label text for the widget.

Returns:

A checkbox widget.

Return type:

_Checkbox

hyperspy_gui_anywidget.preferences.directory2unicode(trait, label)[source]#

Convert a directory/file trait into a labeled text widget.

Parameters:

trait (traits.api.TraitType) – The trait to convert.
label (str) – Label text for the widget.

Returns:

A labeled text widget.

Return type:

_Labeled

hyperspy_gui_anywidget.preferences.range2floatrangeslider(trait, label)[source]#

Convert a Range trait into a range slider widget.

Parameters:

trait (traits.api.TraitType) – The trait to convert.
label (str) – Label text for the widget.

Returns:

A range slider widget.

Return type:

_RangeSlider

hyperspy_gui_anywidget.preferences.show_exspy_preferences_widget(obj, **kwargs)[source]#

Display the exspy preferences widget.

Parameters:

obj (hyperspy.preferences.Preferences) – The exspy preferences object.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.preferences.show_preferences_widget(obj, **kwargs)[source]#

Display the HyperSpy preferences widget.

Parameters:

obj (hyperspy.preferences.Preferences) – The preferences object.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

tools#

Interactive tool widgets for HyperSpy signals using anywidget.

hyperspy_gui_anywidget.tools.calibrate2d_aw(obj, **kwargs)[source]#

Build a widget for 2D signal calibration.

Parameters:

obj (hyperspy.signal_tools.Calibrate2D) – The 2D calibration tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.calibrate_aw(obj, **kwargs)[source]#

Build a widget for 1D signal calibration.

Parameters:

obj (hyperspy.signal_tools.Calibrate) – The 1D calibration tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.find_peaks2D_aw(obj, **kwargs)[source]#

Build a widget for 2D peak finding.

Parameters:

obj (hyperspy.signal_tools.PeakFinder2D) – The 2D peak finder tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.image_constast_editor_aw(obj, **kwargs)[source]#

Build a widget for image contrast editing.

Parameters:

obj (hyperspy.signal_tools.ImageContrastEditor) – The image contrast editor tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.interactive_range_aw(obj, **kwargs)[source]#

Build a widget for interactive range selection.

Parameters:

obj (hyperspy.signal_tools.InteractiveRangeSelector) – The interactive range selector instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.print_edges_table_aw(obj, **kwargs)[source]#

Build a widget for printing EELS edges table.

Parameters:

obj (hyperspy.signal_tools.PrintEdgesTable) – The edges table tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.remove_background_aw(obj, **kwargs)[source]#

Build a widget for background removal.

Parameters:

obj (hyperspy.signal_tools.BackgroundRemoval) – The background removal tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.remove_baseline_aw(obj, **kwargs)[source]#

Build a widget for baseline removal.

Parameters:

obj (hyperspy.signal_tools.BaselineRemoval) – The baseline removal tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.smooth_butterworth_aw(obj, **kwargs)[source]#

Build a widget for Butterworth smoothing.

Parameters:

obj (hyperspy.signal_tools.SmoothButterworth) – The Butterworth smoothing tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.smooth_lowess_aw(obj, **kwargs)[source]#

Build a widget for LOWESS smoothing.

Parameters:

obj (hyperspy.signal_tools.SmoothLowess) – The LOWESS smoothing tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.smooth_savitzky_golay_aw(obj, **kwargs)[source]#

Build a widget for Savitzky-Golay smoothing.

Parameters:

obj (hyperspy.signal_tools.SmoothSavitzkyGolay) – The smoothing tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.smooth_tv_aw(obj, **kwargs)[source]#

Build a widget for total variation smoothing.

Parameters:

obj (hyperspy.signal_tools.SmoothTV) – The total variation smoothing tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.tools.spikes_removal_aw(obj, **kwargs)[source]#

Build a widget for spikes removal.

Parameters:

obj (hyperspy.signal_tools.SpikesRemoval) – The spikes removal tool instance.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

microscope_parameters#

Microscope parameter widgets for EELS and EDS using anywidget.

class hyperspy_gui_anywidget.microscope_parameters.ButtonWidget(*args: t.Any, **kwargs: t.Any)[source]#

hyperspy_gui_anywidget.microscope_parameters.eds_sem_microscope_parameter_aw(obj, **kwargs)[source]#

Build a widget for EDS SEM microscope parameters.

Parameters:

obj (hyperspy.microscope_parameters.MicroscopeParameters) – The EDS SEM microscope parameters object.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.microscope_parameters.eds_tem_microscope_parameter_aw(obj, **kwargs)[source]#

Build a widget for EDS TEM microscope parameters.

Parameters:

obj (hyperspy.microscope_parameters.MicroscopeParameters) – The EDS TEM microscope parameters object.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None

hyperspy_gui_anywidget.microscope_parameters.eels_microscope_parameter_aw(obj, **kwargs)[source]#

Build a widget for EELS microscope parameters.

Parameters:

obj (hyperspy.microscope_parameters.MicroscopeParameters) – The EELS microscope parameters object.
**kwargs – Passed through to the widget builder.

Returns:

{"widget": ContainerWidget, "wdict": {...}} when display=False, otherwise None (widget displayed inline).

Return type:

dict or None