API reference

This page documents the PyARPES API by generation from signatures and docstrings. You can use this and the source code to supplement the remainder of the PyARPES documentation.

Please note that this is not a complete API documentation page. Less used and internal APIs are not documented here.

Data-loading functions

io.load_data(file[, location])

Loads a piece of data using available plugins.

io.load_example_data([example_name])

Provides sample data for executable documentation.

io.example_data

ExampleData()

Momentum Conversion

Exact Forward Transforms

utilities.conversion.forward.convert_coordinates_to_kspace_forward(...)

Forward converts all the individual coordinates of the data array.

Utilities

utilities.conversion.fast_interp.Interpolator(...)

Provides a Pythonic interface to fast gridded linear interpolation.

utilities.conversion.bounds_calculations.full_angles_to_k(...)

Converts from the full set of standard PyARPES angles to momentum.

utilities.conversion.remap_manipulator.remap_coords_to(...)

Produces coordinates for the scan path of arr in the coordinate system of reference_arr.

Conversion Implementations

You do not need to call these directly, but they are good references for anyone looking to implement a different kind of coordinate transform.

utilities.conversion.base.CoordinateConverter(arr)

Infrastructure code to support a new coordinate conversion routine.

utilities.conversion.kx_ky_conversion.ConvertKp(...)

A momentum converter for single ARPES (kp) cuts.

utilities.conversion.kx_ky_conversion.ConvertKxKy(...)

Implements volumetric momentum conversion for kx-ky scans.

utilities.conversion.kz_conversion.ConvertKpKz(...)

Implements single angle photon energy scans.

General Analysis

Axis Methods

arpes.analysis.general.rebin(data[, shape, ...])

Rebins the data onto a different (smaller) shape.

arpes.analysis.general.symmetrize_axis(data, ...)

Symmetrizes data across an axis.

arpes.analysis.general.condense(data)

Clips the data so that only regions where there is substantial weight are included.

arpes.preparation.axis_preparation.normalize_dim(...)

Normalizes the intensity so that all values along axes other than dim_or_dims have the same value.

arpes.preparation.axis_preparation.sort_axis(...)

Sorts slices of data along axis_name so that they lie in order.

Experimental Resolution Modeling

arpes.analysis.resolution.total_resolution_estimate(data)

Gives the quadrature sum estimate of the resolution of an ARPES spectrum.

arpes.analysis.resolution.thermal_broadening_estimate(data)

Calculates the thermal broadening from the temperature on the data.

arpes.analysis.resolution.beamline_resolution_estimate(data)

arpes.analysis.resolution.analyzer_resolution_estimate(data)

Estimates the energy resolution of the analyzer.

Self-Energy

arpes.analysis.self_energy.to_self_energy(...)

Converts MDC fit results into the self energy.

arpes.analysis.self_energy.fit_for_self_energy(data)

Fits for the self energy of a dataset containing a single band.

arpes.analysis.self_energy.estimate_bare_band(...)

Estimates the bare band from a fitted dispersion.

arpes.analysis.self_energy.quasiparticle_lifetime(...)

Calculates the quasiparticle mean free path in meters (meters!).

Derivatives

arpes.analysis.derivative.dn_along_axis(arr)

Like curvature, performs a second derivative.

arpes.analysis.derivative.curvature(arr[, ...])

Provides "curvature" analysis for band locations.

arpes.analysis.derivative.minimum_gradient(data)

Implements the minimum gradient approach to defining the band in a diffuse spectrum.

Smoothing and Filtering

arpes.analysis.filters.gaussian_filter_arr(arr)

Coordinate aware scipy.ndimage.filters.gaussian_filter.

arpes.analysis.filters.boxcar_filter_arr(arr)

Coordinate aware scipy.ndimage.filters.boxcar_filter.

arpes.analysis.savitzky_golay.savitzky_golay(...)

Implements a Savitzky Golay filter with given window size.

Deconvolution

arpes.analysis.deconvolution.make_psf1d(...)

Produces a 1-dimensional gaussian point spread function for use in deconvolve_rl.

arpes.analysis.deconvolution.deconvolve_ice(...)

Deconvolves data by a given point spread function using the iterative convolution extrapolation method.

arpes.analysis.deconvolution.deconvolve_rl(data)

Deconvolves data by a given point spread function using the Richardson-Lucy method.

Masks

arpes.analysis.mask.apply_mask(data, mask[, ...])

Applies a logical mask, i.e. one given in terms of polygons, to a specific piece of data.

