Analysis (mpes.analysis)

Data analysis pipeline including background removal, segmentation and fitting

@author: R. Patrick Xian

class mpes.analysis.BoundedArea(image=None, shape=None, subimage=None)

Bounded area object from a parametric equation.

property mask

Subimage attribute as mask

setBoundary(pmz='linear', boundtype='>', **kwds)

Add bound to grid to redefine subgrid.

Parameters
pmzstr | ‘linear’

Parametrization (pmz) of the decision boundary (‘linear’ or ‘circular’).

boundtypestr | ‘>’

Bound region specification (‘>’ or ‘<’).

**kwds : keyword arguments

property subgrid

Substituent pixel coordinates of the image.

toMask(inbound=1, exbound=0)

Generate a scaled mask from existing shape.

Parameters
inboundfloat | 1

Value for the pixels within the boundary.

exboundfloat | 0

Value for the pixels outside the boundary.

Return
modmask2d array

Modified mask as a 2d array.

view(origin='lower', cmap='terrain_r', axes=True, **kwds)

Display the current mask.

Parameters
originstr | ‘lower’

Location of the image origin.

cmapstr | ‘terrain_r’

Color map

axesbool | True

Axes visibility option in plot.

**kwdskeyword arguments

Additional arguments for matplotlib.pyplot.imshow().

class mpes.analysis.EnergyCalibrator(biases=None, files=[], folder=[], file_sorting=True, traces=None, tof=None)

Electron binding energy calibration workflow.

addFeatures(ranges, refid=0, traces=None, infer_others=False, mode='append', **kwds)

Select or extract the equivalent landmarks (e.g. peaks) among all traces.

Parameters
rangeslist/tuple

Collection of feature detection ranges, within which an algorithm (i.e. 1D peak detector) with look for the feature.

refidint | 0

Index of the reference trace (EDC).

traces2D array | None

Collection of energy dispersion curves (EDCs).

infer_othersbool | True

Option to infer the feature detection range in other traces (EDCs) from a given one.

modestr | ‘append’

Specification on how to change the feature ranges (‘append’ or ‘replace’).

**kwdskeyword arguments

Dictionarized keyword arguments for trace alignment (See self.findCorrespondence())

calibrate(refid=0, ret=['coeffs'], **kwds)

Calculate the functional mapping between time-of-flight and the energy scale using optimization methods.

Parameters
refidint | 0

The reference trace index (an integer).

retlist | [‘coeffs’]

Options for return values (see mpes.analysis.calibrateE()).

**kwdskeyword arguments

See available keywords for mpes.analysis.calibrateE().

property dup

The duplication number.

featureExtract(ranges=None, traces=None, **kwds)

Select or extract the equivalent landmarks (e.g. peaks) among all traces.

Parameters

ranges : list | None traces : 2D array | None **kwds : keyword arguments

See available keywords in mpes.analysis.peaksearch().

static findCorrespondence(sig_still, sig_mov, method='dtw', **kwds)

Determine the correspondence between two 1D traces by alignment.

Parameters
sig_still, sig_mov1D array, 1D array

Input 1D signals.

methodstr | ‘dtw’

Method for 1D signal correspondence detection (‘dtw’ or ‘ptw’).

**kwdskeyword arguments

See available keywords for the following functions, (1) fastdtw.fastdtw() (when method=='dtw') (2) ptw.ptw.timeWarp() (when method=='ptw')

Return
pathcorrlist

Pixel-wise path correspondences between two input 1D arrays (sig_still, sig_mov).

property nfiles

The number of loaded files.

normalize(**kwds)

Normalize the spectra along an axis.

Parameters
**kwdskeyword arguments

See the keywords for mpes.utils.normspec().

property nranges

The number of specified feature ranges.

property ntraces

The number of loaded/calculated traces.

read(form='h5', tracename='', tofname='ToF')

Read traces (e.g. energy dispersion curves) from files.

Parameters
formstr | ‘h5’

Format of the files (‘h5’ or ‘mat’).

tracenamestr | ‘’

Name of the group/attribute corresponding to the trace.

tofnamestr | ‘ToF’

Name of the group/attribute corresponding to the time-of-flight.

saveParameters(form='h5', save_addr='./energy')

Save all the attributes of the workflow instance for later use (e.g. energy scale conversion).

Parameters
formstr | ‘h5’

The file format to save the attributes in (‘h5’/’hdf5’ or ‘mat’).

save_addrstr | ‘./energy’

The filename to save the files with.

view(traces, segs=None, peaks=None, show_legend=True, ret=False, display=True, backend='matplotlib', linekwds={}, linesegkwds={}, scatterkwds={}, legkwds={}, **kwds)

