Interactive (erlab.interactive)

Interactive tools based on Qt and pyqtgraph.

This module provides interactive tools for plotting and analyzing ARPES data. See the sidebar on the right for a list of available tools.

Commonly used tools are available directly in the erlab.interactive namespace, so regular users should not need to import the submodules directly.

Documentation of classes and functions in submodules mostly contain implementation details for advanced users who want to create new interactive tools. See Authoring interactive tools for a contributor-oriented walkthrough, and use the source code of erlab.interactive.utils and erlab.interactive.colors as the main reference implementations.

Modules

imagetool

Interactive visualization tool for multidimensional image-like data.

bzplot

colors

Functions for manipulating colors in Qt.

derivative

Interactive tool for visualizing dispersive data.

explorer

Quickly browse and load ARPES data files with a file manager-like interface.

fermiedge

kspace

Interactive momentum conversion tool.

utils

Various helper functions and extensions to Qt and pyqtgraph.
erlab.interactive.data_explorer(directory=None, loader_name=None, *, execute=None)[source]

Start the data explorer.

Data explorer is a tool to browse and load ARPES data files with a file manager-like interface. Data attributes of supported files can be quickly inspected, and can be loaded into ImageTool manager for further analysis.

The data explorer can be started from the command line as a standalone application with the following command:

python -m erlab.interactive.explorer

Also, it can be opened from the GUI by selecting “File” -> “Data Explorer” or by pressing Ctrl+E in ImageTool manager.

Parameters:

  • directory (str | PathLike | None, default: None) – Initial directory to display in the explorer.

  • loader_name (str | None, default: None) – Name of the loader to use to load the data. The loader must be registered in erlab.io.loaders.

erlab.interactive.dtool(data, data_name=None, *, execute=None)[source]

Interactive tool for visualizing dispersive data.

This tool can also be accessed from the right-click context menu of an image plot in an ImageTool window.

Parameters:

  • data (DataArray) – Data to visualize. Must be a 2D DataArray with no NaN values.

  • data_name (str | None, default: None) – Name of the data variable in the generated code. If not provided, the name is automatically determined.

erlab.interactive.ftool(data, model=None, params=None, *, data_name=None, model_name=None, execute=None)[source]

Launch an interactive fitting tool.

The tool provides an interactive GUI for fitting 1D models to 1D or 2D data.

See the user guide for more information on using the tool.

Parameters:

  • data (DataArray | Dataset) – The 1D or 2D data to fit. Also accepted is a fit result xarray.Dataset, from which the data to fit will be extracted. In this case, the tool will attempt to restore the fit state from the dataset.

  • model (Model | None, default: None) – The model to fit to the data. If None, MultiPeakModel will be used.

  • params (Parameters | dict[str, Any] | None, default: None) – Initial parameters for the fit. If None, parameters will be initialized from the model. If data is 2D, params can be a dictionary that is interpreted like the params argument of xarray.DataArray.xlm.modelfit().

  • data_name (str, optional) – The name of the data variable, used in code generation. If None, an attempt will be made to infer the name from the calling context.

  • model_name (str, optional) – The name of the model variable, used in code generation. If None, an attempt will be made to infer the name from the calling context.

erlab.interactive.goldtool(data, data_corr=None, *, data_name=None, execute=None, **kwargs)[source]

Interactive tool for correcting curved Fermi edges.

This tool can also be accessed from the right-click context menu of an image plot in an ImageTool window.

Parameters:

  • data (DataArray) – The data to perform Fermi edge fitting on. Must be a 2D DataArray with an ‘eV’ dimension.

  • data_corr (DataArray | None, default: None) – The data to correct with the edge. Defaults to data.

  • data_name (str | None, default: None) – Name of the data used in generating the code snipped copied to the clipboard. Overrides automatic detection.

  • **kwargs – Arguments passed onto erlab.interactive.utils.AnalysisWindow.

erlab.interactive.itool(data, *, link=False, link_colors=True, manager=None, replace=None, execute=None, **kwargs)[source]

Create and display ImageTool windows.

This tool can also conveniently accessed with xarray.DataArray.qshow() and xarray.Dataset.qshow().

Parameters:

  • data (DataArray, Dataset, DataTree, numpy.ndarray, list of DataArray or list of numpy.ndarray) –

    The data to be displayed. Data can be provided as:

    • A xarray.DataArray with 2 to 4 dimensions

      The DataArray will be displayed in an ImageTool window.

    • A numpy array with 2 to 4 dimensions

      The array will be converted to a DataArray and displayed in an ImageTool.

    • A list of the above objects

      Multiple ImageTool windows will be created and displayed.

    • A xarray.Dataset

      If the Dataset contains multiple displayable DataArrays, ImageTool asks which variables to open. Data variables that have less than 2 dimensions or more than 4 dimensions are ignored. Dimensions with length 1 are automatically squeezed.

    • A xarray.DataTree

      Every leaf node will be parsed as a xarray.Dataset. If the DataTree contains multiple displayable DataArrays, ImageTool asks which variables to open, grouped by DataTree node path.

  • link (bool, default: False) – Whether to enable linking between multiple ImageTool windows when data is a sequence or a xarray.Dataset, by default False.

  • link_colors (bool, default: True) – Whether to link the color maps between multiple linked ImageTool windows, by default True. This argument has no effect if link is set to False.

  • manager (bool | int | None, default: None) –

    Whether to open the ImageTool window(s) using the ImageToolManager if it is running. An integer targets a specific 0-based manager index. If True, the current process default manager is used, or the only live manager if no default is set. If multiple managers are live and no default has been selected, an error is raised. If not provided, the manager will only be used if it is in the same process as the caller.

    Changed in version 3.4.0: Argument renamed from use_manager to manager.

    Changed in version 3.22.0: Integer manager indexes select a specific ImageTool Manager instance.

  • replace (Collection[int] | int | None, default: None) –

    When using the manager, this argument specifies which existing ImageTool windows should be replaced with the new data. If the manager is not used, this argument is ignored. replace can be set to:

    • None (default): no existing windows are replaced. New windows are created for the new data.

    • A single integer: this can be a valid existing index (replace that window), one greater than the current largest index (create a new window), or a negative index from the end (for example, -1 means the largest existing index).

    • A list of integers: each integer is interpreted as described above. The list length must match the number of windows data is expected to create.

    If this argument is used, the link, link_colors, and kwargs arguments are ignored, since no new windows are created.

  • execute (bool | None, default: None) –

    Whether to execute the Qt event loop and display the window, by default None. For more information, see erlab.interactive.utils.setup_qapp().

    This argument has no effect when the ImageTool window(s) are opened in the manager.

  • **kwargs – Additional keyword arguments to be passed onto the underlying slicer area. For a full list of supported arguments, see the erlab.interactive.imagetool.viewer.ImageSlicerArea documentation.