arpes.analysis.mask.apply_mask_to_coords(...)

Performs broadcasted masking along a given dimension.

arpes.analysis.mask.polys_to_mask(mask_dict, ...)

Converts a mask definition in terms of the underlying polygon to a True/False mask array.

arpes.analysis.mask.raw_poly_to_mask(poly)

Converts a polygon into a mask definition.

Fermi Surface Pockets

arpes.analysis.pocket.curves_along_pocket(data)

Produces radial slices along a Fermi surface through a pocket.

arpes.analysis.pocket.edcs_along_pocket(data)

Collects EDCs around a pocket.

arpes.analysis.pocket.radial_edcs_along_pocket(...)

Produces EDCs distributed radially along a vector from the pocket center.

arpes.analysis.pocket.pocket_parameters(data)

Estimates pocket center, anisotropy, principal vectors, and extent in either angle or k-space.

Background Removal

Shirley Backgrounds

analysis.shirley.calculate_shirley_background(xps)

Calculates a shirley background iteratively over the full energy range energy_range.

analysis.shirley.remove_shirley_background(...)

Calculates and removes a Shirley background from a spectrum.

Convex Hull Backgrounds

analysis.background.calculate_background_hull(arr)

Calculates a background using the convex hull of the data (viewing the intensity as a Z axis).

analysis.background.remove_background_hull(...)

Removes a background according to calculate_background_hull.

Incoherent Backgrounds

corrections.background.remove_incoherent_background(data)

Removes counts above the Fermi level.

Array Alignment

Subpixel Correlation Based Alignment

analysis.align.align(a, b, **kwargs)

Returns the unitful offset of b in a for ndarrays.

Machine Learning

ML Based Decompositions

analysis.decomposition.decomposition_along(...)

Performs a change of basis of multidimensional data according to sklearn decomposition classes.

analysis.decomposition.pca_along(data, axes, ...)

Performs a change of basis of multidimensional data according to sklearn decomposition classes.

analysis.decomposition.nmf_along(data, axes, ...)

Performs a change of basis of multidimensional data according to sklearn decomposition classes.

analysis.decomposition.factor_analysis_along(...)

Performs a change of basis of multidimensional data according to sklearn decomposition classes.

analysis.decomposition.ica_along(data, axes, ...)

Performs a change of basis of multidimensional data according to sklearn decomposition classes.

Interactive Decomposition Browsers

widgets.pca_explorer(pca, data[, ...])

A tool providing PCA decomposition exploration of a dataset.

Deep Learning and PyTorch

Utilities for interpretation of results akin to those in fast.ai.

deep_learning.interpret.Interpretation(...)

Provides utilities to interpret predictions of a model.

deep_learning.interpret.InterpretationItem(...)

Provides tools to introspect model performance on a single item.

IO tools.

deep_learning.io.from_portable_bin(path)

Reads data from a relatively portable binary format.

deep_learning.io.to_portable_bin(arr, path)

Converts data to a relatively portable binary format.

Transform pipelines.

deep_learning.transforms.Identity()

Represents a reversible identity transform.

deep_learning.transforms.ReversibleLambda(...)

A reversible anonymous function, so long as the caller supplies an inverse.

deep_learning.transforms.ComposeBoth(transforms)

Like torchvision.transforms.Compose but this operates on data & target in each transform.

Data Generation

Here are tools for simulating ARPES from theoretical models, including finite statistics, resolution modeling, and detector effects.

simulation.sample_from_distribution(distribution)

Samples events from a probability distribution.

simulation.cloud_to_arr(point_cloud, shape)

Converts a point cloud (list of xy pairs) to an array representation.

simulation.SpectralFunctionMFL([k, omega, ...])

Implements the Marginal Fermi Liquid spectral function, more or less.

simulation.SpectralFunctionPhaseCoherent([...])

Implements the "phase coherence" model for the BSSCO spectral function.

simulation.DetectorEffect()

Detector effects are callables that map a spectrum into a new transformed one.

simulation.NonlinearDetectorEffect([gamma])

Implements power law detector nonlinearities.

Data Loading Plugins

endstations.plugin.ALG_main.ALGMainChamber()

Implements data loading for the Lanzara group "Main Chamber".

endstations.plugin.ALG_spin_ToF.SpinToFEndstation()

Implements data loading for the Lanzara group Spin-ToF.

endstations.plugin.ANTARES.ANTARESEndstation()

Implements data loading for ANTARES at SOLEIL.

endstations.plugin.Elettra_spectromicroscopy.SpectromicroscopyElettraEndstation()