Display a plot showing line traces with annotation.

Parameters
traces2d array

Matrix of traces to visualize.

segslist/tuple

Segments to be highlighted in the visualization.

peaks2d array

Peak positions for labelling the traces.

retbool

Return specification.

backendstr | ‘matplotlib’

Backend specification, choose between ‘matplotlib’ (static) or ‘bokeh’ (interactive).

linekwdsdict | {}

Keyword arguments for line plotting (see matplotlib.pyplot.plot()).

scatterkwdsdict | {}

Keyword arguments for scatter plot (see matplotlib.pyplot.scatter()).

legkwdsdict | {}

Keyword arguments for legend (see matplotlib.pyplot.legend()).

**kwdskeyword arguments

keyword

data type

meaning

maincolor

str

labels

list

Labels for each curve

xaxis

1d array

x (horizontal) axis values

title

str

Title of the plot

legend_location

str

Location of the plot legend

class mpes.analysis.Model(func, xvar, name=None)

Class of fitting curve models

_costfunc(inits, xv, form='original')

Define the cost function of the optimization process

fit(data, inits, method='leastsq', **fitkwds)

Run the optimization

model_eval(params)

Evaluate the fitting model with given parameters

static normalize(data)

Normalize n-dimensional data

partial_eval(params, part=0)

Evaluate parts of a composite fitting model

class mpes.analysis.MomentumCorrector(image, rotsym=6)

Momentum distortion correction and momentum calibration workflow.

_featureUpdate(center_det='centroidnn', **kwds)

Update selected features.

_imageUpdate()

Update distortion-corrected images.

applyDeformation(image, ret=True, **kwds)

Apply the deformation field to a specified image slice.

Parameters
image2D array

Image slice to apply the deformation.

retbool | True

Option to return the image after deformation.

**kwdskeyword arguments
rdeform, cdeform

2D array, 2D array | self.rdeform_field, self.cdeform_field Row- and column-ordered deformation fields.

interp_order

int | 1 Interpolation order.

others

See scipy.ndimage.map_coordinates().

calcGeometricDistances()

Calculate geometric distances involving the center and the vertices. Distances calculated include center-vertex and nearest-neighbor vertex-vertex distances.

calcSymmetryScores(symtype='rotation')

Calculate the symmetry scores from geometric quantities.

Paramters
symtypestr | ‘rotation’

Type of symmetry.

calibrate(image, point_from, point_to, dist, ret='coeffs', **kwds)

Calibration of the momentum axes. Obtain all calibration-related values, return only the ones requested.

Parameters
image2d array

Image slice to construct the calibration function.

point_from, point_tolist/tuple, list/tuple

Pixel coordinates of the two special points in (row, col) ordering.

distfloat

Distance between the two selected points in inverse Angstrom.

retstr | ‘coeffs’

Specification of return values (‘axes’, ‘extent’, ‘coeffs’, ‘grid’, ‘func’, ‘all’).

**kwdskeyword arguments

See arguments in mpes.analysis.calibrateE().

Return

Specified calibration parameters in a dictionary.

coordinateTransform(type, keep=False, ret=False, interp_order=1, mapkwds={}, **kwds)

Apply a pixel-wise coordinate transform to an image.

Parameters
typestr

Type of deformation to apply to image slice.

keepbool | False

Option to keep the specified coordinate transform.

retbool | False

Option to return transformed image slice.

interp_orderint | 1

Interpolation order for filling in missed pixels.

mapkwdsdict | {}

Additional arguments passed to scipy.ndimage.map_coordinates().

**kwdskeyword arguments

Additional arguments in specific deformation field. See symmetrize.sym module.

correct(axis, use_composite_transform=False, update=False, use_deform_field=False, updatekwds={}, **kwds)

Apply a 2D transform to a stack of 2D images (3D) along a specific axis.

Parameters
axisint

Axis for slice selection.

use_composite_transformbool | False

Option to use the composite transform involving the rotation.

updatebool | False

Option to update the existing figure attributes.

use_deform_fieldbool | False

Option to use deformation field for distortion correction.

**kwdskeyword arguments

keyword

data type

meaning

image

2d array

3D image for correction

dfield

list/tuple

row and column deformation field

warping

2d array

2D transform correction matrix

featureExtract(image, direction='ccw', type='points', center_det='centroidnn', symscores=True, **kwds)
Extract features from the selected 2D slice.

Currently only point feature detection is implemented.

Parameters
image2d array

The image slice to extract features from.

directionstr | ‘ccw’

The circular direction to reorder the features in (‘cw’ or ‘ccw’).

typestr | ‘points’

The type of features to extract.

center_detstr | ‘centroidnn’

