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. A user guide for creating new interactive tools will be available in the future. In the meantime, take a look at the source code of erlab.interactive.utils and erlab.interactive.colors which provide general utility functions for creating new interactive tools.

Modules

imagetool

Interactive visualization tool for multidimensional image-like data.

bzplot

colors

Functions for manipulating colors in Qt.

curvefittingtool

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.goldtool(data, data_corr=None, *, data_name=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.

  • 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

      Every DataArray in the Dataset will be displayed across multiple ImageTool windows. 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.

  • 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 | None, default: None) –

    Whether to open the ImageTool window(s) using the ImageToolManager if it is running. 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.

  • 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:
      • A valid index of an existing ImageTool window:

        The data in the window with the specified index is replaced with the new data.

      • A number that is greater by 1 than the largest existing index:

        A new ImageTool window is created with the new data. This is useful when you want to add a new window on initial execution, but want to replace the window with the same index on subsequent calls.

      • A negative integer:

        The index is interpreted as an index from the end of the list of existing ImageTool windows, sorted by their indices. For example, -1 refers to the window with the largest index, -2 to the second largest, and so on.

    • A list of integers:

      A list of integers specifying the indices of the windows to be replaced, each of which is interpreted as described above. The length of the list 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.core.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, cmap=None, gamma=None, *, data_name=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) 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.

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

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.