Data loading for the nano-ARPES beamline "Spectromicroscopy Elettra".

endstations.plugin.example_data.ExampleDataEndstation()

Loads data from exported .nc format saved by xarray.

endstations.plugin.fallback.FallbackEndstation()

Sequentially tries different loading plugins.

endstations.plugin.HERS.HERSEndstation()

Implements data loading at the ALS HERS beamline.

endstations.plugin.igor_export.IgorExportEndstation()

Implements loading exported HDF files for ARPES data from Igor.

endstations.plugin.igor_plugin.IgorEndstation()

A generic file loader for PXT files.

endstations.plugin.kaindl.KaindlEndstation()

The Kaindl Tr-ARPES high harmonic generation setup.

endstations.plugin.MAESTRO.MAESTROMicroARPESEndstation()

Implements data loading at the microARPES endstation of ALS's MAESTRO.

endstations.plugin.MAESTRO.MAESTRONanoARPESEndstation()

Implements data loading at the nanoARPES endstation of ALS's MAESTRO.

endstations.plugin.MBS.MBSEndstation()

Implements loading text files from the MB Scientific text file format.

endstations.plugin.merlin.BL403ARPESEndstation()

The MERLIN ARPES Endstation at the Advanced Light Source.

endstations.plugin.SToF_DLD.SToFDLDEndstation()

Provides data loading for the Lanzara group experimental ARToF.

Curve Fitting

Broadcast Fitting

fits.utilities.broadcast_model(model_cls, ...)

Perform a fit across a number of dimensions.

General Curve Fitting Utilities

fits.utilities.result_to_hints(m[, defaults])

Turns an lmfit.model.ModelResult into a dictionary with initial guesses.

Models

fits.fit_models

Collect imports from categorized submodules.

Helpful Methods for Setting Initial Parameters

xarray_extensions.SelectionToolAccessor.first_exceeding(...)

xarray_extensions.SelectionToolAccessor.max_in_window(...)

Working with Broadcast Fit Results

Available as methods via .F accessor.

xarray_extensions.ARPESDatasetFitToolAccessor(...)

xarray_extensions.ARPESFitToolsAccessor(...)

Utilities related to examining curve fits.

NorthStar Laue

Loading Laue data from the NorthStar DAQ program

laue.load_laue(path)

Loads NorthStart Laue backscattering data.

Plotting

Interactive Utilities: Qt Based

plotting.qt_tool.qt_tool(data, **kwargs)

Starts the qt_tool using an input spectrum.

plotting.qt_ktool.ktool(data, **kwargs)

Start the momentum conversion tool.

plotting.fit_tool.fit_tool(data)

Starts the fitting inspection tool using an input fit result Dataset.

plotting.bz_tool.bz_tool()

Starts the Brillouin zone exploration tool.

plotting.basic_tools.path_tool(data)

plotting.basic_tools.mask_tool(data)

plotting.basic_tools.bkg_tool(data)

plotting.basic_tools.det_window_tool(data)

General Utilities/Matplotlib Quality of Life

An incomplete list of useful plotting utilities from arpes.utilities.plotting.

plotting.utils.path_for_plot(desired_path)

Provides workspace and date scoped path generation for plots.

plotting.utils.savefig(desired_path[, dpi, ...])

The PyARPES preferred figure saving routine.

plotting.utils.simple_ax_grid(n_axes[, figsize])

Generates a square-ish set of axes and hides the extra ones.

plotting.utils.invisible_axes(ax)

Make a Axes instance completely invisible.

plotting.utils.no_ticks(ax)

Remove all axis ticks.

plotting.utils.remove_colorbars([fig])

Removes colorbars from given (or, if no given figure, current) matplotlib figure.

plotting.utils.frame_with(ax[, color, linewidth])

Makes thick, visually striking borders on a matplotlib plot.

plotting.utils.unchanged_limits(ax)

Context manager that retains axis limits.

plotting.utils.plot_arr([arr, ax, over, mask])

Convenience method to plot an array with a mask over some other data.

plotting.utils.imshow_mask(mask[, ax, over, ...])

Plots a mask by using a fixed color and transparency.

plotting.utils.swap_xaxis_side(ax)

Swaps the x axis to the top of the figure.

plotting.utils.swap_yaxis_side(ax)

Swaps the y axis to the right of the figure.

plotting.utils.swap_axis_sides(ax)

Swaps the y axis to the right of the figure and the x axis to the top.

plotting.utils.latex_escape(text[, force])