Specification of center detection method (‘centroidnn’, ‘centroid’, None).

**kwdskeyword arguments

Extra keyword arguments for symmetrize.pointops.peakdetect2d().

property features

Dictionary of detected features for the symmetrization process. self.features is a derived attribute from existing ones.

static getWarpFunction(**kwds)

Construct warping function to apply to other datasets. # TODO: turn this into a fully operational method.

importBinningParameters(parp)

Import parameters of binning used for correction image from parallelHDF5Processor Class instance

Parameters

parp: instance of the ParallelHDF5Processor class used for creation of the correction image

intensityTransform(type='rot_sym', **kwds)

Apply pixel-wise intensity transform.

Parameters
typestr | ‘rot_sym’

Type of intensity transform.

**kwds : keyword arguments

linWarpEstimate(weights=1, 1, 1, optfunc='minimize', optmethod='Nelder-Mead', ret=True, warpkwds={}, **kwds)

Estimate the homography-based deformation field using landmark correspondences.

Parameters
weightstuple/list/array | (1, 1, 1)

Weights added to the terms in the optimizer. The terms are assigned to the cost functions of (1) centeredness, (2) center-vertex symmetry, (3) vertex-vertex symmetry, respectively.

optfunc, optmethodstr/func, str | ‘minimize’, ‘Nelder-Mead’

Name of the optimizer function and the optimization method. See description in mpes.analysis.sym.target_set_optimize().

retbool | True

Specify if returning the corrected image slice.

warpkwdsdictionary | {}

Additional arguments passed to symmetrize.sym.imgWarping().

**kwdskeyword arguments

keyword

data type

meaning

niter

int

Maximum number of iterations

landmarks

list/array

Symmetry landmarks selected for registration

fitinit

tuple/list

Initial conditions for fitting

Return

Corrected 2D image slice (when ret=True is specified in the arguments).

resetDeformation(**kwds)

Reset the deformation field.

rotate(angle='auto', ret=False, **kwds)

Rotate 2D image in the homogeneous coordinate.

Parameters
anglefloat/str

Angle of rotation (specify ‘auto’ to use automated estimation).

retbool | False

Return specification (True/False)

**kwdskeyword arguments

keyword

data type

meaning

image

2d array

2D image for correction

center

tuple/list

pixel coordinates of the image center

scale

float

scaling factor in rotation

See symmetrize.sym.sym_pose_estimate() for other keywords.

saveImage(form='tiff', save_addr='./', dtyp='float32', **kwds)

Save the distortion-corrected dataset (image only, without axes).

Parameters
formstr | ‘tiff’

File format for saving the corrected image (‘tiff’ or ‘mat’).

save_addrstr | ‘./’

The address to save the file at.

dtypstr | ‘float32’

Data type (in case conversion if needed).

**kwdskeyword arguments

See keywords from tifffile.imsave().

saveParameters(form='h5', save_addr='./momentum')

Save all the attributes of the workflow instance for later use (e.g. momentum scale conversion, reconstructing the warping map function).

Parameters
formstr | ‘h5’

File format to for saving the parameters (‘h5’/’hdf5’, ‘mat’)

save_addrstr | ‘./momentum’

The address for the to be saved file.

selectSlice2D(selector, axis=2)

Select (hyper)slice from a (hyper)volume.

Parameters
selectorslice object/list/int

Selector along the specified axis to extract the slice (image). Use the construct slice(start, stop, step) to select a range of images and sum them. Use an integer to specify only a particular slice.

axisint | 2

Axis along which to select the image.

splineWarpEstimate(image, include_center=True, fixed_center=True, iterative=False, interp_order=1, update=False, ret=False, **kwds)

Estimate the spline deformation field using thin plate spline registration.

Parameters
image2D array

Image slice to be corrected.

include_centerbool | True

Option to include the image center/centroid in the registration process.

fixed_centerbool | True

Option to have a fixed center during registration-based symmetrization.

iterativebool | False

Option to use the iterative approach (may not work in all cases).

interp_orderint | 1

Order of interpolation (see scipy.ndimage.map_coordinates()).

updatebool | False

Option to keep the spline-deformed image as corrected one.

retbool | False

Option to return corrected image slice.

**kwdskeyword arguments
landmarks

list/array | self.pouter_ord Landmark positions (row, column) used for registration.

new_centers

dict | {} User-specified center positions for the reference and target sets. {‘lmkcenter’: (row, col), ‘targcenter’: (row, col)}

property symscores

Dictionary of symmetry-related scores.

static transform(points, transmat)

Coordinate transform of a point set in the (row, column) formulation.

Parameters
pointslist/array

Cartesian pixel coordinates of the points to be transformed.

