Other interactive tools¶

In addition to ImageTool and the ImageTool manager, other interactive tools for specific tasks are available in the erlab.interactive module.

Most of these tools can be opened from within ImageTool, and are also integrated into the ImageTool manager, allowing you to manage them alongside your ImageTool windows.

When a tool is launched from an ImageTool that is open in the manager, the manager can show the tool as a child row under that ImageTool. ImageTool windows opened from the tool can also appear as child rows under the tool instead of as unrelated top-level windows. This keeps the data in the ImageTool that opened the tool, the tool settings, update status, and code for repeating the steps together; see Nested windows, Automatic updates, and Operation history.

More interactive tools will be added in the near future.

Here are some of the miscellaneous interactive tools provided:

ktool¶

Interactive conversion from angles to momentum space. ktool supports constant-energy alpha/beta maps, angle-energy alpha/eV cuts with a fixed beta coordinate, and 3D angle volumes.

There are four ways to start ktool.

xarray.DataArray.kspace.interactive()
```
data.kspace.interactive()
```
erlab.interactive.ktool()

This option is recommended because the name of the input data will be automatically detected and applied to the generated code that is copied to the clipboard.
```
import erlab.interactive as eri

eri.ktool(data)
```
From the ImageTool View menu

Click View → Open ktool.

The button will be disabled if the data is not compatible with ktool.

When the ImageTool data contains both alpha and beta dimensions, the normal emission values are set from the active cursor position.

If a rotation guideline is visible on the main image, the guideline’s angle and center will be applied instead.
From IPython using the %ktool magic described in Notebook shortcuts.

The GUI is divided into two tabs.

The first tab is for setting momentum conversion parameters. The image is updated in real time as you change the parameters. For angle-energy cuts, the preview keeps the full energy axis and displays the converted k/eV cut.

Clicking Copy code will copy the code for conversion to the clipboard.

Open in ImageTool performs a full conversion. When ktool was opened from an ImageTool in the manager, the converted data opens as a child row under ktool; outside the manager, it opens as a normal standalone ImageTool window.

The second tab provides visualization options. You can overlay Brillouin zones and high symmetry points on momentum-momentum or momentum-kz previews, adjust colors, and optionally preview n-fold symmetrized constant energy contours for maps. Brillouin-zone and symmetry previews are disabled for angle-energy cuts.

Note

The symmetrization preview uses the same rotational averaging as erlab.analysis.transform.symmetrize_nfold(), but it only affects the displayed image in ktool. Open in ImageTool and Copy code still use the unsymmetrized momentum-converted data.

The Add Circle ROI button allows you to add a circular region of interest to the image, which can be edited by dragging or right-clicking on it.

You can pass some parameters to customize the GUI. For example, you can set the Brillouin zone size/orientation and the colormap like this:

data.kspace.interactive(
    avec=np.array([[-3.485, 6.03], [6.97, 0.0]]), rotate_bz=30.0, cmap="viridis"
)

For all available parameters, see the documentation for erlab.interactive.ktool().

dtool¶

Interactive tool for visualizing dispersive data using derivative-based methods.

dtool can be started with erlab.interactive.dtool():

import erlab.interactive as eri

eri.dtool(data)

It can also be opened from the right-click context menu of any image plot in ImageTool.

The %dtool line magic (see Notebook shortcuts) provides the same entry point from notebooks.

The first section interpolates the data to a grid prior to smoothing.
The second section applies smoothing prior to differentiation.
In the third section, selecting different tabs will apply different methods. Each tab contains parameters relevant to the selected method.
Clicking the copy button will copy the code for differentiation to the clipboard.
Both the smoothed data and the result can be opened in ImageTool from the right-click menu of each plot, where it can be analyzed further or saved to disk. When dtool was opened from an ImageTool in the manager, these ImageTool windows stay under dtool in the manager tree and can be updated when the ImageTool that opened dtool changes.

goldtool¶

Interactive tool for obtaining the shape of the Fermi edge (e.g., from a gold reference spectrum).

goldtool can be started with erlab.interactive.goldtool():

import erlab.interactive as eri

eri.goldtool(data)

