ARPESPlots

crosshair_heatmap(A::AbstractDimArray{T,3} where T,
                  stack_dim::Union{DimensionalData.Dimension, Symbol};
                  kwargs...) -> Figure

Create an interactive 2D heatmap with a crosshair cursor, side-panel line profiles, and a slider to step through slices of a 3D data array.

The 3D array is treated as a stack of 2D heatmaps along stack_dim. All crosshair and profile features from the 2D method are available; the extra slider selects which 2D slice is displayed.

Arguments

• A::AbstractDimArray{T,3}: 3D data array with DimensionalData dimensions.
• stack_dim: The dimension along which to slice (e.g., Dim{:hv} or :hv).

Keyword Arguments

• figure::NamedTuple = (;): Passed to Makie.Figure.
• axis_top::NamedTuple = (;): Attributes for the top (X-profile) axis.
• axis_right::NamedTuple = (;): Attributes for the right (Y-profile) axis.
• heatmap_kwargs...: Additional keyword arguments forwarded to heatmap!.

Layout

Same 2×2 grid as the 2D method, plus a SliderGrid with three sliders:

1. Horizontal radius (pts) — half-width of the x-direction integration band.
2. Vertical radius (pts) — half-width of the y-direction integration band.
3. Stack index — selects the active 2D slice along stack_dim.

The label in the top-right corner also shows the current value of stack_dim.

Example

using DimensionalData, ARPESPlots, GLMakie

A = DimArray(
    rand(100, 80, 5),
    (Dim{:phi}(range(-10, 10, 100)), Dim{:eV}(range(0, 8, 80)), Dim{:hv}([100, 105, 110, 115, 120])),
)
fig = crosshair_heatmap(A, :hv)
display(fig)

See also: crosshair_heatmap (2D method).

crosshair_heatmap(A::AbstractDimArray{T,2} where T; kwargs...) -> Figure
crosshair_heatmap(A::AbstractDimArray{T,3} where T,
                  stack_dim::Union{DimensionalData.Dimension, Symbol};
                  kwargs...) -> Figure

Create an interactive heatmap with a linked crosshair cursor and side-panel line profiles for exploring ARPES data.

The 2D method plots A directly. The 3D method treats A as a stack of 2D heatmaps along stack_dim and adds a slider to step through the slices.

Arguments

• A: 2D or 3D data array with DimensionalData dimensions.
• stack_dim (3D only): Dimension along which to slice (e.g., Dim{:hv} or :hv).

Keyword Arguments

• figure::NamedTuple = (;): Passed to Makie.Figure (e.g., size = (900, 600)).
• axis_top::NamedTuple = (;): Attributes for the top (X-profile) axis.
• axis_right::NamedTuple = (;): Attributes for the right (Y-profile) axis.
• heatmap_kwargs...: Additional keyword arguments forwarded to heatmap! (e.g., colormap = :inferno, colorrange = (0, 1)).

Layout

┌─────────────┬──────────┐
│  ax_top     │  label   │  row 1 (25 %)
├─────────────┼──────────┤
│  ax_main    │ ax_right │  row 2
├─────────────┴──────────┤
│  SliderGrid            │  row 3
└────────────────────────┘

• ax_main: central heatmap; crosshair updates as the mouse moves.
• ax_top: X-direction profile, averaged over the vertical integration band.
• ax_right: Y-direction profile, averaged over the horizontal integration band.
• SliderGrid: sliders control the half-width (in index points) of the integration bands. The 3D method adds a third Stack index slider.

Features

• Mouse movement over ax_main updates ax_top and ax_right in real-time.
• ax_main is linked to ax_top (x-axis) and ax_right (y-axis).
• A label in the top-right corner shows the current coordinates, integration range, and averaged intensity. The 3D method also shows the current stack_dim value.
• When a slider value is non-zero, a shaded span is drawn on ax_main to visualise the integration region.

Examples

2D

using DimensionalData, ARPESPlots, GLMakie

A = DimArray(rand(100, 80), (Dim{:phi}(range(-10, 10, 100)), Dim{:eV}(range(0, 8, 80))))
fig = crosshair_heatmap(A; colormap = :inferno)
display(fig)

3D

using DimensionalData, ARPESPlots, GLMakie

A = DimArray(
    rand(100, 80, 5),
    (Dim{:phi}(range(-10, 10, 100)), Dim{:eV}(range(0, 8, 80)), Dim{:hv}([100, 105, 110, 115, 120])),
)
fig = crosshair_heatmap(A, :hv)
display(fig)

Notes

• On WGLMakie, this function may be slow for large arrays due to the overhead of

real-time interactivity. For better performance, consider using GLMakie or CairoMakie backends.