transmat2D array

The transform matrix.

Return

Transformed point coordinates.

update(content, **kwds)

Update specific attributes of the class.

Parameters
contentstr | ‘all’

‘feature’ = update only feature attributes ‘image’ = update only image-related attributes ‘all’ = update both feature and image-related attributes

**kwdskeyword arguments

Extra keyword arguments passed into self._featureUpdate().

updateDeformation(rdeform, cdeform, reset=False, **kwds)

Update the deformation field.

Parameters
rdeform, cdeform2D array, 2D array

Row- and column-ordered deformation fields.

resetbool | False

Option to reset the deformation field.

**kwdskeyword arguments

See mpes.analysis.MomentumCorrector.resetDeformation().

view(origin='lower', cmap='terrain_r', figsize=4, 4, points={}, annotated=False, display=True, backend='matplotlib', ret=False, imkwds={}, scatterkwds={}, crosshair=False, radii=[50, 100, 150], crosshair_thickness=1, **kwds)

Display image slice with specified annotations.

Parameters
originstr | ‘lower’

Figure origin specification (‘lower’ or ‘upper’).

cmapstr | ‘terrain_r’

Colormap specification.

figsizetuple/list | (4, 4)

Figure size.

pointsdict | {}

Points for annotation.

annotatedbool | False

Option for annotation.

displaybool | True

Display option when using bokeh to render interactively.

backendstr | ‘matplotlib’

Visualization backend specification. :’matplotlib’: use static display rendered by matplotlib. :’bokeh’: use interactive display rendered by bokeh.

retbool | False

Option to return figure and axis objects.

imkwddict | {}

Keyword arguments for matplotlib.pyplot.imshow().

crosshairbool | False

Display option to plot circles around center self.pcent. Works only in bokeh backend.

radiilist | [50,100,150]

Radii of circles to plot when crosshair optin is activated.

crosshair_thicknessint | 1

Thickness of crosshair circles.

**kwdskeyword arguments

General extra arguments for the plotting procedure.

mpes.analysis._datacheck_peakdetect(x_axis, y_axis)

Input format checking

mpes.analysis._rotate2d(image, center, angle, scale=1)

2D matrix scaled rotation carried out in the homogenous coordinate.

Parameters
image2d array

Image matrix.

centertuple/list

Center of the image (row pixel, column pixel).

anglenumeric

Angle of image rotation.

scalenumeric | 1

Scale of image rotation.

Returns
image_rot2d array

Rotated image matrix.

rotmat2d array

Rotation matrix in the homogeneous coordinate system.

mpes.analysis._signedmask(imr, imc, maskr, maskc, sign)

Generate a binary mask using the masked coordinates.

Parameters
imr, imcint

Row and column size of the image.

maskr, maskc1D array

Row and column coordinates of the masked pixels.

signint/str

Value of the masked region, (0, 1, ‘nan’, or ‘xnan’).

Return
mask2D array

Mask matrix.

mpes.analysis.applyWarping(imgstack, axis, hgmat)

Apply warping transform for a stack of images along an axis

Parameters
imgstack3D array

Image stack before warping correction.

axisint

Axis to iterate over to apply the transform.

hgmat2D array

Homography matrix.

Return
imstack_transformed3D array

Stack of images after correction for warping.

mpes.analysis.apply_mask_along(arr, mask, axes=None)

Apply a mask in a low dimensional slice throughout a high-dimensional array.

Parameters
arrnD array

Multidimensional array for masking.

masknD array

Mask to apply.

axeslist/tuple of int | None

The axes to apply the mask to.

Return
maskedarrnD array

Masked multidimensional array.

mpes.analysis.bandpath_map(bsvol, pathr=None, pathc=None, path_coords=None, eaxis=2, method='analog')

Extract band diagram map from 2D/3D data.

Parameters
bsvol2D/3D array

Volumetric band structure data.

pathr, pathc1D array | None, None

Row and column pixel coordinates along the band path (ignored if path_coords is given).

path_coords2D array | None

Combined row and column pixel coordinates of the band path.

eaxisint | 2

Energy axis index.

methodstr | ‘analog’

Method for generating band path map (‘analog’ or ‘digital’). :’analog’: Using an interpolation scheme to calculate the exact pixel values. :’digital’: Using only the approximating pixel values (Bresenham’s algorithm).

Return
bpm2D array

Band path map (BPM) sampled from the volumetric data.

mpes.analysis.blocknorm(data, mavg_axis=0, blockwidth=1)

Block-thresholding 2D data.

Parameters
datandarray

Data to normalize.

mavg_axisint | 0

Axis to move the block along.

blockwidthint | 1

Width of the moving block.