It can also be opened from the right-click context menu of any image plot in ImageTool.

Use the %goldtool magic (see Notebook shortcuts) to launch it directly from IPython.

When goldtool is opened from an ImageTool in the manager, it remembers the selected spectrum or slice that opened it. If that ImageTool changes, the manager can mark the tool and its corrected ImageTool window as Stale. Enable Refit after update when you want the edge fit to rerun automatically after compatible updates.

ftool¶

Interactive curve-fitting tool for 1D and 2D data. By default uses erlab.analysis.fit.models.MultiPeakModel, but you can pass any 1D lmfit model.

There are three ways to start ftool.

erlab.interactive.ftool()

import erlab.interactive as eri

eri.ftool(data)

To supply a custom model:

eri.ftool(data, model=my_model)

From the ImageTool context menu

Right-click an image plot or line plot and choose ftool.
From IPython using the %ftool magic described in Notebook shortcuts.
```
%ftool data
%ftool --model my_model data
```

When ftool is opened from an ImageTool in the manager, it remembers the slice or line cut that opened it. If that ImageTool changes, the manager can update the tool from the latest compatible data. Enable Refit after update when the same fit should rerun after updates. For 2D fits, parameter maps opened in ImageTool appear as child rows under ftool.

Overview¶

When you first open ftool, you will see a stack of controls on the left and a plot on the right, as shown below. The controls have two tabs: Setup and Fit.

Setup

Fit

The main plot shows the data with the fit overlay, plus dashed vertical lines that define the current fit window.
- Check Plot components to show individual model components (if any). This also adds a legend for each curve. You can show/hide a component by clicking its legend entry.
The left panel contains controls for setting up and performing the fit. The Setup tab is for choosing the model and preprocessing options, while the Fit tab contains parameter settings and options related to the fitting process.

Models and options¶

First, use the Model drop-down to choose a predefined model, a user-provided model, or a model loaded from disk.

Built-in options are:
From file loads a lmfit model saved with lmfit.model.save_model().

Some models have additional options that appear below the model selector that are used to initialize the model:

MultiPeakModel:
- # Peaks and Peak shape define how many components are fit and whether they are Lorentzian or Gaussian.
- Background and Degree add a constant, linear, or polynomial background.
- Fermi-Dirac multiplies the peaks by a Fermi-Dirac distribution.
- Convolve applies instrumental broadening; Oversample controls the internal sampling density used for the convolution.
ExpressionModel:
- Edit the independent variable name in the f(...) header and type your formula in the expression box (e.g., a * x + b).
- Click Apply to rebuild the model from the current expression.
- Use Edit init script… to define helper functions or constants used in the expression.
- For more information, see the documentation for lmfit.models.ExpressionModel.

Workflow for 1D data¶

Choose your model, and set any model-specific options.
In the Preprocess group, set the fit window using X range or drag the dashed vertical bounds in the plot.

You may also choose to divide the data by its average value for better numerical stability.
Now, move on to the Fit tab.

In the Parameters group, click Guess to get initial parameters, then refine them.

You can edit parameter values, bounds, and other settings directly in the table.

You can also use the slider to adjust parameter values interactively.
Note
- Guess uses the model’s built-in guessing method (if implemented) to generate initial parameter values based on the data in the fit window. This overwrites all current parameter values.
- Any adjustment can be undone & redone with standard keyboard shortcuts.
- You can right-click parameters in the table to assign/remove expressions.
  
  For instance, to tie the position of peak 1 (p1_center) to be always 0.1 units above than peak 0 (p0_center), right-click p1_center, choose Set expression…, and enter p0_center + 0.1.
- Hover over rows in the parameter table to see tooltips with additional information.
- You can choose to fix a parameter value to be equal to a coordinate variable in the data (e.g., get the temperature from a sample_temp coordinate) by changing the Mode in the Parameter panel.
- When using MultiPeakModel, checking Plot components also shows lines at the peak centers in addition to the component curves.
  
  These lines can be dragged to quickly adjust peak positions and heights. Dragging vertically changes the height, while dragging horizontally changes the center position. Dragging vertically while holding the right mouse button changes the peak width.