waterfall_dispersion!(ax::AbstractAxis, A::ARPESData; stack_dim=:phi, scale_factor=1.0, cmap=:turbo, mode=:line, alpha=nothing, axis_right=(;))
waterfall_dispersion!(ax::AbstractAxis, A::AbstractDimArray, stack_dim; scale_factor=1.0, cmap=:turbo, mode=:line, alpha=nothing, axis_right=(;))
waterfall_dispersion!(ax::Axis3, A::AbstractDimArray, stack_dim; cmap=:turbo, mode=:line, alpha=nothing)

Plot a waterfall dispersion into an existing axis, showing multiple slices of a 2D AbstractDimArray stacked with vertical offsets (2D axis variants) or as 3D ribbon lines (Axis3 variant).

Arguments

• ax: Target axis — an AbstractAxis (2D) or Axis3 (3D).
• A: 2D dimensional array to plot.
• stack_dim::Union{DimensionalData.Dimension,Symbol}: Dimension along which to slice. Defaults to :phi when A is an ARPESData.
• scale_factor::Real = 1.0: Vertical offset multiplier between slices (2D only).
• cmap = :turbo: Colormap / Color applied across slices.
• mode::Symbol = :line: Rendering mode — :line (lines only), :fill (lines + colored bands), or :hide (lines + white bands to mask lower slices).
• alpha::Union{Real,Nothing} = nothing: Opacity for band elements; defaults to 0.5 (:fill) or 1.0 (:hide) when nothing.
• axis_right::NamedTuple = (;): Keyword arguments forwarded to the secondary right-hand Axis (2D only; ignored for Axis3).
• kwargs...: Additional keyword arguments forwarded to lines! (e.g. linewidth, linestyle).

Returns

• 2D variants: (Vector{AbstractPlot}, Axis) — plotted line objects and the linked right-hand axis whose ticks reflect the original stacking-dimension values.
• Axis3 variant: Vector{AbstractPlot} — plotted line objects.

Description

Each slice along stack_dim is drawn as a line (and optionally a band) offset vertically by

offset = scale_factor * abs(stack_axis[i] - stack_axis[end])

so that the first slice sits highest and the last slice sits at the baseline. Slices are colored by sampling cmap uniformly across the number of slices.

For the 2D variants a secondary right-hand Axis is created and linked to the left axis, with tick values drawn from the actual stacking-dimension coordinates.

Examples

using DimensionalData, GLMakie

E  = range(-2.0, 0.0, length=200)
kx = range(-1.0, 1.0, length=40)
A  = DimArray(rand(200, 40), (X(E), Y(kx)))

fig = Figure()
ax  = Axis(fig[1, 1], xlabel="Energy (eV)", ylabel="Intensity (arb. u.)")
plots, ax_right = waterfall_dispersion!(ax, A, :Y; scale_factor=0.05, cmap=:viridis)
ax_right.ylabel = "kx (Å⁻¹)"
display(fig)

waterfall_dispersion(A, stack_dim; scale_factor=1.0, cmap=:turbo, mode=:line, alpha=nothing, figure=(;), axis=(;), axis_right=(;))

Create a waterfall dispersion plot, returning a Makie.FigureAxisPlot.

Arguments

• A::AbstractDimArray: 2D dimensional array to plot.
• stack_dim::Union{DimensionalData.Dimension,Symbol}: Dimension along which to slice.
• scale_factor::Real = 1.0: Vertical offset multiplier between slices.
• cmap = :turbo: Colormap /color applied across slices.
• mode::Symbol = :line: Rendering mode — :line, :fill, or :hide.
• alpha::Union{Real,Nothing} = nothing: Band opacity; defaults to 0.5 (:fill) or 1.0 (:hide) when nothing.
• figure::NamedTuple = (;): Keyword arguments forwarded to Figure (e.g. size=(800,600)).
• axis::NamedTuple = (;): Keyword arguments forwarded to the left Axis (e.g. xlabel="Energy (eV)").
• axis_right::NamedTuple = (;): Keyword arguments forwarded to the linked right-hand Axis.
• kwargs...: Additional keyword arguments forwarded to lines! (e.g. linewidth, linestyle).

Returns

• Makie.FigureAxisPlot: Contains the Figure, left Axis, and the first plot object. The linked right-hand axis (with stacking-dimension tick labels) is accessible via waterfall_dispersion! if needed.

Examples

using DimensionalData, GLMakie

E  = range(-2.0, 0.0, length=200)
kx = range(-1.0, 1.0, length=40)
A  = DimArray(rand(200, 40), (X(E), Y(kx)))

fap = waterfall_dispersion(A, :Y;
    scale_factor = 0.05,
    cmap         = :plasma,
    figure       = (size = (900, 500),),
    axis         = (xlabel = "Energy (eV)", ylabel = "Intensity (arb. u.)"),
    axis_right   = (ylabel = "kx (Å⁻¹)",),
)
display(fap)