Return
datanormndarray

Block-normalized data.

mpes.analysis.bootstrapfit(data, axval, model, params, axis=0, dfcontainer=None, pbar=False, pbenv='classic', ret='all', **kwds)

Line-by-line fitting via bootstrapping fitted parameters from one line to the next.

Parameters
datandarray

Data used in fitting.

axvallist/numeric array

Value for the axis.

modellmfit Model object

The fitting model.

paramslmfit Parameters object

Initial guesses for fitting parameters.

axisint | 0

The axis of the data to fit.

dfcontainerpandas DataFrame | None

Dataframe container for the fitting parameters.

pbarbool | False

Progress bar condition.

pbenvstr | ‘classic’

Progress bar environment (‘classic’ for generic version, ‘notebook’ for notebook compatible version).

**kwdskeyword arguments

keyword

data type

meaning

maxiter

int

maximum iteration per fit (default = 20)

concat

bool

concatenate the fit parameters to DataFrame input False (default) = no concatenation, use an empty DataFrame to start True = with concatenation to input DataFrame

bgremove

bool

toggle for background removal (default = True)

flipped

bool

toggle for fitting start position (if flipped, fitting start from the last line)

limpropagate

bool

verbose

bool

toggle for output message (default = False)

Returns
df_fitpandas DataFrame

Dataframe container populated with obtained fitting parameters.

data_nobgndarray

Background-removed (Shirley-type) traces.

mpes.analysis.build_dynamic_matrix(fitparams, display_range=slice(None, None, None), pre_t0_range=slice(None, 1, None))

Construct the dynamic matrix from the fitting results. For each fitting parameter, construct time-dependent value, time-dependent absolute and relative changes.

Parameters

fitparams: 3D ndarray

fitting output

display_range: slice object | slice(None, None, None)

display time range of the fitting parameters (default = full range)

pre_t0_range: slice object | slice(None, 1, None)

time range regarded as before time-zero

Returns

dyn_matrix4D ndarray

calculated dynamic matrix

mpes.analysis.calibrateE(pos, vals, order=3, refid=0, ret='func', E0=None, Eref=None, t=None, aug=1, method='lstsq', **kwds)