Click Fit to perform the fit.

If the fit fails to converge or gives unsatisfactory results, adjust the parameters and try again.

If you want to retry automatically, use Fit×20. You can increase Max nfev in the Fit options group, which sets the maximum number of function evaluations allowed. The nfev stat is highlighted in red when the fit hits this limit without converging.

About Fit ×20

Fit ×20 performs a sequence of 20 fits on the same data. After each run, the fitted parameters are fed back in as the initial parameters for the next run. This can help in nonlinear or highly correlated models where a single fit gets close but not fully converged. Reusing the previous best-fit parameters often nudges the optimizer into a better solution without you having to manually tweak values between runs.
Use Copy code to copy the reproducible code for this fit to the clipboard, or use Save fit to save the results with xarray_lmfit.save_fit(). In the manager, the side panel can also show code for the ImageTool selections and tool steps that led to the fit.

Workflow for 2D data¶

For 2D data, an additional image and a parameter-versus-coordinate plot are shown, along with a Transpose button and index navigation controls.

Setup

Fit

For 2D data, the tool fits a stack of 1D curves.

Check if the data dimensions are in the correct order. The axis you wish to sweep along is the vertical axis; if the image is rotated 90 degrees from what you expect, click Transpose to swap the axes.
Set the X window with X range or by dragging the vertical dashed lines.
Choose the Y range to fit: use the Y range spin boxes or drag the horizontal dashed lines in the image.
Pick a representative Y index with Index (or drag the yellow cursor), then tune the fit parameters for that slice like in the 1D workflow above. Once you are satisfied with the fit, proceed to the next step.
Decide how parameters propagate between EDCs using Fill mode.
- Previous keeps the last good parameters.
- Extrapolate linearly projects parameters from the previous two slices.
- Use None when all slices already have reasonable initial parameters, and you just want to fit them all without parameter propagation.
Start the 2D sequence with Fit ⤒ or Fit ⤓. The tool will step through the selected range while populating the parameters according to the chosen mode.
Inspect the parameter plot to verify trends. If a slice fails, move to it with Index, fix the parameters, then continue the sequence.
When all indices in the range are fitted, click Save fit to export the combined results or Copy code to generate reproducible code for the full 2D fit. These buttons are only enabled after the full sequence is complete. When ftool is open in the manager, parameter maps opened in ImageTool appear as child rows under ftool.

Reopening saved fits¶

You can reopen a saved fit by loading the dataset with xarray_lmfit.load_fit() and passing it directly to erlab.interactive.ftool().

Saved fits restore the stored data, the serialized model (when available), and the fitted parameter values. For 2D fits, all slices must share the same model definition.

Note

The data is cropped to the fit range used during saving, so reopening a saved fit will only show the data within the fit window used when the fit was saved. To preserve the full data in the ImageTool window, ftool settings, fit result, and any ImageTool windows opened from ftool, open ftool from data in the ImageTool manager and save as a workspace.

restool¶

Interactive tool for fitting a single resolution-broadened Fermi-Dirac distribution to an energy distribution curve (EDC). The momentum range to be integrated over can be adjusted interactively. This is useful for quickly determining the energy resolution of the current experiment.

The GUI can be invoked with erlab.interactive.restool():

import erlab.interactive as eri

eri.restool(data)

It can also be opened from the ImageTool image-plot context menu when the data contains an energy axis.

The %restool magic (see Notebook shortcuts) provides a quick way to launch it from IPython.

When restool is launched from an ImageTool in the manager, it remembers the selected EDC that opened it. If that ImageTool is replaced with compatible data, the manager can update the tool and optionally rerun the fit when Refit after update is enabled.

meshtool¶

Interactive tool for removing grid-like mesh artifacts from fixed mode ARPES data.

The GUI can be invoked with erlab.interactive.meshtool():

import erlab.interactive as eri

eri.meshtool(data)

It can also be opened from the ImageTool View menu with View → Open meshtool.

The %meshtool magic (see Notebook shortcuts) provides a quick way to launch it from IPython.

This tool accepts any DataArray with eV and alpha dimensions. When additional dimensions are present, the data will be averaged over those dimensions to detect the mesh pattern. meshtool then applies the detected mesh parameters to the full input DataArray.