Conditionally escapes a string based on the matplotlib settings.

plotting.utils.fancy_labels(ax_or_ax_set[, data])

Attaches better display axis labels for all axes.

plotting.utils.sum_annotation([eV, phi])

Annotates that a given axis was summed over by listing the integration range.

plotting.utils.summarize(data[, axes])

Makes a summary plot with different marginal plots represented.

Interactive Utilities: Bokeh Based

plotting.dyn_tool.dyn(dynamic_function, data)

Starts the dynamic tool using dynamic_function and widgets for each arg.

plotting.dyn_tool.DynamicTool(analysis_fn, ...)

Presents a utility to rerun a function with different arguments and see the result of the function.

plotting.fit_inspection_tool.FitCheckTool(...)

Interactive verification of fit quality for broadcast fits.

plotting.mask_tool.MaskTool(**kwargs)

Tool to allow masking data by drawing regions.

plotting.path_tool.PathTool(**kwargs)

Tool to allow drawing paths on data, creating selections, and masking regions around paths.

plotting.band_tool.BandTool(**kwargs)

Two dimensional fitting band tool.

plotting.interactive.ImageTool([curs])

Implements a 2D and 3D data browser via Bokeh.

Interactive Utilities: Matplotlib Based

widgets.pick_rectangles(data, **kwargs)

A utility allowing for selection of rectangular regions.

widgets.pick_points(data_or_str, **kwargs)

A utility allowing for selection of points in a dataset.

widgets.pca_explorer(pca, data[, ...])

A tool providing PCA decomposition exploration of a dataset.

widgets.kspace_tool(data[, overplot_bz, ...])

A utility for assigning coordinate offsets using a live momentum conversion.

widgets.fit_initializer(data[, peak_type])

A tool for initializing lineshape fitting.

Stack Plots

plotting.stack_plot.stack_dispersion_plot(data)

Generates a stack plot with all the lines distinguished by offset rather than color.

plotting.stack_plot.flat_stack_plot(data[, ...])

Generates a stack plot with all the lines distinguished by color rather than offset.

plotting.stack_plot.offset_scatter_plot(data)

Makes a stack plot but which uses scatters rather than a lineplot for each curve in the set.

Spin-ARPES Plots

plotting.spin.spin_polarized_spectrum(spin_dr)

Plots a simple spin polarized spectrum using curves for the up and down components.

plotting.spin.spin_colored_spectrum(spin_dr)

Plots a spin spectrum using total intensity and assigning color with the spin polarization.

plotting.spin.spin_difference_spectrum(spin_dr)

Plots a spin difference spectrum.

Count-based and ToF Plots

plotting.tof.plot_with_std(data[, ...])

Makes a fill-between line plot with error bars from associated statistical errors.

plotting.tof.scatter_with_std(data[, ...])

Makes a scatter plot of data with error bars generated from associated statistical errors.

Reference Plots

plotting.spatial.plot_spatial_reference(...)

Helpfully plots data against a reference scanning dataset.

plotting.spatial.reference_scan_spatial(data)

Plots the spatial content of a dataset, useful as a quick reference.

Curve Fitting Plots

plotting.fits.plot_fit(model_result[, ax])

Performs a straightforward plot of the data, residual, and fit to an axis.

plotting.fits.plot_fits(model_results[, ax])

Plots several fits onto a grid of axes.

plotting.parameter.plot_parameter(fit_data, ...)

Makes a simple scatter plot of a parameter from an broadcast_fit result.

False Color Plots

plotting.false_color.false_color_plot(...[, ...])

Plots a spectrum in false color after conversion to R, G, B arrays.

Plotting with Brillouin Zones

plotting.bz.bz_plot(cell, *args, **kwargs)

Dimension generic BZ plot which uses the cell dimension to delegate.

plotting.bz.plot_data_to_bz(data, cell, **kwargs)

A dimension agnostic tool used to plot ARPES data onto a Brillouin zone.

plotting.bz.overplot_standard([name, ...])

A higher order function to plot a Brillouin zone over a plot.

plotting.bz.plot_plane_to_bz(cell, plane, ax)

Plots a 2D cut plane onto a Brillouin zone.

Plot Annotations

plotting.annotations.annotate_cuts(ax, data, ...)

Annotates a cut location onto a plot.

plotting.annotations.annotate_point(ax, ...)

Annotates a point or high symmetry location into a plot.

plotting.annotations.annotate_experimental_conditions(ax, ...)

Renders information about the experimental conditions onto a set of axes.