Energy calibration by nonlinear least squares fitting of spectral landmarks on a set of (energy dispersion curves (EDCs). This amounts to solving for the coefficient vector, a, in the system of equations T.a = b. Here T is the differential drift time matrix and b the differential bias vector, and assuming that the energy-drift-time relationship can be written in the form, E = sum_n (a_n * t**n) + E0

Parameters
poslist/array

Positions of the spectral landmarks (e.g. peaks) in the EDCs.

valslist/array

Bias voltage value associated with each EDC.

orderint | 3

Polynomial order of the fitting function.

refidint | 0

Reference dataset index, varies from 0 to vals.size - 1.

retstr | ‘func’

Return type, including ‘func’, ‘coeffs’, ‘full’, and ‘axis’ (see below).

E0float | None

Constant energy offset.

tnumeric array | None

Drift time.

augint | 1

Fitting dimension augmentation (1=no change, 2=double, etc).

Returns
pfuncpartial function

Calibrating function with determined polynomial coefficients (except the constant offset).

ecalibdictdict

A dictionary of fitting parameters including the following, :coeffs: Fitted polynomial coefficients (the a’s). :offset: Minimum time-of-flight corresponding to a peak. :Tmat: the T matrix (differential time-of-flight) in the equation Ta=b. :bvec: the b vector (differential bias) in the fitting Ta=b. :axis: Fitted energy axis.

mpes.analysis.calibrateK(img, pxla, pxlb, k_ab=None, kcoorda=None, kcoordb=[0.0, 0.0], equiscale=False, ret=['axes'])

Momentum axes calibration using the pixel positions of two symmetry points (a and b) and the absolute coordinate of a single point (b), defaulted to [0., 0.]. All coordinates should be specified in the (row_index, column_index) format. See the equiscale option for details on the specifications of point coordinates.

Parameters
img2D array

An energy cut of the band structure.

pxla, pxlblist/tuple/1D array

Pixel coordinates of the two symmetry points (a and b). Point b has the default coordinates [0., 0.] (see below).

k_abfloat | None

The known momentum space distance between the two symmetry points.

kcoordalist/tuple/1D array | None

Momentum coordinates of the symmetry point a.

kcoordblist/tuple/1D array | [0., 0.]

Momentum coordinates of the symmetry point b (krow, kcol), default to k-space center.

equiscalebool | False

Option to adopt equal scale along both the row and column directions. :True: Use a uniform scale for both x and y directions in the image coordinate system. This applies to the situation where the points a and b are (close to) parallel with one of the two image axes. :False: Calculate the momentum scale for both x and y directions separately. This applies to the situation where the points a and b are sufficiently different in both x and y directions in the image coordinate system.

retlist | [‘axes’]

Return type specification, options include ‘axes’, ‘extent’, ‘coeffs’, ‘grid’, ‘func’, ‘all’.

Returns
k_row, k_col1D array

Momentum coordinates of the row and column.

axis_extentlist

Extent of the two momentum axis (can be used directly in imshow).

k_rowgrid, k_colgrid2D array

Row and column mesh grid generated from the coordinates (can be used directly in pcolormesh).

mpes.analysis.circmask(img, rcent, ccent, rad, sign=1, ret='mask', **kwds)

Use a circular binary mask to cover an image.

Parameters
img2D array

Input image to be masked.

rcentfloat

Row center position.

ccentfloat

Column center position.

radfloat

Radius of circle.

signint/str | 1

Value of the masked region (0, 1, ‘nan’ or ‘xnan’). ‘xnan’ means the masked region is 1 and the other region nan.

retstr | ‘mask’

Return type (‘mask’, ‘masked_image’)

kwdskeyword arguments

keyword

data type

default

meaning

shape

tuple/list

shape of img

see skimage.draw.circle()

method

str

‘graphic’

‘graphic’ or ‘algebraic’

edgefactor

float

1.02

prefactor to rad**2

Return
cmask or cmask*img2D array

Mask only or masked image

mpes.analysis.curvature2d(image, cx=1, cy=1)

Implementation of 2D curvature calculation. The formula follows Zhang et al. Rev. Sci. Instrum. 82, 043712 (2011).

Parameters
image2D array

2D image obtained from measurement.

cx, cynumeric, numeric | 1, 1

Scaling parameters in x and y directions.

mpes.analysis.func_add(*funcs)

Addition of an arbitray number of functions

*Parameters*

*funcs: list/tuple

functions to combine

*Returns*

funcsum: function

functional sum

mpes.analysis.func_update(func, suffix='')

Attach a suffix to parameter names and their instances in the expression of a function

*Parameters*

func: function

input function

suffix: str | ‘’

suffix to attach to parameter names

*Returns*

params: list of str

updated function parameters

expr: str

updated function expression

mpes.analysis.gaussian(feval=False, vardict=None)

1D Gaussian lineshape model. Returns numerical values if feval=True.

Parameters

feval: bool | False

Option to evaluate function.

vardict: dict | None

Dictionary containing values for the variables named as follows (as dictionary keys).

amp function amplitude or scaling factor.

xvar x values (energy values in a lineshape).

ctr center position.

sig standard deviation.

mpes.analysis.gradn(array, axes, **kwds)

Calculate nth-order gradients of the array along different directions.

Parameters
arraynumpy array

N-dimensional matrix for calculating the gradient.

axesint/list/tuple/1D array

A sequence of axes (from first to last) to calculate the gradient. When input a single integer, the gradient is calculated along that particular axis. For example, the 4th-order mixed gradient d4f/(dxdydxdy) requires the sequence (1, 0, 1, 0).

**kwdskeyword arguments

See numpy.gradient().

mpes.analysis.image_interpolator(image, iptype='RGI')

Construction of an image interpolator.

Parameters

image: 2D array

2D image for interpolation.

iptype: str | ‘RGI’

Type of the interpolator.

Return

interp: interpolator instance

Instance of an interpolator.

mpes.analysis.interp_slice(data, pathr=None, pathc=None, path_coords=None, iptype='RGI')

Slicing 2D/3D data through interpolation.

Parameters

data: 2D/3D array

Data array for slicing.

pathr, pathc: list/tuple/array, list/tuple/array

Row and column coordinates of the interpolated path.

path_coords: array

Cartesian coordinates of the interpolated path.

iptype: str | ‘RGI’

Type of interpolator.

mpes.analysis.line_generator(A, B, npoints, endpoint=True, ret='separated')

Generate intermediate points in a line segment AB (A to B) given endpoints.

Parameters
A, Btuple/list, tuple/list

Pixel coordinates of the endpoints of the line segment.

npointsnumeric

Number of points in the line segment.

endpointbool | True

Option to include the endpoint (B) in the line coordinates.

retstr | ‘separated’

Option to return line coordinates (‘separated’ or ‘joined’).

mpes.analysis.peakdetect1d(y_axis, x_axis=None, lookahead=200, delta=0)

Function for detecting local maxima and minima in a signal. Discovers peaks by searching for values which are surrounded by lower or larger values for maxima and minima respectively

Converted from/based on a MATLAB script at: http://billauer.co.il/peakdet.html

Parameters y_axis : list

A list containing the signal over which to find peaks

x_axislist | None

A x-axis whose values correspond to the y_axis list and is used in the return to specify the position of the peaks. If omitted an index of the y_axis is used.

lookaheadint | 200

distance to look ahead from a peak candidate to determine if it is the actual peak ‘(samples / period) / f’ where ‘4 >= f >= 1.25’ might be a good value

deltanumeric | 0

this specifies a minimum difference between a peak and the following points, before a peak may be considered a peak. Useful to hinder the function from picking up false peaks towards to end of the signal. To work well delta should be set to delta >= RMSnoise * 5.

Returns max_peaks : list

positions of the positive peaks

min_peakslist

positions of the negative peaks

mpes.analysis.peakdetect2d(img, method='daofind', **kwds)

Peak-like feature detection in a 2D image.

Parameters
img2D array

Image matrix.

methodstr | ‘daofind’

Detection method (‘daofind’ or ‘maxlist’).

**kwdskeyword arguments

Arguments passed to the specific methods chosen.

daofind

See astropy.stats.sigma_clipped_stats() and photutils.detection.DAOStarFinder().

sigmafloat | 5.0

Standard deviation of the clipping Gaussian.

fwhmfloat | 3.0

FWHM of the convoluting Gaussian kernel.

threshfactorfloat | 8

Intensity threshold for background-foreground separation (foreground is above threshold).

maxlist

See skimage.feature.peak_local_max().

mindistfloat | 10

Minimal distance between two local maxima.

numpeaksint | 7

Maximum number of detected peaks.

Return
pks2D array

Pixel coordinates of detected peaks, in (column, row) ordering.

mpes.analysis.peaksearch(traces, tof, ranges=None, method='range-limited', pkwindow=3, plot=False)

Detect a list of peaks in the corresponding regions of multiple EDCs

Parameters
traces2D array

Collection of EDCs.

tof1D array

Time-of-flight values.

rangeslist of tuples/lists | None

List of ranges for peak detection in the format [(LowerBound1, UpperBound1), (LowerBound2, UpperBound2), ….].

methodstr | ‘range-limited’

Method for peak-finding (‘range-limited’ and ‘alignment’).

pkwindowint | 3

Window width of a peak(amounts to lookahead in mpes.analysis.peakdetect1d).

plotbool | False

Specify whether to display a custom plot of the peak search results.

Returns
pkmaxs1D array

Collection of peak positions

mpes.analysis.perspectiveWarping(img, landmarks, targs, ret='image')

Perform image warping based on a generic affine transform (homography).

Parameters
img2D array

Input image (distorted).

landmarkslist/array

List of pixel positions of the reference points.

targslist/array

List of pixel positions of the target points.

Returns
imgaw2D array

Image after affine warping.

maw2D array

Homography matrix for the tranform.

mpes.analysis.points2path(pointsr, pointsc, method='analog', npoints=None, ret='separated')

Calculate ordered pixel cooridnates along a path defined by specific intermediate points. The approach constructs the path using a set of line segments bridging the specified points, therefore it is also able to trace the sequence indices of these special points.

Parameters
pointsr, pointsclist/tuple/array

The row and column pixel coordinates of the special points along the sampling path.

methodstr | ‘analog’

Method of sampling.

npointslist/tuple | None

Number of points along each segment.

retstr | ‘separated’

Specify if return combined (‘combined’) or separated (‘separated’) row and column coordinates.

Returns
polyr, polyc1D array

Pixel coordinates along the path traced out sequentially.

pid1D array

Pointwise indices of the special lpoints.

mpes.analysis.rangeConvert(x, xrng, pathcorr)

Convert value range using a pairwise path correspondence (e.g. obtained from time warping techniques).

Parameters
x1D array

Values of the x axis (e.g. time-of-flight values).

xrnglist/tuple

Boundary value range on the x axis.

pathcorrlist/tuple

Path correspondence between two 1D arrays in the following form, [(id_1_trace_1, id_1_trace_2), (id_2_trace_1, id_2_trace_2), …]

Return
xrange_transtuple

Transformed range according to the path correspondence.

mpes.analysis.rectmask(img, rcent, ccent, shift, direction='row', sign=1, ret='mask', **kwds)

Use a rectangular binary mask to cover an image.

Parameters
img2D array

Input image to be masked

rcentfloat

Row center position

ccentfloat

Column center position

shiftint/list of int

Pixel shifts

directionstr | ‘row’

Direction to apply the shift to, ‘row’ or ‘column’ indicates row-wise or column-wise shift for generating the rectangular mask

signint/str | 1

Value of the masked region (0, 1, ‘nan’ or ‘xnan’). ‘xnan’ means the masked region is 1 and the other region nan.

retstr | ‘mask’

Return type (‘mask’, ‘masked_image’)

**kwds : keyword arguments

Return
cmask or cmask*img2D array

Mask only or masked image

mpes.analysis.regionExpand(mask, **kwds)

Expand the region of a binarized image around a line position

Parameters mask : numeric binarized 2D array

the mask to be expanded

**kwdskeyword arguments

keyword

data type

meaning

method

str

method of choice (‘offset’, ‘growth’)

value

numeric

value to be assigned to the masked

linecoords

2D array

contains x and y positions of the line

axoffsets

tuple/list

[downshift upshift] pixel number

clipbounds

tuple/list

bounds in the clipping direction

selem

ndarray

structuring element

Return mask : numeric 2D array

modified mask (returns the original mask if insufficient arguments are provided for the chosen method for region expansion)

mpes.analysis.ridgeDetect(mask, method='mask_mean_y', **kwds)

Detect the band ridges using selected methods.

Parameters

masknumeric 2D array

the 2D integer-valued mask with labeled bands

methodstr

the method used for ridge detection ‘mask_mean_y’ : mean mask position along y direction (default) ‘mask_mean_x’ : mean mask position along x direction

**kwdskeyword arguments

keyword

data type

meaning

x

int/float

x axis coordinates

y

int/float

y axis coordinates

Return

ridgeslist of dataframes

the ridge coordinates

mpes.analysis.segment2d(img, nbands=1, **kwds)

Electronic band segmentation using local thresholding and connected component labeling

Parameters

img2D numeric array

the 2D matrix to segment

nbandsint

number of electronic bands

**kwds : keyword arguments

Return

imglabeled2D numeric array

labeled mask

mpes.analysis.shirley(x, y, tol=1e-05, maxiter=20, explicit=False, warning=False)

Calculate the 1D best Shirley-Proctor-Sherwood background S for a dataset (x, y). A. Proctor, P. M. A. Sherwood, Anal. Chem. 54 13 (1982). The function is adapted from Kane O’Donnell’s routine 1. Finds the biggest peak 2. Use the minimum value on either side of this peak as the terminal points of the Shirley background. 3. Iterate over the process within maximum allowed iteration (maxiter) to reach the tolerance level (tol).

Parameters

x: 1D numeric array

The photoelectron energy axis.

y: 1D numeric array

The photoemission intensity axis.

tol: float | 1e-5

The fitting tolerance.

maxiter: int | 20

The maximal iteration.

explicit: bool | False

Option for explicit display of iteration number.

warning: bool | False

Option to display of warnings during calculation.

Return

sbg: 1D numeric array

Calculated Shirley background.

mpes.analysis.shirley2d(x, y, tol=1e-05, maxiter=20, explicit=False, warning=False)

2D Shirley background removal

Parameters

x: 1D numeric array

Photoemission energy axis.

y: 2D numeric array

Photoemission intensity matrix.

tol: float | 1e-5

The fitting tolerance.

maxiter: int | 20

The maximal iteration.

explicit: bool | False

Option for explicit display of iteration number.

warning: bool | False

Option to display of warnings during calculation.

mpes.analysis.vertexGenerator(center, fixedvertex=None, cvd=None, arot=None, nside=None, direction=- 1, scale=1, diagdir=None, ret='all', rettype='float32')

Generation of the vertices of symmetric polygons.

Parameters
center(int, int)

Pixel positions of the symmetry center (row pixel, column pixel).

fixedvertex(int, int) | None

Pixel position of the fixed vertex (row pixel, column pixel).

cvdnumeric | None

Center-vertex distance.

arotfloat | None

Spacing in angle of rotation.

nsideint | None

The total number of sides for the polygon.

directionint | -1

Direction of angular rotation (1 = counterclockwise, -1 = clockwise)

scalefloat | 1

Radial scaling factor.

diagdirstr | None

Diagonal direction of the polygon (‘x’ or ‘y’).

retstr | ‘all’

Return type. Specify ‘all’ returns all vertices, specify ‘generated’ returns only the generated ones (without the fixedvertex in the argument).

Return
vertices2D array

Collection of generated vertices.

mpes.analysis.voigt(feval=False, vardict=None)

1D Voigt lineshape model. Returns numerical values if feval=True.

Parameters

feval: bool | False

Option to evaluate function.

vardict: dict | None

Dictionary containing values for the variables named as follows (as dictionary keys).

amp function amplitude or scaling factor.

xvar x values (energy values in a lineshape).

ctr center position.

sig standard deviation of the Gaussian component.

gam linewidth of the Lorentzian component.