Returns:

ImageTool or list of ImageTool or None – The created ImageTool window(s).

If the window(s) are executed, the function will return None, since the event loop will prevent the function from returning until the window(s) are closed.

If the window(s) are not executed, for example while running in an IPython shell with %gui qt, the function will not block and return the ImageTool window(s) or a list of ImageTool windows depending on the input data.

The function will also return None if the windows are opened in the ImageToolManager.

Return type:

ImageTool | list[ImageTool] | None

Examples

>>> itool(data, cmap="gray", gamma=0.5)
>>> itool([data1, data2], link=True)
erlab.interactive.ktool(data, avec=None, rotate_bz=None, centering=None, *, cmap=None, gamma=None, data_name=None, initial_normal_emission=None, initial_delta=None, execute=None)[source]

Interactive momentum conversion tool.

This tool can also be accessed with DataArray.kspace.interactive(), or from the View menu of an ImageTool window.

Parameters:

  • data (DataArray) – Data to convert. Currently supports constant energy slices (2D data with alpha and beta dimensions), 2D angle-energy cuts with alpha and eV dimensions and a fixed beta coordinate, and all 3D data that has eV and alpha dimensions, including maps and photon energy dependent data.

  • avec (array-like, optional) – Real-space lattice vectors as a 2x2 or 3x3 numpy array. If provided, the Brillouin zone boundary overlay will be calculated based on these vectors. If given as a 2x2 array, the third row and column will be assumed to be all 0. You can use utilities from erlab.lattice to construct these vectors.

  • rotate_bz (float | None, default: None) – Rotation angle for the Brillouin zone boundary overlay.

  • centering (Literal['P', 'A', 'B', 'C', 'F', 'I', 'R'] | None, default: None) – Optional centering type to convert the conventional unit cell into a primitive one. Must be one of "P" (primitive), "A", "B", "C", "I" (body-centered), "F" (face-centered), and "R" (rhombohedral).

  • cmap (str, optional) – Name of the colormap to use.

  • gamma (float | None, default: None) – Initial gamma value for the colormap.

  • data_name (str | None, default: None) – Name of the data variable in the generated code. If not provided, the name is automatically determined.

  • initial_normal_emission (tuple[float, float] | None, default: None) – Optional pair of (alpha, beta) values used once during initialization to seed the normal emission controls and derived angle offsets.

  • initial_delta (float | None, default: None) – Optional delta value to apply alongside initial_normal_emission.

erlab.interactive.meshtool(data, data_name=None, *, execute=None)[source]

Interactive tool for mesh removal.

This tool can also be accessed from the menu in ImageTool.

Parameters:

  • data (DataArray) – Data to extract the mesh from. The data dimensions must include ‘alpha’ and ‘eV’. All other dimensions are averaged over to extract the mesh pattern.

  • data_name (str | None, default: None) – Name of the data variable in the generated code. If not provided, the name is automatically determined.

erlab.interactive.ptable(*, hv=None, workfunction=None, max_harmonic=1, notation=None, execute=None)[source]

Open the periodic table window.

The periodic table provides an interactive reference for XPS-relevant elemental properties, including x-ray absorption edges, ground-state electron configurations, and photoionization cross sections.

See Periodic table for an overview of the features and user interface.

Parameters:

  • hv (float | None, default: None) – Optional photon energy in eV. When given, the inspector also shows kinetic energies and marks the photon energy on the cross-section plot.

  • workfunction (float | None, default: None) – Optional work function in eV used for converting an absorption edge to kinetic energy.

  • max_harmonic (int, default: 1) – Highest harmonic order to include when kinetic energies are shown. Harmonics are integer multiples of hv from 1 through max_harmonic.

  • notation (str | None, default: None) – Initial energy-level notation. When omitted, the most recently used notation is restored. Explicit values should be either "orbital" or "iupac".

  • execute (bool | None, default: None) – Passed through to erlab.interactive.utils.setup_qapp().

Notes

The periodic table combines several reference datasets.

erlab.interactive.restool(data, *, data_name=None, execute=None)[source]

Interactive tool for precise resolution fitting of EDCs.

This tool can also be accessed from the right-click context menu of an image plot in an ImageTool window.

Parameters:

  • data (DataArray) – Data to visualize. Must be a 2D DataArray with an ‘eV’ dimension.

  • data_name (str | None, default: None) – Name of the data variable in the generated code. If not provided, the name is automatically determined.