The first checkbox enables/disables undoing of software edge correction for straight analyzer slits that some analyzers apply automatically (currently only tested with Scienta DA30L).
In the next section, you must specify the location of the first order mesh peaks in the FFT of the data.
- Drag the two yellow targets on the FFT plot over the two first order mesh peaks by dragging them with the mouse.
- Alternatively, an automatic search can be performed by clicking Find under Auto locate peaks.
In the final section, several parameters for mesh removal are provided. For more information on these parameters, see the documentation for erlab.analysis.mesh.remove_mesh(). You may have to experiment with these parameters to achieve optimal results for your dataset.
Once you are satisfied with the parameters, click Go! to perform mesh removal.

If you open the corrected data in ImageTool from a meshtool that was opened from an ImageTool in the manager, the new ImageTool window is kept as a child row under meshtool in the manager tree. The manager side panel can then show the data in the ImageTool that opened meshtool and the code for repeating the mesh-removal steps.

Note

Mesh removal is currently experimental and may not work well for all datasets, and may introduce unwanted artifacts. Please use with caution and verify the results carefully.

Data explorer¶

Provides a file-browser-like interface for exploring and visualizing ARPES data stored on your disk.

For most day-to-day browsing and loading, this is faster than the interactive summary table described in the I/O guide. Use the summary table when you want the overview as a DataFrame inside Python or when you are implementing loaders.

You can open the explorer in several ways:

From the ImageTool manager with File → Data Explorer or Ctrl+E.
From Python with erlab.interactive.data_explorer().
From the command line with python -m erlab.interactive.explorer.

Browsing directories and previewing metadata works in the standalone explorer. Opening selected files into ImageTool analysis requires a running ImageTool manager. Launching the explorer from the manager is therefore the recommended path for users who want to find a dataset and start working with it immediately.

Periodic table¶

GUI that shows the periodic table of the elements. It provides information on orbital configurations, atomic mass, x-ray absorption edges (core-level binding energies) and photoionization cross sections for individual elements, which are useful for planning and interpreting core-level measurements.

ptable can be started with erlab.interactive.ptable():

import erlab.interactive as eri

eri.ptable()

It can also be started directly from the command line:

python -m erlab.interactive.ptable

In the ImageTool manager, you can open it from Apps → Periodic Table or with the keyboard shortcut Ctrl+Shift+P.

The search bar highlights matching elements by symbol or name and offers autocomplete suggestions that select the chosen element. Entering a comma- or space-separated list of exact symbols adds a multi-selection entry that selects all listed elements at once.
Hovering an element previews it in the side panel.
Clicking selects one element, and Ctrl/Cmd-click adds or removes elements from the selection. Clicking the table background clears the selection, and arrow keys move the current selection.
The spreadsheet below the periodic table lists x-ray absorption edges, which include core-level binding energies for each element. When a photon energy is entered, the table can also show kinetic energies.
Use Harmonics up to to calculate the kinetic energies for additional higher harmonics of the photon energy.
The side panel includes a log-log plot of photoionization cross sections for the selected element. If a photon energy is entered, the plot can also show markers for the fundamental and higher harmonics.

BZPlotter¶

This tool is not an analysis tool, but rather a utility for creating plots of three-dimensional Brillouin zones and exporting them as vector graphics.

The GUI can be invoked with erlab.interactive.bzplot.BZPlotter:

import erlab.interactive as eri

eri.bzplot.BZPlotter()

Once opened, a matplotlib figure window will appear alongside a control panel for adjusting the lattice parameters. The figure can be rotated interactively using the mouse, and the plot can be exported as any of the formats supported by matplotlib via the standard matplotlib save button.

Notebook shortcuts¶

Loading the erlab.interactive IPython extension (%load_ext erlab.interactive) registers convenient line magics for quickly launching the various interactive tools from within a Jupyter notebook or IPython console.

%ktool --cmap viridis darr.sel(eV=0)

%dtool darr

%goldtool darr.isel(beta=1)

%restool darr.mean(dim='kx')

%ftool --model my_model darr