First notebook¶

This tutorial is for users who can read basic Python and run notebook cells. It introduces the xarray concepts that the workflow uses.

Download this notebook and run it in Jupyter.

Before you start, complete the installation verification. Run this notebook in the same ERLabPy environment.

You will follow one analysis path from simulated angle-resolved data to momentum space and dispersion plots. The fixed simulation makes each result reproducible. You can compare your output with the output on this page.

Analysis path¶

Create a three-dimensional angle-resolved dataset.
Inspect its xarray dimensions, coordinates, and metadata.
Crop the dataset by coordinate values.
Select a constant energy surface and average an energy interval.
Plot constant energy surfaces and energy–angle cuts.
Check the momentum conversion parameters and set the normal emission position.
Convert the angle-resolved data to momentum space and plot constant energy surfaces and energy–momentum cuts.
Overlay the Brillouin zone and extract K–M–K′ and Γ–M–K–Γ cuts.

Imports¶

Import NumPy, xarray, Matplotlib, and ERLabPy.

import matplotlib.pyplot as plt
import numpy as np
import xarray as xr

import erlab.analysis as era
import erlab.plotting as eplt
from erlab.io.exampledata import generate_data_angles

Labeled data and metadata¶

A xarray.DataArray stores one array together with labels and metadata. These parts have different roles:

Dimensions name the array axes. Their order describes the stored layout.
Dimension coordinates give a physical value for each position on an axis.
Scalar coordinates record a fixed condition that applies to the complete array.
Attributes describe the array but do not take part in coordinate selection or alignment.

The DataArray display shows all four parts. You may access each part individually:

xarray.DataArray.dims gives the dimension names in order.

example_map.dims

('alpha', 'beta', 'eV')

xarray.DataArray.shape gives the number of points along each dimension.

example_map.shape

(500, 60, 500)

xarray.DataArray.coords contains the coordinate labels. Here, eV, beta, and alpha label dimensions. Coordinates such as hv, xi, and delta are scalars because they do not vary across this map.

example_map.coords

Coordinates:
  * alpha    (alpha) float64 4kB -15.0 -14.94 -14.88 -14.82 ... 14.88 14.94 15.0
  * beta     (beta) float64 480B -15.0 -14.49 -13.98 -13.47 ... 13.98 14.49 15.0
  * eV       (eV) float64 4kB -0.45 -0.4489 -0.4477 ... 0.1177 0.1189 0.12
    xi       float64 8B 0.0
    delta    float64 8B 0.0
    hv       float64 8B 50.0

xarray.DataArray.attrs contains descriptive metadata. ERLabPy accessors can read known attributes even though xarray does not use them for label-based selection.

example_map.attrs

{'configuration': 1, 'sample_temp': 20.0, 'sample_workfunction': 4.5}

The energy range is -0.45 to 0.12 eV. Both angle ranges are -15° to 15°.

The names and units follow ERLabPy’s ARPES data conventions:

Name	Role in this map	Physical meaning
`eV`	Dimension coordinate	Energy in eV. ERLabPy uses negative values for occupied states.
`alpha`	Dimension coordinate	Emission angle measured along the analyzer slit.
`beta`	Dimension coordinate	Polar mapping angle for this Type 1 configuration.
`hv`	Scalar coordinate	Photon energy in eV.
`configuration`	Attribute	Experimental geometry used for momentum conversion.
`sample_workfunction`	Attribute	Work function in eV used for momentum conversion.

The additional scalar coordinates describe fixed sample angles. sample_temp records the sample temperature.

Inspecting data interactively¶

It is useful to inspect the working data interactively to choose appropriate coordinates and averaging windows.

If Qt is installed, use xarray.DataArray.qshow() to inspect the working data in ImageTool from your local notebook:

analysis_map.qshow()

In the right-click menu of each panel, you can use the Copy selection code to copy the xarray.DataArray.qsel() call required to reproduce the selection in that panel from the original data.

Plotting two-dimensional data¶

Use Matplotlib to create the axes and ERLabPy to plot and annotate the data:

matplotlib.pyplot.subplots() creates the figure and its axes.
erlab.plotting.plot_array() draws a two-dimensional DataArray.
erlab.plotting.fermiline() marks the Fermi level at eV=0.
erlab.plotting.set_titles() applies titles to several axes.

The dimension order determines the default plot axes. The surface has dimensions beta and alpha. The cut has dimensions eV and alpha. Use the same intensity color map for both panels. Mark the selected beta value on the constant energy surface and the averaged energy interval on the cut.

fig, axes = plt.subplots(
    1, 2, figsize=(6.4, 2.8), layout="compressed", width_ratios=(1.0, 1.35)
)

eplt.plot_array(
    angle_constant_energy.T, ax=axes[0], cmap="Greys", gamma=0.7, aspect="equal"
)
axes[0].axhline(angle_energy_cut.beta, color="tab:red", linestyle="--", linewidth=0.8)

eplt.plot_array(angle_energy_cut.T, ax=axes[1], cmap="Greys", gamma=0.7)
axes[1].axhspan(-0.31, -0.29, color="tab:red", alpha=0.15)
eplt.fermiline(ax=axes[1], color="0.35", linestyle="--", linewidth=0.8)

