xanespy package

Submodules

xanespy.beamlines module

Functions and classes that prepare experiments at specific synchrotron beamlines.

class xanespy.beamlines.Detector(start: xanespy.beamlines.ZoneplatePoint, x_step: int = None, y_step: int = None, z_step: int = None, end: xanespy.beamlines.ZoneplatePoint = None)

Bases: xanespy.beamlines.Zoneplate

A calibration object for the position of the detector.

class xanespy.beamlines.DetectorPoint(x, y, z, energy)

Bases: tuple

energy

Alias for field number 3

x

Alias for field number 0

y

Alias for field number 1

z

Alias for field number 2

class xanespy.beamlines.Zoneplate(start: xanespy.beamlines.ZoneplatePoint, x_step: int = None, y_step: int = None, z_step: int = None, end: xanespy.beamlines.ZoneplatePoint = None)

Bases: object

Type of focusing optic using in X-ray microscopy. It must be moved with changing energy to properly focus the beam. In order to properly predict zoneplate positions, it needs either two position-energy pairs or one position-energy pair and a step. Passing two position-energy pairs is preffered because this allows x, y and z to be set properly instead of just z.

Parameters:

• start (tuple) – The first zoneplate position-energy pair.
• z_step (int, optional) – Adjustment in z-position for every positive change of 1 eV of beam energy.
• end (tuple, optional) – The second zoneplate position-energy pair.

position(energy: float)

Predict the x, y and z position of the zonplate for the given energy.

class xanespy.beamlines.ZoneplatePoint(x, y, z, energy)

Bases: tuple

energy

Alias for field number 3

x

Alias for field number 0

y

Alias for field number 1

z

Alias for field number 2

xanespy.beamlines.monitor_sector8(tsv_filename)

Monitors a list of files and displays them as they are collected from the instrument. A matplotlib axes is displayed and is updated with each new frame that is detected. This function will block until all files in the file list are accounted for.

Parameters:tsv_filename (string) – The name of the file that contains a tab-separated-values list of filenames. This file is automatically generated by the sector8_xanes_script function.

xanespy.beamlines.sector8_xanes_script(dest, edge, zoneplate, detector, sample_positions, names, iterations=range(0, 1), binning=1, exposure=30, abba_mode=True)

Prepare an script file for running multiple consecutive XANES framesets on the transmission x-ray micrscope at the Advanced Photon Source beamline 8-BM-B. This function also creates a tab-separated-values (tsv) file which contains each sample filename and its associated meta-data. This can then be used for real-time processing.

Parameters:

• dest – file-like object that will hold the resulting script
• zoneplate (Zoneplate) – Calibration details for the Fresnel zone-plate.
• detector (Detector) – Like zoneplate, but for detector.
• edge (KEdge) – Description of the absorption edge.
• binning (int, optional) – how many CCD pixels to combine into one image pixel (eg. 2 means 2x2 CCD pixels become 1 image pixel.
• exposure (float) – How many seconds to collect for per frame
• sample_positions – Locations to move the x, y (and z) axes to in order to capture the image.
• names – sample name to use in file names. Should match sample_positions in length.
• iterations (iterable) – contains an identifier for each full set of xanes location with reference.
• abba_mode (str, optional) – If True, script will locations forward and backwards to save time. Eg: reference, sample, change-energy, sample, reference, change-energy, etc. Not compatible with frame_rest argument. If used, the reference frame should be first or last in the order to make the process maximally efficient.

xanespy.beamlines.ssrl6_xanes_script(dest, edge: edges.KEdge, zoneplate: xanespy.beamlines.Zoneplate, positions: List[utilities.position], reference_position: utilities.position, iterations: Iterable[T_co], iteration_rest: int = 0, frame_rest: int = 0, binning: int = 2, exposure=0.5, repetitions: int = 5, ref_repetitions: int = 10, abba_mode: bool = True)

Prepare a script file for running multiple consecutive XANES framesets on the transmission x-ray micrscope at the Advanced Photon Source beamline 8-BM-B. Both iteration_rest and frame_rest can be used to give the material time to recover from X-ray damage.

Parameters:

• dest – A file-like object that will hold the resulting script
• edge (Edge) – Description of the absorption edge.
• binning (int, optional) – how many CCD pixels to combine into one image pixel (eg. 2 means 2x2 CCD pixels become 1 image pixel.
• exposure (float, optional) – How many seconds to collect for per frame
• positions – Locations to move the x, y (and z) axes to in order to capture the image.
• reference_position (tuple) – Single x, y, z location to capture a reference frame.
• iteration_rest (int, optional) – Time (in seconds) to wait between iterations. Beam will wait at reference location before starting next XANES set.
• frame_rest (int, optional) – Time (in seconds) to wait between frames. Beam will wait at reference location before starting next energy frame.
• zoneplate (Zoneplate) – Calibration details for the Fresnel zone-plate.
• detector (Detector) – Like zoneplate, but for detector.
• iterations (Iterable) – Contains an identifier for each XANES dataset.
• repetitions (int, optional) – How many images to collect for each location/energy. These frames will then be averaged during analysis.
• ref_repetitions (int, optional) – Same as repetitions but for reference frames.
• abba_mode (bool, optional) – If True, script will alternate sample and reference locations first to save time. Eg: reference, sample, change-energy, sample, reference, change-energy, etc. Not compatible with frame_rest argument.

xanespy.beamlines.write_scaninfo_header(f, abba_mode, repetitions, ref_repetitions)

xanespy.edges module

Descriptions of X-ray energy absorption edge.

class xanespy.edges.CuKEdge

Bases: xanespy.edges.KEdge

E_0 = 8978.9

edge_range = (8970, 9010)

map_range = (8970, 9010)

name = 'Cu'

post_edge = (9010, 9200)

pre_edge = (8940, 8970)

regions = []

shell = 'K'

class xanespy.edges.Edge

Bases: object

An X-ray absorption edge. It is defined by a series of energy ranges. All energies are assumed to be in units of electron-volts. This class is intended to be extended into K-edge, L-edge, etc.

E_0

The energy of the absorption edge itself.

Type:float

regions

All the energy regions. Each tuple is of the form (start, end, step) and is inclusive at both ends.

Type:list of 3-tuples

name

A human-readable name for this edge (eg “Ni K-edge”)

Type:string

pre_edge

Energy range (start, stop) that defines points below the edge region, inclusive.

Type:2-tuple

post_edge

Energy range (start, stop) that defines points above the edge region, inclusive.

Type:2-tuple

map_range

Energy range (start, stop) used for normalizing maps. If not supplied, will be determine from pre- and post-edge arguments.

Type:2-tuple

edge_range

Energy range (start, stop) used to determine the official beginning and edge of the edge itself.

Type:2-tuple

E_0 = None

all_energies()

Combine all the regions into one array.

Returns:energies – Flat array with the energies for this edge. Return type:list

edge_range = None

energies_in_range(norm_range=None)

map_range = None

post_edge = None

pre_edge = None

pre_edge_fit = None

regions = []

class xanespy.edges.FeKEdge

Bases: xanespy.edges.KEdge

E_0 = 7100.0

edge_range = (7115, 7140)

map_range = (7100, 7200)

name = 'Fe'

post_edge = (7150, 7250)

pre_edge = (7100, 7108)

regions = [(7100, 7110, 3), (7110, 7117, 1), (7117, 7130, 5), (7130, 7200, 5)]

shell = 'K'

class xanespy.edges.KEdge

Bases: xanespy.edges.Edge

annotate_spectrum(ax)

Draw lines on the axes to indicate the position of the edge.

mask(*args, **kwargs)

Return a numpy array mask for material that’s active at this edge. Calculations are done in xanes_math.l_edge_mask().

shell = 'K'

An X-ray absorption K-edge corresponding to a 1s transition.

class xanespy.edges.LEdge

Bases: xanespy.edges.Edge

An X-ray absorption K-edge corresponding to a 2s or 2p transition.

annotate_spectrum(ax)

Draw lines on the axes to indicate the position of the edge.

mask(*args, **kwargs)

Return a numpy array mask for material that’s active at this edge. Calculations are done in xanes_math.l_edge_mask().

shell = 'L'

class xanespy.edges.LMOMnKEdge

Bases: xanespy.edges.KEdge

name = 'Mn_LMO'

regions = [(6450, 6510, 20), (6524, 6542, 2), (6544, 6564, 1), (6566, 6568, 2), (6572, 6600, 4), (6610, 6650, 10), (6700, 6850, 50)]

class xanespy.edges.NCACobaltKEdge

Bases: xanespy.edges.KEdge

E_0 = 7712

edge_range = (7715, 7740)

map_range = (7725, 7735)

name = 'Co_NCA'

post_edge = (7780, 7900)

pre_edge = (7600, 7715)

shell = 'K'

class xanespy.edges.NCACobaltLEdge

Bases: xanespy.edges.LEdge

E_0 = 793.2

edge_range = (775, 785)

map_range = (0, 1)

name = 'Co_NCA'

post_edge = (785, 790)

pre_edge = (770, 775)

regions = [(770, 775, 1), (775, 785, 0.5), (785, 790, 1)]

class xanespy.edges.NCANickelKEdge

Bases: xanespy.edges.KEdge

E_0 = 8333

edge_range = (8341, 8358)

map_range = (8341, 8360)

name = 'Ni_NCA'

post_edge = (8350, 8500)

pre_edge = (8249, 8320)

regions = [(8250, 8310, 20), (8324, 8344, 2), (8344, 8356, 1), (8356, 8360, 2), (8360, 8400, 4), (8400, 8440, 8), (8440, 8640, 50)]

shell = 'K'

class xanespy.edges.NCANickelKEdge61

Bases: xanespy.edges.NCANickelKEdge

regions = [(8250, 8310, 15), (8324, 8360, 1), (8360, 8400, 4), (8400, 8440, 8), (8440, 8640, 50)]

class xanespy.edges.NCANickelKEdge62

Bases: xanespy.edges.NCANickelKEdge

regions = [(8250, 8310, 15), (8324, 8360, 1), (8360, 8400, 4), (8400, 8440, 8), (8440, 8690, 50)]

class xanespy.edges.NCANickelLEdge

Bases: xanespy.edges.LEdge

E_0 = 853

edge_range = (848, 857)

map_range = (0, 1)

name = 'Ni_NCA'

post_edge = (857, 862)

pre_edge = (844, 848)

regions = [(844, 848, 1), (849, 856, 0.25), (857, 862, 1)]

class xanespy.edges.NMCNickelKEdge29

Bases: xanespy.edges.NCANickelKEdge

regions = [(8250, 8310, 20), (8324, 8346, 6), (8346, 8358, 1), (8360, 8400, 10), (8400, 8440, 15), (8440, 8640, 100)]

xanespy.exceptions module

Define classes for more fine-grained control over exception handling.

exception xanespy.exceptions.CreateGroupError

Bases: ValueError

Tried to import a TXM frameset into a group but the corresponding HDF group already exists or is otherwise inaccessible.

exception xanespy.exceptions.DataFormatError

Bases: RuntimeError

The raw data are arranged in a way that the importers or TXM classes do not understand.

exception xanespy.exceptions.DataNotFoundError

Bases: FileNotFoundError

Expected a directory containing data but found none.

exception xanespy.exceptions.DatasetExistsError

Bases: RuntimeError

Trying to save a new dataset but one already exists with the given path.

exception xanespy.exceptions.FileExistsError

Bases: OSError

Tried to import a TXM frameset but the corresponding HDF file already exists.

exception xanespy.exceptions.FilenameParseError

Bases: ValueError

The parameters in the filename do not match the naming scheme associated with this flavor.

exception xanespy.exceptions.FrameFileNotFound

Bases: OSError

Expected to load a TXM frame file but it doesn’t exist.

exception xanespy.exceptions.FrameSourceError

Bases: KeyError

The frame-source attribute is not present.

exception xanespy.exceptions.GroupKeyError

Bases: KeyError

Tried to load or create an HDF group but failed. Examples include: the group doesn’t exist, is ambiguous or already exists when being created.

exception xanespy.exceptions.HDFScopeError

Bases: ValueError

Tried to pass an HDF scope that is not recognized.

exception xanespy.exceptions.NoParticleError

Bases: Exception

exception xanespy.exceptions.RefinementError

Bases: RuntimeError

exception xanespy.exceptions.XanesMathError

Bases: RuntimeError

xanespy.fitting module

A collection of callables that can be used for fitting spectra against.

xanespy.fitting.prepare_p0(p0, frame_shape, num_timesteps=1)

Create an initial parameter guess for fitting.

Takes a starting guess (p0) and returns a numpy array with this inital guess that matches the frameset.

For example, if a frameset has 12 timesteps and (1024, 2048) frames, then a 5-tuple input for p0 will result in a return value with shape (12, 5, 1024, 2048)

xanespy.fitting.fit_spectra(observations, func, p0, nonnegative=False, quiet=False)

Fit a function to a series observations.

The shapes of observations and p0 parameters must match in the first dimension, and the callable func should take a series of parameters (the exact number is determined by the last dimension of p0) and return a set of observations (the length of which is determined by the last dimension of observations).

Parameters:

• observations (np.ndarray) – A 1- or 2-dimensional array of observations against which to fit the function func.
• func (callable, str) – The function that will be used for fitting. It should match func(p0, p1, ...) where p0, p1, etc are the fitting parameters. Some useful functions can be found in the xanespy.fitting module.
• p0 (np.ndarray) – Initial guess for parameters, with similar dimensions to a frameset. Example, fitting 3 sources (plus offset) for a (1, 40, 256, 256) 40-energy frameset requires p0 to be (1, 4, 256, 256).
• nonnegative (bool, optional) – If true (default), negative parameters will be avoided. This can also be a tuple to allow for fine-grained control. Eg: (True, False) will only punish negative values in the first of the two parameters.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

Returns:

• params (numpy.ndarray) – The fit parameters (as frames) for each source.
• residuals (numpy.ndarray) – Residual error after fitting, as maps.

class xanespy.fitting.Curve

Bases: object

Base class for a callabled Curve.

name = 'curve'

param_names = ()

class xanespy.fitting.Line(x)

Bases: xanespy.fitting.Curve

class xanespy.fitting.LinearCombination(sources)

Bases: xanespy.fitting.Curve

Combines other curves into one callable.

The constructor accepts the keyword argument sources, which should be a list of numpy arrays. The resulting object can then be called with parameters for the weight of each function plus an offset. For example, with two sources, the object is called as

# Prepare the separate sources
x = np.linspace(0, 2*np.pi, num=361)
sources = [np.sin(x), np.sin(2*x)]

# Produce a combo with 0.5*sin(x) + 0.25*sin(2x) + 2
lc = LinearCombination(sources=sources)
out = lc(0.5, 0.25, 2)

The final output will have the same shape as the sources, which should all be the same shape as each other.

name = 'linear_combination'

param_names

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

class xanespy.fitting.Gaussian(x)

Bases: xanespy.fitting.Curve

A Gaussian curve.

Mathematically:

\[y = a e^{\frac{-(x-b)**2}{2c^2}}\]

Parameters:x (np.ndarray) – Array of x-values to input into the Gaussian function.

name = 'gaussian'

param_names = ('height', 'center', 'width')

class xanespy.fitting.L3Curve(energies, num_peaks=2)

Bases: xanespy.fitting.Curve

An L_3 absorption edge.

This function is a combination of two Gaussian peaks and a step function. The first 3 parameters give the height, position and width of one peak, and parameters 3:6 give the same for a second peak. Parameters 6:9 are height, position and width of an arctan step function. Parameter 9 is a global offset.

Parameters:peaks (int, optional) – How many peaks to fit across the edge.

name = 'L3-gaussian'

param_names

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

class xanespy.fitting.KCurve(energies)

Bases: xanespy.fitting.Curve

A K absorption edge.

Fit Parameters:

scale

Overall scale factor for curve

voffset

Overall vertical offset for the curve

E0

Edge position as energy of maximum in second derivative at edge

sigw

Sharpenss of the edge sigmoid

bg_slope

Linear increase/-decrease in background optical depth

ga

Height parameter for Gaussian whiteline peak

gb

Center parameter in eV (relative to E0) for Gaussian whiteline peak

gc

Width parameter for Gaussian whiteline peak

guess_params(intensities, edge)

Guess initial starting parameters for a k-edge curve. This will give a rough estimate, appropriate for giving to the fit_kedge function as the starting parameters, p0.

Parameters:

• intensities (np.ndarray) – An array containing optical_depth data that represents a K-edge spectrum. Only 1-dimensional data are currently accepted.
• edge (xanespy.edges.KEdge) – An X-ray Edge object, will be used for estimating the actual edge energy itself.

Returns:

p0 – A named tuple with the estimated parameters (see KEdgeParams for definition)

Return type:

tuple

name = 'K-edge-curve'

param_names = ('scale', 'voffset', 'E0', 'sigw', 'bg_slope', 'ga', 'gb', 'gc')

xanespy.importers module

xanespy.importers.decode_aps_params(filename)

Accept the filename of an XRM file and return sample parameters as a dictionary.

xanespy.importers.decode_ssrl_params(filename)

Accept the filename of an XRM file and return sample parameters as a dictionary.

xanespy.importers.import_aps32idc_xanes_file(filename, hdf_filename, hdf_groupname, timestep=0, total_timesteps=1, append=False, downsample=1, square=True, exclude=[], median_filter_size=(1, 3, 3), dark_idx=slice(None, None, None))

Import XANES data from a HDF5 file produced at APS beamline 32-ID-C.

This is used for importing a single XANES dataset.

Parameters:

• filename (str) – The path to the HDF5 file containing the source data.
• hdf_filename (str) – The path to the HDF5 file that will receive the imported data. Will be created if it doesn’t exist.
• hdf_groupname (str, optional) – A description of the dataset that will be used to form the HDF data group.
• timestep (int, optional) – Which timestep index to use for saving data.
• total_timesteps (int, optional) – How many timesteps to use for creating new datasteps. Only meaningful if append is truthy.
• append (bool, optional) – If true, existing datasets will be saved and only the timestep will be overwritten.
• downsample (int, optional) – Improves signal-to-noise at the expense of spatial resolution. Applied to intensities, flat-field, etc before converting to optical_depth.
• square (bool, optional) – If true (default), the edges will be cut to make a square array. Eg (2048, 2448) becomes (2048, 2048).
• exclude (iterable, optional) – Indices of frames to exclude from importing if, for example, the frame contains artifacts or is otherwise problematic.
• median_filter_size (float or tuple) – If not None, apply a median rank filter to each flat and data frame. The value of this parameters matches the size parameter to scipy.ndimage.filters.median_filter(), for example using (1, 3, 3) will filter only along the x and y axes, and not the energy axis. Median filtering takes places after downsampling.
• dark_idx (slice, optional) – A slice object (or an index) for which dark-field images to use. Must be the same for all timesteps in an experiment. Useful if some dark field images are not usable.

xanespy.importers.import_aps32idc_xanes_files(filenames, hdf_filename, hdf_groupname, *args, **kwargs)

Import XANES data from a HDF5 file produced at APS beamline 32-ID-C.

This is used for importing a full operando experiment at once.

Parameters:

• filenames (str) – List of paths to the HDF5 files containing the source data.
• hdf_filename (str) – The path to the HDF5 file that will receive the imported data. Will be created if it doesn’t exist.
• hdf_groupname (str, optional) – A description of the dataset that will be used to form the HDF data group.
• kwargs (args,) – Passed to import_aps32idc_xanes_file

xanespy.importers.import_aps4idc_sxstm_files(filenames, hdf_filename, hdf_groupname, shape, energies, flux_correction=True)

Import scanning X-ray tunneling microscopy absorbance frames.

These frames are STM images from APS 4-ID-C with incident X-rays at increasing energies, providing pixel-resolved spectral data. If the files are all in one directory with no other data, then the filenames argument can be the directory name, otherwise it should be a list of the filenames to import. It is assumed that the fast axis is energy, then the two spatial axes.

Parameters:

• filenames (list, str) – List of filenames to import relative to working directory. Alternately, it can be a string with a directory path and all files will be imported.
• hdf_filename (str) – Path to a filename to use for saving imported data. If it doesn’t exist, it will be created.
• hdf_groupname (str) – HDF groupname to use for saving data. If it exists, it will be overwritten.
• shape (2-tuple) – Shape for the resulting maps.
• energies (iterable) – Incident beam energies for each frame, in electron-volts.
• flux_correction (bool, optional) – If true, certain channels will be corrected to account for changing beam flux.

xanespy.importers.import_aps8bm_xanes_dir(directory, hdf_filename, groupname=None, *args, **kwargs)

xanespy.importers.import_aps8bm_xanes_file(filename, ref_filename, hdf_filename, groupname=None, quiet=False)

Extract an entire xanes framestack from one xradia file.

A single TXRM file can contain multiple frames at different energies. This function will import such a file along with the corresponding reference frames into an HDF file. If the given groupname exists in hdf_filename, it will be overwritten and a RuntimeWarning will be issued.

Parameters:

• filename (str) – File path to the txrm file to import.
• ref_filename (str) – File path to the txrm file that contains the white-field reference images. This will be used to calculate optical depth from transmitted intensity.
• hdf_filename (str) – File path to the destination HDF5 file that will receive the imported data.
• groupname (str, optional) – The name for the top-level HDF group. If omitted, a group name will be generated from the filename parameter. ‘{}’ can be included and will receive the position name using the format() method. The ‘{}’ is required if more than one field of view exists and a groupname is given.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

xanespy.importers.import_frameset(directory, flavor, hdf_filename, groupname=None, return_val=None, quiet=False)

Import all files in the given directory collected at an X-ray microscope beamline.

Images are assumed to full-field transmission X-ray micrographs.

If return_val is “group”, the return value for this function will be a data group in an open HDF5 file. The underlying file should be explicitly closed to avoid corruption. This is done automatically if return_val is None (default).

Parameters:

• directory (str) – A valid path to a directory containing the frame data to import.
• flavor (str) – Indicates what type of naming conventions and data structure to assume. See documentation for xanespy.xradia.XRMFile for possible choice.
• hdf_filename (str) – Where to save the output to. Will overwrite previous data-sets with the same name.
• groupname (str, optional) – What to use as the name for HDF group storing the data. If omitted, guess the name from the directory path. ‘{}’ can be included and will receive the position name using the format() method. The ‘{}’ is required if more than one field of view exists and a groupname is given.
• return_val (str, optional) – Request a specific return value. - None: No return value (default) - “group”: The open HDF5 group for this experiment.
• quiet (bool, optional) – Whether to suppress the progress bar

xanespy.importers.import_nanosurveyor_frameset(directory: str, quiet=False, hdf_filename=None, hdf_groupname=None, energy_range=None, exclude_re=None, append=False, frame_shape=None)

Import a set of images from reconstructed ptychography scanning microscope data.

This generates ptychography chemical maps based on data collected at ALS beamline 5.3.2.1. The arguments energy_range and exclude_re can be used to fine-tune the set of imported file. For example: passing exclude_re='(019|017)' will import everything except scans 019 and 017.

Parameters:

• directory (str) – Directory where to look for results. It should contain .cxi files that are the output of the ptychography reconstruction.”
• quiet (Bool, optional) – If truthy, progress bars will not be shown.
• hdf_filename (str, optional) – HDF File used to store computed results. If omitted or None, the directory basename is used
• hdf_groupname (str, optional) – Name to use for the hdf group of this dataset. If omitted or None, the directory basename is used. Raises an exception if the group already exists in the HDF file.
• energy_range (2-tuple, optional) – A 2-tuple with the (min, max) energy to be imported. This is useful if only a subset of the available data is usable. Values are assumed to be in electron-volts.
• exclude_re (str, optional) – Any filenames matching this regular expression will not be imported. A string or compiled re object can be given.
• append (bool, optional) – If True, any existing dataset will be added to, rather than replaced (default False)
• frame_shape (2-tuple, optional) – If given, images will be trimmed to this shape. Must be smaller than the smallest frame. This may be useful if the frames are slightly different shapes. Does not apply to STXM images.

xanespy.importers.import_ssrl_xanes_dir(directory, hdf_filename, groupname=None, *args, **kwargs)

Import all files in the given directory collected at SSRL beamline 6-2c and process into framesets. Images are assumed to full-field transmission X-ray micrographs and repetitions will be averaged. Passed on to xanespy.importers.import_frameset

Parameters:

• directory (str) – Where to look for files to import.
• hdf_filename (str) – Path to an HDF5 to receive the data.
• groupname (str, optional) – HDF group name to use for saving these data. If omitted, try to guess from directory path.
• kwargs (args,) – Arguments and keyword arguments passed on to
• import_frameset. –

xanespy.importers.import_stxm_frameset(directory: str, quiet=False, hdf_filename=None, hdf_groupname=None, energy_range=None, exclude_re=None, append=False)

Import a set of images from scanning microscope data.

This generates Scanning Tranmission X-ray Microscopy chemical maps based on data collected at ALS beamline 5.3.2.1

Parameters:

• directory (str) – Directory where to look for results. It should contain .hdr and xim files that are the output of the ptychography reconstruction.”
• quiet (Bool, optional) – If truthy, progress bars will not be shown.
• hdf_filename (str, optional) – HDF File used to store computed results. If omitted or None, the directory basename is used
• hdf_groupname (str, optional) – Name to use for the hdf group of this dataset. If omitted or None, the directory basename is used. Raises an exception if the group already exists in the HDF file.
• energy_range (2-tuple, optional) – A 2-tuple with the (min, max) energy to be imported. This is useful if only a subset of the available data is usable. Values are assumed to be in electron-volts.
• exclude_re (str, optional) – Any filenames matching this regular expression will not be imported. A string or compiled re object can be given.
• append (bool, optional) – If True, any existing dataset will be added to, rather than replaced (default False)

xanespy.importers.magnification_correction(frames, pixel_sizes)

Correct for changes in magnification at different energies.

As the X-ray energy increases, the focal length of the zone plate changes and so the image is zoomed-out at higher energies. This method applies a correction to each frame to make the magnification similar to that of the first frame. Some beamlines correct for this automatically during acquisition and don’t need this function: APS 8-BM-B, 32-ID-C.

Parameters:

• frames (np.ndarray) – Numpy array of image frames that need to be corrected.
• pixel_sizes (np.ndarray) – Numpy array of pixel sizes corresponding to entries in frames.

Returns:

(scales2D, translations) – An array of scale factors to use for applying a correction to each frame. Translations show how much to move each frame array by to re-center it.

Return type:

(np.ndarray, np.ndarray)

xanespy.importers.read_metadata(filenames, flavor, quiet=False)

Take a list of filenames and return a pandas dataframe with all the metadata.

Parameters:

• filenames (iterable) – Iterable of filenames to use for extracting metadata.
• flavor (str) – Same as in import_frameset.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

xanespy.plots module

Helper functions for setting up and displaying plots using matplotlib.

xanespy.plots.big_axes()

Return a new Axes object, but larger than the default.

xanespy.plots.draw_colorbar(ax, cmap, norm, energies=None, orientation='vertical', *args, **kwargs)

Draw a colorbar on the side of a mapping axes to show the range of colors used. Returns the newly created colorbar object.

Parameters:

• ax – Matplotlib axes object against which to plot.
• cmap (str) – String or mpl Colormap instance indicating which colormap to use.
• norm (matplotlib.Normalize) – Describes the range of values to use.
• energies (iterable, optional) – Values to put as the tick marks on the colorbar. If not given, 3 points across norm will be used.
• orientation (str, optional) – “horizontal” or “vertical” (default)

xanespy.plots.draw_histogram_colorbar(ax, *args, **kwargs)

Similar to draw_colorbar() with some special formatting options to put it along the X-axis of the axes.

xanespy.plots.dual_axes(fig=None, longdim=13.8, shortdim=6.9, orientation='horizontal')

Two new axes for mapping, side-by-side.

Parameters:

• longdim (float) – Size in inches for the long dimension. If orientation is “vertical”, this will be the height.
• shortdim (float) – Size in inches for the short dimension. If orientation is “vertical”, this will be the width.

xanespy.plots.latexify()

Set some custom options for saving matplotlib graphics in PGF format.

xanespy.plots.new_axes(height=5, width=None)

Create a new set of matplotlib axes for plotting. Height in inches.

xanespy.plots.new_image_axes(height=5, width=5)

Square axes with ticks on the outside.

xanespy.plots.plot_composite_map(data, ax=None, origin='upper', *args, **kwargs)

Plot an RGB composite map on the given axes.

xanespy.plots.plot_kedge_fit(energies, params)

Plot the fit based on the given k-edge params. The params will be given to xanespy.xanes_math.KEdgeParams for conversion.

energies : np.ndarray

A 1D array with the x values to plot.

params : array-like

Fitted K-edge parameters.

xanespy.plots.plot_pixel_spectra(pixels, extent, spectra, energies, map_ax, spectra_ax=None, step_size=0)

Highlight certain pixels in an already-plotted map and plot their spectra. The map should already have been plotted.

Parameters:

• pixels (-) – to highlight and plot.
• extent (-) – positions to (row, column) positions.
• spectra (-) – in pixels will use this array to get spectra. Shape is assumed to be (row, column, energy).
• energies (-) – plotting spectra.
• map_ax (-) – pixels.
• spectra_ax (-) – None (default) a new axes will be created.
• step_size (-) – directly on top of each other.

xanespy.plots.plot_spectra(spectra, energies, ax=None)

Take an iterable of spectra and plot them one above the next.

Parameters:

• spectra (iterable) – Each entry is an array with intensity values.
• energies (np.ndarray) – Energy values for the points in each entry of spectra.
• ax (matplotlib.Axes, optional) – The Axes object to receive the plots. If omitted, a new Axes will be created.

Returns:

artists – A list of the matplotlib artists used to draw the spectra.

Return type:

list

xanespy.plots.plot_spectra_as_map(spectra, energies, ax=None, extent=None, **kwargs)

Take an iterable of spectra and plot them as a heat map.

This function takes energies so it can put ticks on the x-axis, however if they are not equally spaced, their distance on the map will not properly capture they’re distance numerically.

Parameters:

• spectra (iterable) – Each entry is an array with intensity values.
• energies (np.ndarray) – Energy values for the points in each entry of spectra.
• ax (matplotlib.Axes, optional) – The Axes object to receive the plots. If omitted, a new Axes will be created.
• extent (Matplotlib extent.) –
• **kwargs (Get passed on to matplotlib imshow()) –

Returns:

artists – A list of the matplotlib artists used to draw the spectra.

Return type:

list

xanespy.plots.plot_spectrum(spectrum, energies, norm=<matplotlib.colors.Normalize object>, show_fit=False, ax=None, ax2=None, linestyle=':', color='blue', cmap='plasma', polar_coords=False, *args, **kwargs)

Plot an energy spectrum on an axes.

Applies some color formatting if edge is a valid XANES Edge object.

Parameters:

• spectrum (np.ndarray) – Array of intensity values.
• energies (np.ndarray) – Array of energy values.
• norm (optional) – Matplotlib Normalize() object that shows the map range. This will be used to annotate the plot if it is give.
• show_fit (bool, optional) – Whether to plot lines showing the best fit.
• ax (mpl.Axes, optional) – Matplotlib Axes on which to plot. If not given, a new axes will be generated.
• ax2 (mpl.Axes, optional) – A second y-axes for plotting the imaginary component if the data are complex.
• linestyle (optional) – Passed on to matplotlib.
• cmap (str, optional) – Colormap, passed on to matplotlib
• color (optional) – Specifies the color for the circles plotted. Either “x” or “y” will decide based on the numerical value, norm and cmap arguments. Anything else will be passed as a color spec to the matplotlib commands.
• polar_coords (bool, optional) – If truthy, the spectrum will be plotted as modulus-phase instead of real-imag. For purely real data this is equivalent to taking the absolute value.

xanespy.plots.plot_txm_histogram(data, ax=None, norm=None, bins=None, cmap='plasma', add_cbar=True, *args, **kwargs)

Take an array of data values and show a histogram with some color-coding related to normalization value.

Returns: The matplotlib axes object used for plotting.

Parameters:

• data (np.ndarray) – An array of values to plot on the histogram.
• ax (optional) – Matplotlib Axes instance to receive the plot. If None, a new axes will created.
• norm (optional) – Matplotlib Normalize instance with the colormap range.
• bins (optional) – Bins to pass to the matplotlib hist() routine. If None (default), we will choose based on dtype of the data: integers will yield 1-wide bins, anything else will give 256 bins.
• cmap (str, optional) – Matplotlib colormap for coloring the bars.
• add_cbar (bool, optional) – Boolean to decide whether to add a colorbar along the bottom axis or not.
• *args – Positional arguments passed to matplotlib’s hist call.
• *kwargs – Keyword arguments passed to matplotlib’s hist call.

xanespy.plots.plot_txm_intermediates(images)

Accept a dictionary of images and plots them each on its own axes using matplotlib’s imshow. This is a complement to routines that operate on a microscopy frame and optionally return all the intermediate calculated frames.

xanespy.plots.plot_txm_map(data, edge=None, norm=None, ax=None, cmap='plasma', origin='upper', vmin=None, vmax=None, *args, **kwargs)

xanespy.plots.remove_extra_spines(ax)

Removes the right and top borders from the axes.

xanespy.plots.set_axes_color(ax, color)

Set the axes, tick marks, etc of ax to mpl color color. Also, “doegreen” has special significance as the color associated with the US department of energy.

xanespy.plots.set_outside_ticks(ax)

Convert all the axes so that the ticks are on the outside and don’t obscure data.

xanespy.qt_frame_view module

class xanespy.qt_frame_view.FrameAnimation(fig, artists, *args, **kwargs)

Bases: matplotlib.animation.ArtistAnimation

Performs the animation for scrolling through frames arbitarily.

stop()

class xanespy.qt_frame_view.FrameChangeSource(view, *args, **kwargs)

Bases: PyQt5.QtCore.QObject

add_callback(func, *args, **kwargs)

callbacks = []

remove_callback(func, *args, **kwargs)

start()

stop()

class xanespy.qt_frame_view.QtFrameView

Bases: PyQt5.QtCore.QObject

add_hdf_tree_item(item)

animate_frames(frames, energies, norm, cmap, extent)

back_button_clicked

build_hdf_tree(tree)

change_vrange(vmin, vmax, step, decimals)

Change the range of frame map colors.

Does not affect the rendered frames.

clear_axes()

connect_presenter(presenter)

connect_signals(presenter)

create_canvas()

create_status_bar()

draw_histogram(data, energies, norm, cmap)

draw_spectrum(spectrum, fitted_spectrum, norm, cmap, edge_range=None)

edge_ax = None

fig = None

figure_hovered

first_button_clicked

forward_button_clicked

frame_controls()

Gives a list of all the UI buttons that are associated with changing the currently active frame.

frame_slider_moved

hist_ax = None

hist_cb = None

last_button_clicked

move_slider(val)

new_cmap_requested

new_component_requested

new_hdf_file_requested

new_hdf_group_requested

new_timestep_requested

new_vrange_requested

open_hdf_file()

play_button_clicked

play_speed_requested

plotting_controls()

Gives a list of all the UI elements that are associated with changing how the frameset is plotted.

presenter_frame_changed

request_new_vrange(bool)

reset_vrange_requested

select_active_hdf_item(item)

set_busy_mode(status)

Either enable or disable the busy mode.

Changes the mouse pointer and disables/enables controls.

Parameters:status (bool) – If truthy, the UI is disabled, otherwise the UI is re-enabled.

set_cmap_list(cmap_list)

set_component_list(component_list)

set_slider_max(val)

set_status_energy(energy)

set_status_index(msg)

set_status_metadata(frames, energies, norm, cmap, extent)

set_status_unit(msg)

set_timestep(idx)

set_timestep_list(timestep_list)

set_window_title(hdf_path)

setup_ui()

show_status_message(message)

spectrum_ax = None

ui = None

update_figure_pixel(xy, xy_unit, px, value)

window = None

xanespy.qt_frameset_presenter module

class xanespy.qt_frameset_presenter.QtFramesetPresenter(frameset, *args, **kwargs)

Bases: PyQt5.QtCore.QObject

Presenter for showing XanesFrameset frames and maps via Qt.

app_ready

Emitted when the application has been created and is ready for drawing.

Type:pyqtSignal

busy_status_changed

Emitted when processing has started or ended.

Type:pyqtSignal

map_data_changed

Emitted when the map data is different and should be re-plotted.

Type:pyqtSignal

map_data_cleared

Emitted when no map data is available and plots can be cleared.

Type:pyqtSignal

active_energy_changed

active_frame = 0

active_frame_changed

active_frame_component = 'real'

active_frames()

active_map()

Returns the active map array if possible. If it doesn’t exist, return None.

active_map_component = 'real'

active_representation = None

active_timestep = 0

add_frame_view(view, threaded=True)

Attach a view to this presenter.

Parameters:

• view (QObject) – The view will be connected to signals that describe changes in frame data.
• threaded (bool, optional) – If true, this view will be added to its own thread before signals get connected

add_map_view(view, threaded=True)

Attach a view to this presenter.

Parameters:

• view (QObject) – The view will be connected to signals that describe changes in map data.
• threaded (bool, optional) – If true, this view will be added to its own thread before signals get connected, giving a snapier UI. Disabling makes testing more straightforward.

app_ready

build_hdf_tree(expand_tree)

Build the items and insert them into the view’s HDF tree based on the structure of the frameset’s HDF file.

busy_status_changed

change_active_frame(new_idx)

change_frame_cmap(new_cmap)

change_frame_component(new_comp)

change_hdf_file(filename)

change_hdf_group(new_item, old_item)

change_map_cmap(new_cmap)

change_map_component(new_comp)

cmap_list_changed

component_list_changed

create_app()

first_frame()

frame_cmap = ''

frame_data_changed

frame_data_cleared

frame_hover_changed

frame_norm()

frame_pixel = None

frame_vrange_changed

hdf_path_changed

hdf_tree_changed

hover_frame_pixel(xy)

last_frame()

launch()

map_cmap = 'plasma'

map_cursor_changed

map_data_changed

map_data_cleared

map_limits_changed

map_norm()

map_pixel_changed

map_spectrum_changed

mean_spectrum_changed

move_map_pixel(vert, horiz)

Move the active pixel by the given amount in each direction.

If the current pixel is not active, this is a no-op.

next_frame()

num_frames = 0

play_frames(start)

prepare_ui(expand_tree=True)

previous_frame()

process_events

refresh_frames()

reset_frame_range()

Reset the frame plotting vmin and vmax based on the currently selected data. VMin will be the 1nd percentile and VMax will be the 99th percentile. The results can be accessed by calling the frame_norm() method.

Returns:

• (vmin, vmax) ((float, float)) – A 2-tuple with the new min and max range.
• None – If current representation is not a valid map, None will be returned.

reset_map_range()

Reset the map plotting vmin and vmax based on the currently selected data. VMin will be the 1st percentile and VMax will be the 99th percentile. This method also caches the values so they can be retrieved via the map_norm() method. If the current representation is not valid map data, then the cached vmin and vmax will be returned with no other changes.

Returns:(vmin, vmax) – A 2-tuple with the current min and max range. Return type:(float, float)

set_frame_vrange(vmin, vmax)

set_map_cursor(x, y)

set_map_pixel(x, y)

set_map_vmax(new_value)

set_map_vmin(new_value)

set_play_speed(new_speed)

Change how fast the play timer ticks. Input speeds should be in the range of 0, 30 with 30 being the fastest. This is converted to timer intervals between 1ms and 1000ms on a exponential scale.

set_timestep(new_timestep)

show_spectrum_fit = False

timer = None

timestep_list_changed

toggle_edge_mask(state)

toggle_spectrum_fit(state)

update_map_limits()

update_maps()

Send the current mapping data to the map_data_changed signal.

This method should be called after anything changes the visual representation of the map. Examples:

• Changing the active representation
• Changing the active complex component (real, imag, etc)
• Changing the colormap
• Changing the map normalization limits
• Changing whether the XAS edge mask is applied

update_spectra()

Get the most recent data for mean and single-pixel spectra and send them out to the signals mean_spectrum_changed and pixel_sepctrum_changed.

update_timestep_list()

use_edge_mask = False

xanespy.qt_map_view module

class xanespy.qt_map_view.QtMapView

Bases: PyQt5.QtCore.QObject

A Qt view for a frameset map. It should be controlled by a presenter.

cmap_changed

Fires when the user changes the colormap via the UI

Type:signal

limits_applied

Fires when the user requests that data be redrawn with new limits.

Type:signal

limits_reset

Fires when the user asks that the norm limits be reset to the data.

Type:signal

cmap_changed

component_changed

connect_presenter(presenter)

Connect to signals for changed presenter state.

create_canvas()

crosshairs = None

edge_mask_toggled

fig = None

hide()

keyboard_nav(event)

latest_cmap = 'plasma'

limits_applied

limits_reset

map_clicked

map_hovered

map_moved

map_vmax_changed

map_vmin_changed

mouse_clicked_canvas(mouse_event)

mouse_in_canvas(mouse_event)

plot_histogram_data(map_data, norm, cmap, extent)

plot_map_data(map_data, norm, cmap, extent)

plot_spectrum(spectrum, fitted_spectrum, norm, cmap, edge_range)

redraw_canvas()

redraw_crosshairs(xy)

Draw a set of crosshairs on the map at location given by xy.

set_cmap_list(new_list)

set_component_list(new_list)

set_map_limits(vmin, vmax, step, decimals)

setup_ui()

show()

spectrum_fit_toggled

ui = None

update_crosshair_labels(xy, pixel, value)

update_cursor_labels(xy, pixel, value)

update_spectrum_ui(spectrum, fitted_spectrum, norm, cmap, edge_range)

window = None

xanespy.txmstore module

Tools for accessing TXM data stored in an HDF5 file.

class xanespy.txmstore.TXMDataset(name, context=None, dtype=None)

Bases: object

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

class xanespy.txmstore.TXMStore(hdf_filename: str, parent_name: str, data_name=None, mode='r')

Bases: object

Wrapper around HDF5 file that stores TXM data.

It has a series of descriptors and properties that return the corresponding HDF5 dataset object; the TXMStore().attribute.value pattern can be used to get pure numpy arrays directly. These objects should be used as a context manager to ensure that the file is closed, especially if using a writing mode:

with TXMStore() as store:

# Do stuff with store here

Parameters:

• hdf_filename (str) – Path to the HDF file to be used.
• parent_name (str) – Name of the top-level HDF5 group.
• data_name (str) – Name of the second level HDF5 group, used for specific data iterations (eg. imported, aligned)
• mode (str) – Eg. ‘r’ for read-only, ‘r+’ for read-write. Passed directly to h5py.File constructor.

VERSION = 1

close()

cluster_fit

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

data_group()

Retrieve the currently active second-level HDF5 group object for this file and groupname. Ex. “imported” or “aligned_frames”.

data_name

data_tree()

Create a tree of the possible groups this store could access. The first level is samples, then data_groups (ie. same sample but different analysis status), then representations.

edge_mask

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

energies

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

filenames

fit_parameters

fork_data_group(dest, src=None)

Turn on different active data group for this store. This method deletes the existing group and copies symlinks from the current one.

frame_source(name)

Get the name of the frames that went into creating a map.

frameset_names()

Returns a list of all the valid map representations.

get_dataset(name)

Attempt to open the requested dataset.

Returns:data – An open HDF5 dataset Return type:hyp5.Dataset Raises:exceptions.GroupKeyError – If the dataset does not exist in the file.

get_frames(name)

Return the source frame data for the given data name.

This is similar to get_dataset except that if the data are a map, then get the frames that went into making it.

Parameters:name (str) – The dataset name for which to retrieve frames. Returns:dataset – The requested frameset. If the dataset is actually a map, as determined by the “context” attribute, then the related frame source attribute will be retrieved. Return type:h5py.Dataset

has_dataset(name)

Return a boolean indicated whether this dataset exists in the HDF file.

intensities

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

intensity_mean

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

latest_data_name

linear_combination_parameters

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

linear_combination_residuals

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

linear_combination_sources

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

map_names()

Returns a list of all the valid map representations.

open_file(filename, mode)

optical_depth_mean

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

optical_depths

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

original_positions

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

parent_group()

Retrieve the top-level HDF5 group object for this file and groupname.

particle_labels

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

pixel_sizes

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

pixel_unit

references

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

relative_positions

(x, y, z) position values for each frame.

replace_dataset(name, data, context=None, attrs={}, compression=None, *args, **kwargs)

Wrapper for h5py.create_dataset that removes the existing dataset if it exists.

Parameters:

• name (str) – HDF5 groupname name to give this dataset.
• data (np.ndarray) – Numpy array of data to be saved.
• context (str, optional) – Specifies what kind of data is stored. Eg. “frameset”, “metadata”, “map”.
• attrs (dict, optional) – Dictionary containing HDF5 metadata attributes to be set on the resulting dataset.
• compression (str, optional) – What type of compression to use. See HDF5 documentation for options.
• *args – Arguments to pass to h5py’s create_dataset method.
• **kwargs – Keyword arguments to pass to h5py’s create_dataset method.

segments

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

signal_map

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

signal_method

String describing how the previously extracted signals were calculated.

signal_weights

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

signals

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

timestamps

timestep_names

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

validate_parent_group(name)

Retrieve the real parent group name for a possible parent_group.

If name is None and only one group exists in the file, then that group name will be returned. If name is in the file, then name will be returned. If name is not in the file, a GroupKeyError will be raised.

whiteline_fit

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

whiteline_max

Data descriptor for accessing HDF datasets.

Parameters:

• name (str) – The dataset name in the HDF file.
• context (str, optional) – Type of dataset this is: frameset, map, metadata, etc.
• dtype (np.dtype, optional) – The data-type to use when saving new data to disk. Using lower precision datatypes can save significant disk space.

xanespy.utilities module

A collection of classes and functions that arent’ specific to any one type of measurement. Also, it defines some namedtuples for describing coordinates.

xanespy.utilities.Extent

alias of xanespy.utilities.extent

class xanespy.utilities.Pixel(vertical, horizontal)

Bases: tuple

horizontal

Alias for field number 1

vertical

Alias for field number 0

xanespy.utilities.broadcast_reverse(array, shape, *args, **kwargs)

Take the array and extends it as much as possible to match shape. Similar to numpy’s broadcast_to function, but starts with the most significant axis. For example, if array has shape (7, 29), it can be broadcast to (7, 29, 1024, 1024).

xanespy.utilities.foreach(f, l, threads=4, return_=False)

Apply f to each element of l, in parallel

xanespy.utilities.get_component(data, name)

If complex, turn to given component, otherwise return original data.

Parameters:

• data – Numerical (presumably complex-valued) data to be reduced to a component.
• name (str) – One of (‘modulus’, ‘phase’, ‘real’, ‘imag’)

Returns:

Input data converted to requested component.

Return type:

data

xanespy.utilities.is_kernel()

Detect whether or not we’re running inside an IPython kernel. NB: This does not distinguish between eg IPython notebook and IPython QtConsole.

xanespy.utilities.parallel_map(f, l, threads=4)

xanespy.utilities.pixel_to_xy(pixel, extent, shape)

Take an xy location on an image and convert it to a pixel location suitable for numpy indexing.

class xanespy.utilities.position(x, y, z)

Bases: tuple

x

Alias for field number 0

y

Alias for field number 1

z

Alias for field number 2

xanespy.utilities.prog(iterable=None, leave=None, dynamic_ncols=True, smoothing=0.01, *args, **kwargs)

A progress bar for displaying how many iterations have been completed.

This is mostly just a wrapper around the tqdm library. args and kwargs are passed directly to either tqdm.tqdm or tqdm.tqdm_notebook. This function also takes into account the value of USE_PROG defined in this module. If tqdm is no installed, then calls to prog will just return the iterable again.

Parameters:

• iterable – Iterable to decorate with a progressbar. See tqdm.tqdm documentation for more details.
• leave (bool, optional) – Whether to leave the progress bar in the stream after it’s completed. If omitted, will depend on terminal used.
• dynamic_ncols (bool, optional) – Whether to adapt dynamically to the width of the environment.
• args – Positional arguments passed directly to tqdm or tqdm_notebook.
• kwargs – Keyword arguments passed directly to tqdm or tqdm_notebook.

class xanespy.utilities.shape(rows, columns)

Bases: tuple

columns

Alias for field number 1

rows

Alias for field number 0

xanespy.utilities.xy_to_pixel(xy, extent, shape)

Take an xy location on an image and convert it to a pixel location suitable for numpy indexing.

class xanespy.utilities.xycoord(x, y)

Bases: tuple

x

Alias for field number 0

y

Alias for field number 1

xanespy.xanes_frameset module

Class definitions for working with a whole stack of X-ray microscopy frames. Each frame is a micrograph at a different energy. A frameset then is a three-dimenional dataset with of dimenions (energy, row, column).

class xanespy.xanes_frameset.XanesFrameset(filename, edge, groupname=None)

Bases: object

A collection of TXM frames at different energies moving across an absorption edge. Iterating over this object gives the individual Frame() objects. The class assumes that the data have been imported into an HDF file.

active_group = ''

align_frames(reference_frame='mean', method: str = 'cross_correlation', template=None, passes=1, median_filter_size=None, commit=True, component='modulus', plot_results=True, results_ax=None, quiet=False)

Use cross correlation algorithm to line up the frames.

All frames will have their sample position set to (0, 0) since we don’t know which one is the real position. This operation will interpolate between pixels so introduces error. If multiple passes are performed, the translations are saved and combined at the end so this error is only introduced once. Using the commit=False argument allows for multiple different types of registration to be performed in sequence, since uncommitted translations will be applied before the next round of registration.

Parameters:

• reference_frame (2-tuple, str, optional) – The index of the frame to which all other frames should be aligned. If None, the frame of highest intensity will be used. If “mean” (default) or “median”, the average or median of all frames will be used. If “max”, the frame with highest optical_depth is used. Otherwise, a 2-tuple with (timestep, energy) should be provided. This attribute has no effect if template matching is used.
• method (str, optional) –

  Which technique to use to calculate the translation

  • ”cross_correlation” (default)
  • ”template_match”

  (If “template_match” is used, the template argument should also be provided.)

• template (np.ndarray, optional) – Image data that should be matched if the template_match method is used.
• passes (int, optional) – How many times this alignment should be done. Default: 1.
• median_filter_size (int, optional) – If provided, a median filter will be applied to each frame. The value of this parameter determines how large the kernel is: 3 creates a (3, 3) kernel; (3, 5) creates a (3, 5) kernel; etc.
• commit (bool, optional) – If truthy (default), the final translation will be applied to the data stored on disk by calling self.apply_translations(crop=True) after all passes have finished. component : What component of the data to use: ‘modulus’, ‘phase’, ‘imag’ or ‘real’. plot_results : If truthy (default), plot the root-mean-square of the translation distance for each pass. results_ax : optional If plot_results is true, this axes will be used to receive the plot. quiet : bool, optional Whether to suppress the progress bar, etc.
• component (str, optional) – For complex data, which component to use: modulus, phase, real, imag.
• plot_results (bool, optional) – If true, a boxplot will be plot with the RMS shifts for each pass.
• results_ax (mpl.Axes, optional) – If plot_results is true, this Axes will receive the plot. If omitted, a new axes will be created.
• quiet (bool, optional) – Suppress the progress bar

apply_internal_reference()

Use a portion of each frame for internal reference correction.

This function will extract an $I_0$ from the background by thresholding. Then calculate the optical depth by

\[OD = ln(\frac{I_0}{I})\]

This method is compatible with complex intensity data.

apply_median_filter(size, representation='optical_depths')

Permanently apply a median filter to a frameset.

Parameters:

• size (4-tuple) – Dimensions of the kernel to use for filtering in order of (time, energy, row, col).
• representation (str, optional) – Which frameset representation to use for filtering.

apply_transformations(crop=True, commit=True, quiet=False)

Take any transformations staged with self.stage_transformations() and apply them. If commit is truthy, the staged transformations are reset.

Parameters:

• crop (bool, optional) – If truthy, the images will be cropped after being translated, so there are not edges. If falsy, the images will be wrapped.
• commit (bool, optional) – If truthy, the changes will be saved to the HDF5 store for optical depths, intensities and references, and the staged transformations will be cleared. Otherwise, only the optical_depth data will be transformed and returned.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

Returns:

out – Transformed array of the optical depth frames.

Return type:

np.ndarray

calculate_maps()

Generate a set of maps based on pixel-wise Xanes spectra: whiteline position, particle labels.

This method does not do any advanced analysis, so something like ~xanespy.xanes_frameset.XanesFrameset.fit_spectra may be necessary.

calculate_mean_frames()

calculate_signals(n_components=2, method='nmf', frame_source='optical_depths', edge_mask=True)

Extract signals and assign each pixel to a group, then save the resulting RGB cluster map.

Parameters:

• n_components (int, optional) – The number of signals and number of clusters into which the data will be separated.
• method (str, optional) – The technique to use for extracting signals. Currently only “nmf” is supported.
• frame_source (str, optional) – Name of the frame-set to use as the input data.
• edge_mask (bool, optional) – If truthy (default), only those pixels passing the edge filter will be considered.

calculate_whitelines(edge_mask=False)

Calculate and save a map of the whiteline position of each pixel by calculating the energy of simple maximum optical_depth.

Parameters:edge_mask (-) – be fit and the remaning pixels will be set to a default value. This can help reduce computing time.

clear_caches()

Clear cached function values so they will be recomputed with fresh data

cmap = 'plasma'

components()

Retrieve a list of valid representations for these data.

data_name

data_tree()

Wrapper around the TXMStore.data_tree() method.

edge = None

edge_mask

Calculate a mask for what is likely active material at this edge.

Parameters:

• sensitivity (optional) – A multiplier for the otsu value to determine the actual threshold. Higher values give better statistics, but might include the active material, lower values give worse statistics but are less likely to include active material.
• min_size (optional) – Objects below this size (in pixels) will be removed. Passing zero (default) will result in no effect.

endtime(timeidx=None)

Determine the latest timestamp amongst all of the frames.

Parameters:timeidx (int, optional) – Which timestep to use for finding the end time. If omitted or None (default), all timesteps will be checked. Returns:start_time – Naive datetime representing the latest known frame for this time index. Timezone will always be UTC no matter where the data were collected. Return type:np.datetime64

energies

Return the array of beam energies for the given time index.

Returns:energies – A 1-dimensional array with the energy for each frame. Return type:np.ndarray

export_beamer_file(basename, map_names=None, frameset_names=None, time_idxs=None, groupby='dataset')

Plot maps and create a beamer file.

The resulting beamer file won’t be compilable by itself, but should be included in a beamer slide-deck with the \input{} directive. The pgf package must be included with \usepackage{pgf} in the preamble.

Parameters:

• basename (str) – Filename of the beamer output. Will be overwritten if it exists. Pgf figures will use this as a prefix.
• map_names (list, optional) – Representations to use for plotting maps. If omitted, anything resembling a map will be used.
• frameset_names (list, optional) – Representations to use for plotting spectra. If omitted, anything resembling a frameset will be used.
• time_idx (list, optional) – Indices of timesteps to use for plotting maps. If omittedd, all timesteps will be used.
• dataset (str, optional) – Determines which dimension changes quickly. Options are “dataset” and “timestep”.

extent

Determine physical dimensions for axes values.

If an index is given, it will first be applied to the frames array. For any remaining dimensions besides the last two, the median will be taken. For an array of extents for each frame, use the extent_array method.

Parameters:

• representation (str, optional) – Name for which dataset to use.
• idx (int, optional) – Index for choosing a frame. Any valid numpy index is allowed, eg. ... (default) uses all frame.

Returns:

extent – The spatial extent for the frame with order specified by utilities.Extent

Return type:

tuple

fit_linear_combinations(sources, component='real', name='linear_combination', representation='optical_depths', *args, **kwargs)

Take a set of sources and fit the spectra with them.

Saves to the representation “linear_combinations”. Also creates “linear_combination_sources” and “linear_combination_residuals” datasets.

Parameters:

• sources (numpy.ndarray) – Sources to use for fitting the combinations.
• component (str, optional) – Complex component to use before fitting.
• name (str, optional) – What to call the resulting dataset in the hdf file.
• representation (str, optional) – What dataset to use as input for fitting.
• kwargs (args,) – Passed on to self.fit_spectra.

Returns:

• fits (numpy.ndarray) – The weights (as frames) for each source.
• residuals (numpy.ndarray) – Residual error after fitting, as maps.

fit_spectra(func, p0, pnames=None, name=None, edge_filter=True, nonnegative=False, component='real', representation='optical_depths', dtype=None, quiet=False)

Fit a given function to the spectra at each pixel.

The fit parameters will be saved in the HDF dataset “{name}_params” based on the parameter name. RMS residuals for each pixel will be saved in “{name}_residuals”.

Parameters:

• func (callable, str) – The function that will be used for fitting. It should match func(p0, p1, ...) where p0, p1, etc are the fitting parameters. Some useful functions can be found in the xanespy.fitting module.
• p0 (np.ndarray) – Initial guess for parameters, with similar dimensions to a frameset. Example, fitting 3 sources (plus offset) for a (1, 40, 256, 256) 40-energy frameset requires p0 to be (1, 4, 256, 256).
• pnames (str, optional) – An object with __str__ that will be saved as metadata giving the parameters’ names.
• name (str, optional) – What to call this fit in the HDF5 file. Use this to allow subsequent fits against the same dataset to be saved. If None, we will attempt look for func.name, then lastly we’ll use “fit”.
• edge_filter (bool, optional) – If true, only compute pixels that pass an edge filter.
• nonnegative (bool, optional) – If true (default), negative parameters will be avoided. This can also be a tuple to allow for fine-grained control. Eg: (True, False) will only punish negative values in the first of the two parameters.
• component (str, optional) – What to use for complex-valued functions.
• representation (str, optional) – Which set of frames to use for fitting.
• dtype (numpy.dtype, optional) – Specify a datatype to convert all values to. This helps avoid fit failure due to precision errors. If omitted, the function will also check for func.dtype.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

Returns:

• params (numpy.ndarray) – The fit parameters (as frames) for each source.
• residuals (numpy.ndarray) – Residual error after fitting, as maps.

fitting_param_names(representation='fit_parameters')

Get the human-readable names of the fit parameters.

fork_data_group(dest, src=None)

Turn on different active data for this frameset’s store object. Similar to switch_data_group except that this method deletes the existing group and copies symlinks from the current one.

Parameters:

• dest (str) – Name for the data group.
• src (str) – String with the name of the data group to copy from. If None (default), the current data group will be used.

frame_shape(representation='optical_depths')

Return the shape of the individual energy frames.

frames

Return the frames for the given time index.

If representation is really mapping data, then the source frames will be returned.

Parameters:

• timeidx (int) – Index for the first dimension of the combined data array.
• representation (str) – The group name for these data. Eg “optical_depths”, “whiteline_map”, “intensities”

Returns:

frames – A 3-dimensional array with the form (energy, row, col).

Return type:

np.ndarray

gui_viewer()

Launch a Qt GUI for inspecting the data.

has_representation(representation)

hdf_path(representation=None)

Return the hdf path for the active group.

Parameters:representation (str, optional) – Name of third-level group to use. If omitted, the path to the parent group will be given. Returns:path – The path to the current group in the HDF5 file. Returns an empty string if the representation does not exists. Return type:str

label_particles(min_distance=20)

Use watershed segmentation to identify particles.

Parameters:min_distance (int, optional) – Controls how selective the algorithm is at grouping areas into particles. Lower numbers means more particles, but might split large particles into two.

line_spectra(xy0, xy1, representation='optical_depths', timestep=0)

Return an array of spectra on a line between two points.

This is effectively nearest neighbor interpolation between two (x, y) pairs on the frames.

Returns:

spectra – An array of spectra, one for each point on the line.

Return type:

np.ndarray

Parameters:

• xy0 (2-tuple) – Starting point for the line.
• xy1 (2-tuple) – Ending point for the line.

map_data

Return map data for the given time index and representation.

If representation is not really mapping data, then the result will have more dimensions than expected.

Parameters:

• timeidx (int) – Index for the first dimension of the combined data array. If the underlying map data has only 2 dimensions, this parameter is ignored.
• representation (str) – The group name for these data. Eg “optical_depths”, “whiteline_map”, “intensities”

Returns:

map_data – A 2-dimensional array with the form (row, col).

Return type:

np.ndarray

mean_frame(representation='optical_depths')

Return the mean value with the same shape as an individual frame.

normalize(plot_fit=False, new_name='normalized')

Correct for background material not absorbing at this edge. Uses method described in DOI 10.1038/ncomms7883: fit line against material that fails edge_jump_filter and use this line to correct entire frame.

Parameters:

• plot_fit (-) –
• line. (best-fit) –

num_energies

num_timesteps

parent_name = None

particle_regions(intensity_image=None, labels=None)

Return a list of regions (1 for each particle) sorted by area. (largest first). This requires that the label_particles method be called first.

Parameters:

• intensity_image (np.ndarray, optional) – 2D array passed on to the skimage regionprops function to determine what shows up in the image for each particle.
• labels (np.ndarray, optional) – Array of the same shape as the map, with the particles segmented. If None (default), the particle_labels attribute of the TXM store will be used.

particle_series(map_name='whiteline_max')

Generate an array of values from map_name averaged across each particle.

Returns: A 2D array where the first dimension is particles and the second is the first dimension of the map dataset (usually time).

pixel_size(representation='optical_depths', timestep=0)

Return the size of the pixel (with units set by pixel_unit).

pixel_unit()

Return the unit of measure for the size of a pixel.

plot_beamer_maps(basename, map_names=None, time_idxs=None, groupby='dataset', tight_layout=True)

Export maps to pgf and prepare a jinja context.

This method is similar to export_beamer_file except that it doesn’t actually create the .tex file. This can be useful if you desire more control over the beamer layout.

Parameters:

• basename (str) – The base name to be used for generating the .pgf files.
• map_names (list, optional) – Representations to use for plotting maps. If omitted, anything resembling a map will be used.
• time_idxs (list, optional) – Indices of timesteps to use for plotting maps. If omittedd, all timesteps will be used.
• groupby (str, optional) – Determines which dimension changes quickly. Options are “dataset” and “timestep”.
• tight_layout (bool, optional) – Whether to call the matplotlib.tight_layout() function, useful for things with colorbars, etc.

Returns:

context – Context dictionary appropriate for passing into the jinja2 template engine.

Return type:

dict

plot_beamer_spectra(basename, frameset_names=None, time_idxs=None, groupby='dataset')

Export spectra to pgf and prepare a jinja context.

This method is similar to export_beamer_file except that it doesn’t actually create the .tex file. This can be useful if you desire more control over the beamer layout.

Parameters:

• basename (str) – The base name to be used for generating the .pgf files.
• frameset_names (list, optional) – Representations to use for plotting maps. If omitted, anything resembling a map will be used.
• time_idxs (list, optional) – Indices of timesteps to use for plotting maps. If omittedd, all timesteps will be used.
• groupby (str, optional) – Determines which dimension changes quickly. Options are “dataset” and “timestep”.

Returns:

context – Context dictionary appropriate for passing into the jinja2 template engine.

Return type:

dict

plot_frame(idx, ax=None, cmap='gray', *args, **kwargs)

Plot the frame with given index as an image.

plot_histogram(plotter=None, timeidx=None, ax=None, vmin=None, vmax=None, goodness_filter=False, representation='whiteline_fit', component='real', active_pixel=None, bins='energies', *args, **kwargs)

Use a default frameset plotter to draw a map of the chemical data.

plot_line_scans(representation='optical_depths', direction='horizontal', idx=None, ax=None, form='lines', time_idx=0)

Plot spectrum for each point on a line.

The direction and idx parameters control which lines are scanned. Eg. direction="vertical" and idx=3 will plot a spectrum for each position in the 4th column.

Parameters:

• representation (str, optional) – Which frameset to use for plotting.
• direction (str, optional) – Whether to do lines scans in “horizontal” (default) or “vertical” orientation.
• idx (int, optional) – Which row or column to use for line scans. If omitted, frames will be averaged across the unchanging dimension.
• ax (mpl.Axes, optional) – Matplotlib axes to use for plotting. If omitted, a new Axes will be created.
• form (str, optional) – How to plot the data: ‘lines’ or ‘map’.
• timeidx (int, optional) – Which time step to use for plotting line scans.

Returns:

List of line of image artists return from plotting command

Return type:

artists

plot_map(ax=None, map_name='whiteline_fit', timeidx=0, vmin=None, vmax=None, median_size=0, component='real', *args, **kwargs)

Prepare data and plot a map of whiteline positions.

Parameters:median_size (int) – Kernel size for the median rank filter.

plot_map_pixel_spectra(pixels, map_ax=None, spectra_ax=None, map_name='whiteline_map', timeidx=0, step_size=0, *args, **kwargs)

Plot the frameset’s map and highlight some pixels on it then plot those pixel’s spectra on another set of axes.

Parameters:

• pixels (iterable) – An iterable of 2-tuples indicating which (row, column) pixels to highlight.
• map_ax (optional) – A matplotlib axes object to put the map onto. If None, a new 2-wide subplot will be created for both map_ax and spectra_ax.
• spectra_ax (optional) – A matplotlib axes to be used for plotting spectra. Will only be used if map_ax is not None.
• map_name (str, optional) – Name of the map to use for plotting. It will be passed to the TXM store object and retrieved from the hdf5 file. If falsy, no map will be plotted.
• timeidx (int, optional) – Index of which timestep to use (default: 0).
• kwargs (args,) – Passed to plots.plot_pixel_spectra()

plot_mean_image(ax=None, component='modulus', representation='optical_depths', cmap='gray', *args, **kwargs)

plot_signal_map(ax=None, signals_idx=None, interpolation=None)

Plot the map of signal strength for signals extracted from self.calculate_signals().

Parameters:

• ax (-) – axes object is created.
• signals_idx (-) –
• as a numpy array index. Special value None (default) (passed) –
• first three signals will be plotted. (means) –
• interpolation (-) – How to smooth the image when plotting.

plot_signals(cmap='viridis')

Plot the signals from the previously extracted data. Requires that self.store().signals and self.store().signal_weights be set.

plot_spectrum(ax=None, pixel=None, norm_range=None, normalize=False, representation='optical_depths', show_fit=False, edge_jump_filter=False, linestyle=':', timeidx=0, *args, **kwargs)

Calculate and plot the xanes spectrum for this field-of-view.

Parameters:

• ax (optional) – matplotlib axes object on which to draw
• pixel (2-tuple, optional) – Coordinates of a specific pixel on the image to plot.
• normalize (bool, optional) – If truthy, will set the pre-edge at zero and the post-edge at 1.
• show_fit (bool, optional) – If truthy, will use the edge object to fit the data and plot the resulting fit line.
• edge_jump_filter (bool, optional) – If truthy, will only include those values that show a strong absorbtion jump across this edge.
• kwargs (args,) – Passed to plotting functions.

segment_materials(thresholds, representation='optical_depths', component='real')

Split the frames into different materials based on mean values.

This is most useful with a metric that is unique to a given material. For example, the phase representation of ptychography data can be used to determine which material is which. Results will be stored in XanesFrameset().store().segments.

Parameters:

• thresholds (tuple) – The boundary values to use for segmentation. If N tresholds are given, the data will be split into N+1 segments.
• representation (str, optional) – What kind of data the thresholds represent.
• component (str, optional) – Complex-value representation to use. Default is real value. For ptychography data, ‘phase’ is probably better.

spectra(edge_filter=False)

Return a two-dimensional array of spectra for all the pixels in shape of (pixel, energy).

Parameters:(bool or str) (edge_jump_filter) – truthy, only pixels that pass the edge jump filter are used to calculate the spectrum. If “inverse” is given, then the edge jump filter is logically not-ted and calculated with a more conservative threshold.

spectrum(pixel=None, edge_jump_filter=False, representation='optical_depths', index=0, derivative=0)

Collapse the frameset down to an energy spectrum.

Any dimensions (besides the energy dimension) that remain after applying the arguments below, will be averaged to give the final intensity at each energy.

Returns:

spectrum – A pandas Series with the spectrum.

Return type:

pd.Series

Parameters:

• pixel (tuple, optional) – A 2-tuple that causes the returned series to represent the spectrum for only 1 pixel in the frameset. If None, a larger part of the frame will be used, depending on the other arguments.
• edge_jump_filter (bool or str, optional) – If truthy, only pixels that pass the edge jump filter are used to calculate the spectrum. If “inverse” is given, then the edge jump filter is logically not-ted and calculated with a more conservative threshold.
• representation (str, optional) – What kind of data to use for creating the spectrum. This will be passed to TXMstore.get_dataset()
• index (int, optional) – Which step in the frameset to use. When used to index store().optical_depths, this should return a 3D array like (energy, rows, columns).
• derivative (int, optional) – Calculate a derivative of the spectrum before returning it. If less than 1 (default), no derivative is calculated.

stage_transformations(translations=None, rotations=None, center=(0, 0), scales=None)

Allows for deferred transformation of the frame data.

Since each transformation introduces interpolation error, the best results occur when the translations are saved up and then applied all in one shot. Takes a combination of arrays of translations (x, y), rotations and/or scales and saves them for later application. This method should be used in conjunction apply_transformations().

All three arguments should have shapes that are compatible with the frame data, though this is not strictly enforced for now. Rotation will necessarily have one less degree of freedom than translation/scale values.

Example Shapes:

Frames	Translations	Rotations	Scales
(10, 48, 1024, 1024)	(10, 48, 2)	(10, 48, 1)	(10, 48, 2)
(10, 48, 1024, 1024, 1024)	(10, 48, 3)	(10, 48, 2)	(10, 48, 3)

Parameters:

• translations (np.ndarray) – How much to move each axis (x, y[, z]).
• rotations (np.ndarray) – How much to rotate around the origin (0, 0) pixel.
• center (2-tuple) – Where to set the origin of rotation. Default is the first pixel (0, 0).
• scales (np.ndarray) – How much to scale the image by in each dimension (x, y[, z]).

starttime(timeidx=None)

Determine the earliest timestamp amongst all of the frames.

Parameters:timeidx (int, optional) – Which timestep to use for finding the start time. If omitted or None (default), all timesteps will be checked. Returns:start_time – Naive datetime representing the earliest known frame for this timeidx. Timezone will always be UTC no matter where the data were collected. Return type:np.datetime64

store(mode='r')

Get a TXM Store object that saves and retrieves data from the HDF5 file. The mode argument is passed to h5py as is. This method should be used as a context manager, especially if mode is something writeable:

# The 'r+' creates the file or appends if one exists
with self.store(mode='r+') as store:
    # Do stuff with the store...
    img = store.optical_depths[0,0]

subtract_surroundings(sensitivity: float = 1.0)

Use the edge mask to separate “surroundings” from “sample”, then subtract the average surrounding optical_depth from each frame. This effectively removes effects where the entire frame is brighter from one energy to the next.

Parameters:sensitivity (optional) – A multiplier for the otsu value to determine the actual threshold. Higher values give better statistics, but might include the active material, lower values give worse statistics but are less likely to include active material.

timestamps()

Retrieve an array with the timestamp for each scan.

This will be a numpy array with the datetime64 dtype. Each frame has both a start and end time-stamp. Depending on the beamline, the individual energy frames might have timestamps based on the whole XANES scan. These timestamps are in UTC since numpy’s datetime64 has no timezone support.

Returns:timestamps – The timestamps for each energy frame with a shape described as (num_timesteps, num_energies, 2), where the last axis is for the start and end of the frame. Return type:np.ndarray

timestep_names

xanespy.xanes_math module

Module containing all the computationally demanding functions. This allows for easy optimization of parallelizable algorithms and better test isolation. Most functions will operate on large arrays of data.

class xanespy.xanes_math.FramesPool(processes=None, initializer=None, initargs=(), maxtasksperchild=None, context=None)

Bases: multiprocessing.pool.Pool

A multiprocessing pool that iterates over frames even if there are extra dimensions.

Parameters:processes (int, optional) – How many processes to spawn. If omitted, twice the number of CPUs will be used.

map(func, frames, spatial_dims=2, chunksize=None, desc=None)

Apply the function to each frame in frames and return the result.

Parameters:

• func (callable) – Function to be applied to each frame.
• frames (np.ndarray) – Array of frames to operate on. The last dimensions are considered spatial dimensions.
• spatial_dims (int, optional) – How many of the last dimensions are spatial frame dimensions, 2D, 3D, etc.
• chunksize (int, optional) – How many frames to process at a time.
• desc (str, optional) – If provided, a progress bar will be displayed.

Returns:

result – The result of all calculations. Similar in shape to frames except that the spatial dimensions are replaced by whatever is returned by func.

Return type:

np.ndarray

xanespy.xanes_math.apply_internal_reference(intensities, out=None, quiet=False)

Apply a reference correction to complex data to convert intensities into refractive index. \(I_0\) is determined by separating the pixels into background and foreground using Otsu’s method.

Arrays intensities and out must all have the same shape where the last two dimensions are image rows and column.

xanespy.xanes_math.apply_mosaic_reference(intensity, reference)

Use a single reference frame to calculate the reference for a mosaic of intensity frames.

Returns:

- out – Same shape as intensity (I) but with optical depth: ln(I/I0) where I0 is the reference frame.

Return type:

ndarray

Parameters:

• intensity (-) – Intensity data image of the sample. It’s shape must be a whole multiple of the shape of reference.
• reference (-) – A reference image with no sample that will be applied.

xanespy.xanes_math.apply_references(intensities, references, out=None, quiet=False)

Apply a reference correction to convert intensity values to optical depth.

The formula \(-ln\frac{intensities}{references}\) is used to calculate the new values. Arrays intensities, references and out must all have the same shape where the last two dimensions are image rows and columns.

Parameters:

• intensities (np.ndarray) – Sample input signal data.
• references (np.ndarray) – Background input signal data. Must be the same shape as intensities.
• out (np.ndarray, optional) – Array to receive the results.
• quiet (bool, optional) – Whether to suppress progress bar, etc.

xanespy.xanes_math.direct_whitelines(spectra, energies, edge, quiet=False)

Takes an array of X-ray optical_depth spectra and calculates the positions of maximum intensities over the near-edge region.

Parameters:

• spectra (np.array) – 2D numpy array of optical_depth spectra where the last dimension is energy.
• energies (np.array) – Array of X-ray energies in electron-volts. Must be broadcastable to the shape of spectra.
• edge – An XAS Edge object that describes the absorbtion edge in question.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

Returns:

out – Array with the whiteline position of each spectrum.

Return type:

np.ndarray

xanespy.xanes_math.downsample_array(arr, factor, method='mean', axis=None)

Reduced the shape of an image in powers of 2.

Increases in the signal-to-noise can be achieved by sacrificing spatial resolution: a (1024, 1024) image can be converted to (512, 512) by taking the mean of each (2, 2) block. The factor parameter controls how agressive this conversion is. Extra pixels get dropped: eg (1025, 1024) -> (512, 512).

arr	factor	block	out
(1024, 1024) (1024, 1024) (1024, 1024) (1024, 1024)	0 1 2 3	N/A (2, 2) (4, 4) (8, 8)	(1024, 1024) (512, 512) (256, 256) (128, 128)

Parameters:

• arr (np.ndarray) – Input array to be downsampled.
• factor (int) – Downsampling factor. A value of 0 returns the original array.
• method (str, optional) – How to convert a (eg 2x2) block to a single value. Valid choices are ‘mean’ (default), ‘median’, ‘sum’.
• axis (tuple, optional) – Which axes to use for reduction. If omitted, all axes will be used.

Raises:

• ValueError – Negative downsampling factors.
• ValueError – method parameter is not one of the valid options.

Returns:

out – The downsample array.

Return type:

np.ndarray

xanespy.xanes_math.extract_signals_nmf(spectra, n_components, nmf_kwargs=None, mask=None)

Extract the signal components present in the given spectra using non-negative matrix factorization. Input data can be negative, but it will be shifted up, processed, then shifted down again.

Parameters:

• spectra (numpy.ndarray) – A numpy array of observations where the last axis is energy.
• n_components (int) – How many components to extract from the data.
• nmf_kwargs (dict, optional) – Keyword arguments to be passed to the constructor of the estimator.

Returns:

• components, weights (numpy.ndarray) – Extracted components and weights for each pixel-component
• combination.

xanespy.xanes_math.iter_indices(data, leftover_dims=1, desc=None, quiet=False)

Accept an array of frames, indices, etc. and generate slices for each frame.

Assumes the last two dimensions of data are rows and columns. All other dimensions will be iterated over.

Parameters:

• data (np.ndarray) – Data to iterate over.
• leftover_dims (int, optional) – Integer describing which dimensions should not be iterated over. Eg. if data is 3D array and leftover_dims == 1, only first two dimenions will be iterated.
• desc (str, optional) – String to put in the progress bar.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

xanespy.xanes_math.k_edge_jump(frames: numpy.ndarray, energies: numpy.ndarray, edge)

Determine what the difference is between the post_edge and the pre_edge.

xanespy.xanes_math.k_edge_mask(frames: numpy.ndarray, energies: numpy.ndarray, edge, sensitivity: float = 1, min_size=0)

Calculate a mask for what is likely active material at this edge. This is done by comparing the edge-jump to the standard deviation. Foreground material will be identified when the edge-jump accounts for most of the standard deviation.

Parameters:

• frames (numpy.ndarray) – Array with images at different energies.
• energies (numpy.ndarray) – X-ray energies corresponding to images in frames. Must have the same shape along the first dimenion as frames.
• edge (KEdge) – A xanespy.edges.KEdge object that contains a description of the elemental edge being studied.
• sensitivity (float, optional) – A multiplier for the otsu value to determine the actual threshold.
• min_size (int, optional) – Objects below this size (in pixels) will be removed. Passing zero (default) will result in no effect.

Returns:

mask – A boolean mask with the same shape as the last two dimensions of frames where True pixels are likely to be background material.

Return type:

numpy.ndarray

xanespy.xanes_math.l_edge_mask(frames: numpy.ndarray, energies: numpy.ndarray, edge, sensitivity: float = 1, frame_dims=2, min_size=0)

Calculate a mask for what is likely active material at this edge. This is done by comparing each spectrum to the overall spectrum using the dot product. A normalization is first applied to mitigate differences in total intensity.

Parameters:

• frames (np.ndarray) – Array with images at different energies.
• energies (np.ndarray) – X-ray energies corresponding to images in frames. Must have the same shape along the first dimenion as frames.
• edge (xanespy.edges.Edge) – An Edge object that contains a description of the elemental edge being studied.
• sensitivity (float, optional) – A multiplier for the otsu value to determine the actual threshold.
• frame_dims (int, optional) – The number of dimensions that each frame has. Eg, 2 means each frame is a two-dimensional image.
• min_size (float, optional) – Objects below this size (in pixels) will be removed. Passing zero (default) will result in no effect.

Returns:

mask – A boolean mask with the same shape as the last two dimensions of frames where True pixels are likely to be background material.

Return type:

np.ndarray

xanespy.xanes_math.particle_labels(frames: numpy.ndarray, energies: numpy.ndarray, edge, min_distance=20)

Prepare a map by segmenting the images into particles.

Parameters:frames (numpy.ndarray) – An array of images, each one at a different energy. These will be merged and used for segmentation.

xanespy.xanes_math.register_correlations(frames, reference, upsample_factor=10, desc='Registering', median_filter_size=None)

Calculate the relative translation between the reference image and a series of frames.

This uses phase correlation through scikit-image’s register_translation function.

Parameters:

• frames (np.ndarray) – Array where the last two dimensions are (column, row) of images to be registered.
• reference (np.ndarray) – Image frame against which to align the entries in frames.
• upsample_factor (int, optional) – Factor controls subpixel registration via scikit-image.
• desc (str, optional) – Description for putting in the progress bar. None will suppress output.
• median_filter_size (int, optional) – If provided, a median filter will be applied to each frame. The value of this parameter determines how large the kernel is: 3 creates a (3, 3) kernel; (3, 5) creates a (3, 5) kernel; etc.

Returns:

translations – Array with same dimensions as 0-th axis of frames containing (x, y) translations for each frame.

Return type:

np.ndarray

xanespy.xanes_math.register_template(frames, reference, template, desc='Registering', median_filter_size=None)

Calculate the relative translation between the reference image and a series of frames.

This uses template cross correlation through scikit-image’s match_template function.

The register_correlations algorithm is simpler to use in most cases but sometimes results in unreasonable results; in those cases, this method can be more reliable to achieve a first approximation.

Parameters:

• frames (np.ndarray) – Array where the last two dimensions are (column, row) of images to be registered.
• reference (np.ndarray) – Image frame against which to align the entries in frames.
• template (np.ndarray) – A 2D array (smaller than frames and reference) that will be identified in each frame and used for alignment.
• desc (str, optional) – Description for putting in the progress bar. None will suppress output.
• median_filter_size (int, optional) – If provided, a median filter will be applied to each frame. The value of this parameter determines how large the kernel is: 3 creates a (3, 3) kernel; (3, 5) creates a (3, 5) kernel; etc.

Returns:

translations – Array with same dimensions as 0-th axis of frames containing (x, y) translations for each frame.

Return type:

np.ndarray

xanespy.xanes_math.transform_images(data, transformations, out=None, mode='median', quiet=False)

Takes image data and applies the given translation matrices.

It is assumed that the first dimension of data is the same as the length of transformations. The transformation matrices can be generated from translation, rotation and scale parameters via the xanespy.xanes_math.transformation_matrics() function. Data will be written to out if given, otherwise returned as a new array.

Parameters:

• data (np.ndarray) – Numeric array with frames to transform. Last two dimensions are assumed to be (row, columns).
• transformations (np.ndarray) – A numeric array shaped compatibally with data. The last two dimensions are assumed to be (3, 3) and each (3, 3) encodes a transformation matrix for the corresponding frame in data.
• out (np.ndarray, optional) – A numeric array with same shape as data that will hold the transformed data.
• mode (str, optional) – Describes how to deal with edges. See scikit-image documentation for options. Special value “median” (default), takes the median pixel intensity of that frame and uses it as the constant value.
• quiet (bool, optional) – Whether to suppress the progress bar, etc.

Returns:

out – A new array with similar dimensions to data but with transformations applied and converted to float datatype.

Return type:

np.ndarray

xanespy.xanes_math.transformation_matrices(translations=None, rotations=None, scales=None, center=(0, 0))

Takes array of operations and calculates (3, 3) transformation matrices.

This function operates by calculating an AffineTransform similar to that described in the scikit-image package.

All three arguments (translations, rotations, and scales, should have shapes that are compatible with the frame data, though this is not strictly enforced for now. Rotation will necessarily have one less degree of freedom than translation/scale values.

Example Shapes:

Frames	Translations	Rotations	Scales
(10, 48, 1024, 1024)	(10, 48, 2)	(10, 48, 1)	(10, 48, 2)
(10, 48, 1024, 1024, 1024)	(10, 48, 3)	(10, 48, 2)	(10, 48, 3)

Parameters:

• translations (np.ndarray, optional) – How much to move each axis (x, y[, z]).
• rotations (np.ndarray, optional) – How much to rotate around the origin (0, 0) pixel.
• center (np.ndarray, optional) – Where to set the origin of rotation. Default is the first pixel (0, 0).
• scales (np.ndarray, optional) – How much to scale the image by in each dimension (x, y[, z]).

Returns:

new_transforms – Resulting transformation matrices. Will have the same shape as the input arrays but with the last dimension replaced by (3, 3).

Return type:

np.ndarray

xanespy.xradia module

Tools for importing X-ray microscopy frames in formats produced by Xradia instruments.

class xanespy.xradia.TXRMFile(filename, flavor: str)

Bases: xanespy.xradia.XRMFile

Similar to XRMFile but contains multiple images in a data-set.

energies()

image_stack()

class xanespy.xradia.XRMFile(filename, flavor: str)

Bases: object

Single X-ray micrscopy frame created using XRadia XRM format.

Formats from different beamlines have subtly different storage patterns. The flavor argument controls this parameter. The following metadata are affected by this coice:

• Energy: SSRL 6-2c does not store the X-ray beam energy in the file so it must be extracted from the filename.
• starttime, endtime : The XRMFile does not store timezone info, so we have to guess based on beamline.
• pixel_size : The APS microscope automatically corrects magnification when changing energy, the SSRL microscope does not.

Parameters:

• filename (str) – The path to the .xrm file
• flavor (str) – The variety of data represented in the xrm file. Valid choices are [‘ssrl’, ‘aps’, ‘aps-old1’]. These choices should line up with whatever is generated using the scripts in beamlines moudles.

aps_old1_regex = re.compile('(\\d{8})_([a-zA-Z0-9_]+)_([a-zA-Z0-9]+)_(\\d{4}).xrm')

binning()

Binning mode of the image.

Binning reduces pixel density but improves signal/noise ratio by combining adjacent pixels. For example, a 2048 x 2048 CCD with binning 4 would produce a 512 x 512 image.

close()

Close original XRM (ole) file on disk.

endtime()

Retrieve a datetime object representing when this frame was finished collecting. Duration is decided by exposure time of the frame and the start time.

energy()

Beam energy in electronvoltes.

image_data(idx=0)

TXM Image frame.

image_dtype()

image_shape()

is_valid()

Check that the XRM file has valid data.

num_images()

ole_value(stream, fmt=None, as_array=False)

Get arbitrary data from the ole file and convert from bytes.

print_ole()

sample_position()

starttime()

Return the earliest timestamp for the collected frames.

starttimes()

Retrieve all datetime objects representing when these frames were collected. Timezone is inferred from flavor (eg. ssrl -> california time).

um_per_pixel()

Describe the size of a pixel in microns. If this is an SSRL frame, the pixel size is dependent on energy. For APS frames, the pixel size is uniform and assumes a 40µm field-of-view.

Module contents