eplt.set_titles(axes, ["Constant energy surface", "Energy–angle cut"])

../../_images/91d09f40668cb670af8f8a8b03dc6782253a1b5b6534cf53e25146aaaf5c8b5d.svg

In order to plot alpha on the horizontal axis, the data are transposed with .T prior to plotting.

The left panel has alpha on the horizontal axis and beta on the vertical axis. Both axes use degrees, so an equal aspect ratio is meaningful. The right panel has alpha on the horizontal axis and eV on the vertical axis. Its gray dashed line marks eV=0.

The red dashed line on the constant energy surface marks the selected beta value. The red band on the cut marks the 0.02 eV averaging interval used for the constant energy surface. gamma applies a power-law normalization to the displayed colors without changing the DataArray values.

Constant energy surfaces¶

Use erlab.plotting.plot_slices() to compare constant energy surfaces at several energies. The function performs the requested xarray.DataArray.qsel() selections and arranges the panels. Here, each panel uses the same 0.02 eV averaging width. Each panel has independent color limits so that changes in the contours remain visible.

fig, axes = eplt.plot_slices(
    analysis_map,
    figsize=(6.4, 2.3),
    eV=[-0.4, -0.2, 0.0],
    eV_width=0.02,
    cmap="Greys",
    gamma=0.7,
    axis="image",
)

../../_images/b528d15871e3e5e10902f552b6def60ce25689e311ec4a9fd5c269dfc2e7bb66.svg

The automatic labels give the center of the energy window for each panel.

Momentum conversion parameters¶

Momentum conversion uses these parameters:

The experimental configuration defines the relation between the measured angles and kx and ky.
The photon energy and sample work function determine the photoelectron kinetic energy.
The normal emission position sets zero in-plane momentum.

The generated data already contains the configuration, photon energy, and work function. You inspected these values in the coordinate and attribute displays above.

For this simulation, normal emission is alpha=beta=delta=0.0. For experimental data, determine normal emission from the measurement geometry, a known symmetry point, or a separate calibration. An intensity maximum alone does not identify normal emission.

Use xarray.DataArray.kspace.set_normal() to store the normal emission position in the data. The method converts this position to the angular offsets for the selected configuration. xarray.DataArray.kspace.offsets shows the stored offsets.

analysis_map.kspace.set_normal(alpha=0.0, beta=0.0, delta=0.0)

analysis_map.kspace.offsets

delta	0.0
xi	0.0
beta	0.0
normal alpha	0.0
normal beta	0.0

xarray.DataArray.kspace.convert() uses the momentum conversion functions and interpolates the intensity onto a regular momentum grid.

Here, ERLabPy automatically selects the momentum bounds and grid spacing.

The result should have dimensions kx, ky, and eV.

Conversion to momentum space¶

Select the same energy and averaging width before and after momentum conversion. Plot the two constant energy surfaces together. This comparison shows how the angular coordinates map to a regular kx, ky grid.

momentum_constant_energy = momentum_data.qsel(eV=-0.3, eV_width=0.02).T

fig, axes = plt.subplots(1, 2, figsize=(6.4, 3.0), layout="compressed")

eplt.plot_array(angle_constant_energy, ax=axes[0], aspect="equal")
eplt.plot_array(momentum_constant_energy, ax=axes[1], aspect="equal")
eplt.set_titles(axes, ["Angle coordinates", "Momentum coordinates"])

../../_images/1a7ef09b566df82a67774a5e62a8171cd253b5d22624b35c74764a25811ac62c.svg

The left panel has alpha and beta axes in degrees. The right panel has kx and ky axes in Å⁻¹. Momentum conversion changes the coordinates and interpolates the intensity.

Slices of multidimensional data¶

Use erlab.plotting.plot_slices() to make one summary figure from the converted data. The first row contains constant energy surfaces. The second row contains energy–momentum cuts at fixed ky. Each cut averages over a 0.04 Å⁻¹ window.

fig, axes = plt.subplots(
    2,
    3,
    layout="compressed",
    sharex=True,
    sharey="row",
)

eplt.plot_slices(
    [momentum_data],
    eV=[-0.4, -0.2, 0.0],
    eV_width=0.02,
    transpose=True,
    axes=axes[0],
    axis="image",
)
eplt.plot_slices(
    [momentum_data],
    ky=[0.0, 0.1, 0.3],
    ky_width=0.04,
    transpose=True,
    axes=axes[1],
)
eplt.clean_labels(axes)

../../_images/a15ed6de1503419dec7ec6dacfb986dce1f6accafb160888662744fa30844fdf.svg

The constant energy surfaces show the change in contour shape. The cuts show how the dispersion changes with ky. Each panel has independent color limits.

Next steps¶

You started with simulated ARPES data and learned how to conduct basic analysis.

To try this out on your own data, use Data loading and saving, Data inspection and selection, Plotting gallery, and Momentum conversion. Complete function and parameter descriptions are in Reference.

To learn more about the concepts and design choices of this library, read Explanation, ARPES data conventions, and Momentum conversion.

First notebook¶

Analysis path¶

Imports¶

Example ARPES data¶

Labeled data and metadata¶

Coordinate selection and averaging¶