py4DSTEM

There are some shortcuts available for regularly used functions and utilities

IO

py4DSTEM.read(filepath: str | Path, datapath: str | None = None, tree: bool | str | None = True, verbose: bool | None = False, **kwargs)

A file reader for native py4DSTEM / EMD files. To read non-native formats, use py4DSTEM.import_file.

For files written by py4DSTEM version 0.14+, the function arguments are those listed here - filepath, datapath, and tree. See below for descriptions.

Files written by py4DSTEM v0.14+ are EMD 1.0 files, an HDF5 based format. For a description and complete file specification, see https://emdatasets.com/format/. For the Python implementation of EMD 1.0 read-write routines which py4DSTEM is build on top of, see https://github.com/py4dstem/emdfile.

To read file written by older verions of py4DSTEM, different keyword arguments should be passed. See the docstring for py4DSTEM.io.native.legacy.read_py4DSTEM_legacy for a complete list. For example, data_id may need to be specified to select dataset.

Parameters:

  • filepath (str or Path) – the file path

  • datapath (str or None) – the path within the H5 file to the data group to read from. If there is a single EMD data tree in the file, datapath may be left as None, and the path will be set to the root node of that tree. If datapath is None and there are multiple EMD trees, this function will issue a warning a return a list of paths to the root nodes of all EMD trees it finds. Otherwise, should be a ‘/’ delimited path to the data node of interest, for example passing ‘rootnode/somedata/someotherdata’ will set the node called ‘someotherdata’ as the point to read from. To print the tree of data nodes present in a file to the screen, use py4DSTEM.print_h5_tree(filepath).

  • tree (True or False or 'noroot') – indicates what data should be loaded, relative to the target data group specified with datapath. Enables reading the target data node only if tree is False, reading the target node as well as recursively reading the tree of data underneath it if tree is True, or recursively reading the tree of data underneath the target node but excluding the target node itself if tree is to ‘noroot’.

Returns:

(the data)

py4DSTEM.import_file(filepath: str | Path, mem: str | None = 'RAM', binfactor: int | None = 1, filetype: str | None = None, **kwargs)

Reader for non-native file formats. Parses the filetype, and calls the appropriate reader. Supports Gatan DM3/4, some EMPAD file versions, Gatan K2 bin/gtg, and mib formats.

Parameters:

  • filepath (str or Path) – Path to the file.

  • mem (str) – Must be “RAM” or “MEMMAP”. Specifies how the data is loaded; “RAM” transfer the data from storage to RAM, while “MEMMAP” leaves the data in storage and creates a memory map which points to the diffraction patterns, allowing them to be retrieved individually from storage.

  • binfactor (int) – Diffraction space binning factor for bin-on-load.

  • filetype (str) – Used to override automatic filetype detection. options include “dm”, “empad”, “gatan_K2_bin”, “mib”, “arina”, “abTEM”

  • **kwargs – any additional kwargs are passed to the downstream reader - refer to the individual filetype reader function call signatures and docstrings for more details.

Returns:

(DataCube or Array) returns a DataCube if 4D data is found, otherwise returns an Array

py4DSTEM.save(filepath, data, mode='w', emdpath=None, tree=True)

Saves data to an EMD 1.0 formatted HDF5 file at filepath.

For the full docstring, see py4DSTEM.emdfile.save.

py4DSTEM.print_h5_tree(filepath, show_metadata=False)

Prints the contents of an h5 file from a filepath.

Plotting

py4DSTEM.show(ar, figsize=(5, 5), cmap='gray', scaling='none', intensity_range='ordered', clipvals=None, vmin=None, vmax=None, min=None, max=None, power=None, power_offset=True, combine_images=False, ticks=True, bordercolor=None, borderwidth=5, show_image=True, return_ar_scaled=False, return_intensity_range=False, returncax=False, returnfig=False, figax=None, hist=False, n_bins=256, mask=None, mask_color='k', mask_alpha=0.0, masked_intensity_range=False, rectangle=None, circle=None, annulus=None, ellipse=None, points=None, grid_overlay=None, cartesian_grid=None, polarelliptical_grid=None, rtheta_grid=None, scalebar=None, calibration=None, rx=None, ry=None, space='Q', pixelsize=None, pixelunits=None, x0=None, y0=None, a=None, e=None, theta=None, title=None, show_fft=False, apply_hanning_window=True, show_cbar=False, **kwargs)

General visualization function for 2D arrays.

The simplest use of this function is:

>>> show(ar)

which will generate and display a matplotlib figure showing the 2D array ar. Additional functionality includes:

  • scaling the image (log scaling, power law scaling)

  • displaying the image histogram

  • altering the histogram clip values

  • masking some subset of the image

  • setting the colormap

  • adding geometric overlays (e.g. points, circles, rectangles, annuli)

  • adding informational overlays (scalebars, coordinate grids, oriented axes or vectors)

  • further customization tools

These are each discussed in turn below.

Scaling:

Setting the parameter scaling will scale the display image. Options are ‘none’, ‘auto’, ‘power’, or ‘log’. If ‘power’ is specified, the parameter power must also be passed. The underlying data is not altered. Values less than or equal to zero are set to zero. If the image histogram is displayed using hist=True, the scaled image histogram is shown.

Examples:

>>> show(ar,scaling='log')
>>> show(ar,power=0.5)
>>> show(ar,scaling='power',power=0.5,hist=True)
Histogram:

Setting the argument hist=True will display the image histogram, instead of the image. The displayed histogram will reflect any scaling requested. The number of bins can be set with n_bins. The upper and lower clip values, indicating where the image display will be saturated, are shown with dashed lines.

Intensity range:

Controlling the lower and upper values at which the display image will be saturated is accomplished with the intensity_range parameter, or its (soon deprecated) alias clipvals, in combination with vmin, and vmax. The method by which the upper and lower clip values are determined is controlled by intensity_range, and must be a string in (‘None’,’ordered’,’minmax’,’absolute’,’std’,’centered’). See the argument description for intensity_range for a description of the behavior for each. The clip values can be returned with the return_intensity_range parameter.

Masking:

If a numpy masked array is passed to show, the function will automatically mask the appropriate pixels. Alternatively, a boolean array of the same shape as the data array may be passed to the mask argument, and these pixels will be masked. Masked pixels are displayed as a single uniform color, black by default, and which can be specified with the mask_color argument. Masked pixels are excluded when displaying the histogram or computing clip values. The mask can also be blended with the hidden data by setting the mask_alpha argument.

Overlays (geometric):

The function natively supports overlaying points, circles, rectangles, annuli, and ellipses. Each is invoked by passing a dictionary to the appropriate input variable specifying the geometry and features of the requested overlay. For example:

>>> show(ar, rectangle={'lims':(10,20,10,20),'color':'r'})

will overlay a single red square, and

>>> show(ar, annulus={'center':[(28,68),(92,160)],
                      'radii':[(16,24),(12,36)],
                      'fill':True,
                      'alpha':[0.9,0.3],
                      'color':['r',(0,1,1,1)]})

will overlay two annuli with two different centers, radii, colors, and transparencies. For a description of the accepted dictionary parameters for each type of overlay, see the visualize functions add_*, where * = (‘rectangle’,’circle’,’annulus’,’ellipse’,’points’). (These docstrings are under construction!)

Overlays (informational):

Informational overlays supported by this function include coordinate axes (cartesian, polar-elliptical, or r-theta) and scalebars. These are added by passing the appropriate input argument a dictionary of the desired parameters, as with geometric overlays. However, there are two key differences between these overlays and the geometric overlays. First, informational overlays (coordinate systems and scalebars) require information about the plot - e.g. the position of the origin, the pixel sizes, the pixel units, any elliptical distortions, etc. The easiest way to pass this information is by pass a Calibration object containing this info to show as the keyword calibration. Second, once the coordinate information has been passed, informational overlays can autoselect their own parameters, thus simply passing an empty dict to one of these parameters will add that overlay.

For example:

>>> show(dp, scalebar={}, calibration=calibration)

will display the diffraction pattern dp with a scalebar overlaid in the bottom left corner given the pixel size and units described in calibration, and

>>> show(dp, calibration=calibration, scalebar={'length':0.5,'width':2,
                                           'position':'ul','label':True'})

will display a more customized scalebar.

When overlaying coordinate grids, it is important to note that some relevant parameters, e.g. the position of the origin, may change by scan position. In these cases, the parameters rx,``ry`` must also be passed to show, to tell the Calibration object where to look for the relevant parameters. For example:

>>> show(dp, cartesian_grid={}, calibration=calibration, rx=2,ry=5)

will overlay a cartesian coordinate grid on the diffraction pattern at scan position (2,5). Adding

>>> show(dp, calibration=calibration, rx=2, ry=5, cartesian_grid={'label':True,
            'alpha':0.7,'color':'r'})

will customize the appearance of the grid further. And

>>> show(im, calibration=calibration, cartesian_grid={}, space='R')

displays a cartesian grid over a real space image. For more details, see the documentation for the visualize functions add_*, where * = (‘scalebar’, ‘cartesian_grid’, ‘polarelliptical_grid’, ‘rtheta_grid’). (Under construction!)

Further customization:

Most parameters accepted by a matplotlib axis will be accepted by show. Pass a valid matplotlib colormap or a known string indicating a colormap as the argument cmap to specify the colormap. Pass figsize to specify the figure size. Etc.

Further customization can be accomplished by either (1) returning the figure generated by show and then manipulating it using the normal matplotlib functions, or (2) generating a matplotlib Figure with Axes any way you like (e.g. with plt.subplots) and then using this function to plot inside a single one of the Axes of your choice.

Option (1) is accomplished by simply passing this function returnfig=True. Thus:

>>> fig,ax = show(ar, returnfig=True)

will now give you direct access to the figure and axes to continue to alter. Option (2) is accomplished by passing an existing figure and axis to show as a 2-tuple to the figax argument. Thus:

>>> fig,(ax1,ax2) = plt.subplots(1,2)
>>> show(ar, figax=(fig,ax1))
>>> show(ar, figax=(fig,ax2), hist=True)

will generate a 2-axis figure, and then plot the array ar as an image on the left, while plotting its histogram on the right.

Parameters:

  • ar (2D array or a list of 2D arrays) – the data to plot. Normally this is a 2D array of the data. If a list of 2D arrays is passed, plots a corresponding grid of images.

  • figsize (2-tuple) – size of the plot

  • cmap (colormap) – any matplotlib cmap; default is gray

  • scaling (str) –

    selects a scaling scheme for the intensity values. Default is none. Accepted values:

    • ’none’: do not scale intensity values

    • ’full’: fill entire color range with sorted intensity values

    • ’power’: power law scaling

    • ’log’: values where ar<=0 are set to 0

  • intensity_range (str) –

    method for setting clipvalues (min and max intensities).

    The original name “clipvals” is now deprecated. Default is ‘ordered’. Accepted values:

    • ’ordered’: vmin/vmax are set to fractions of the distribution of pixel values in the array, e.g. vmin=0.02 will set the minumum display value to saturate the lower 2% of pixels

    • ’minmax’: The vmin/vmax values are np.min(ar)/np.max(r)

    • ’absolute’: The vmin/vmax values are set to the values of the vmin,vmax arguments received by this function

    • ’std’: The vmin/vmax values are np.median(ar) -/+ N*np.std(ar), and

      N is this functions min,max vals.

    • ’centered’: The vmin/vmax values are set to c -/+ m, where by default ‘c’ is zero and m is the max(abs(ar-c), or the two params can be user specified using the kwargs vmin/vmax -> c/m.

  • vmin (number) – min intensity, behavior depends on clipvals

  • vmax (number) – max intensity, behavior depends on clipvals

  • min – alias’ for vmin,vmax, throws deprecation warning

  • max – alias’ for vmin,vmax, throws deprecation warning

  • power (number) – specifies the scaling power

  • power_offset (bool) – If true, image has min value subtracted before power scaling

  • ticks (bool) – Turn outer tick marks on or off

  • bordercolor (color or None) – if not None, add a border of this color. The color can be anything matplotlib recognizes as a color.

  • borderwidth (number) –

  • returnfig (bool) – if True, the function returns the tuple (figure,axis)

  • figax (None or 2-tuple) – controls which matplotlib Axes object draws the image. If None, generates a new figure with a single Axes instance. Otherwise, ax must be a 2-tuple containing the matplotlib class instances (Figure,Axes), with ar then plotted in the specified Axes instance.

  • hist (bool) – if True, instead of plotting a 2D image in ax, plots a histogram of the intensity values of ar, after any scaling this function has performed. Plots the clipvals as dashed vertical lines

  • n_bins (int) – number of hist bins

  • mask (None or boolean array) – if not None, must have the same shape as ‘ar’. Wherever mask==True, plot the pixel normally, and where mask==False, pixel values are set to mask_color. If hist==True, ignore these values in the histogram. If mask_alpha is specified, the mask is blended with the array underneath, with 0 yielding an opaque mask and 1 yielding a fully transparent mask. If mask_color is set to 'empty' instead of a matplotlib.color, nothing is done to pixels where mask==False, allowing overlaying multiple arrays in different regions of an image by invoking the ``figax` kwarg over multiple calls to show

  • mask_color (color) – see ‘mask’

  • mask_alpha (float) – see ‘mask’

  • masked_intensity_range (bool) – controls if masked pixel values are included when determining the display value range; False indicates that all pixel values will be used to determine the intensity range, True indicates only unmasked pixels will be used

  • scalebar (None or dict or Bool) – if None, and a DiffractionSlice or RealSlice with calibrations is passed, adds a scalebar. If scalebar is not displaying the proper calibration, check .calibration pixel_size and pixel_units. If None and an array is passed, does not add a scalebar. If a dict is passed, it is propagated to the add_scalebar function which will attempt to use it to overlay a scalebar. If True, uses calibraiton or pixelsize/pixelunits for scalebar. If False, no scalebar is added.

  • show_fft (bool) – if True, plots 2D-fft of array

  • apply_hanning_window (bool) – If True, a 2D Hann window is applied to the array before applying the FFT

  • show_cbar (bool) – if True, adds cbar

  • **kwargs – any keywords accepted by matplotlib’s ax.matshow()

Returns:

if returnfig==False (default), the figure is plotted and nothing is returned. if returnfig==True, return the figure and the axis.

Utilities

py4DSTEM.check_config(verbose: bool = False, gratuitously_verbose: bool = False) → None

This function checks the state of required imports to run py4DSTEM.

Default behaviour will provide a summary of install dependencies for each module e.g. Base, ACOM etc.

Parameters:

  • verbose (bool, optional) – Will provide the status of all possible requriements for py4DSTEM, and perform any additonal checks. Defaults to False.

  • gratuitously_verbose (bool, optional) – Provides more indepth analysis. Defaults to False.

Returns:

None

py4DSTEM.join(a, *p)

Join two or more pathname components, inserting ‘/’ as needed. If any component is an absolute path, all previous path components will be discarded. An empty last part will result in a path that ends with a separator.

py4DSTEM.tqdmnd(*args, **kwargs)

An N-dimensional extension of tqdm providing an iterator and progress bar over the product of multiple iterators.

Example Usage:

>>> for x,y in tqdmnd(5,6):
>>>     <expression>

is equivalent to

>>> for x in range(5):
>>>     for y in range(6):
>>>         <expression>

with a tqdmnd-style progress bar printed to standard output.

Accepts:
*args: Any number of integers or iterators. Each integer N

is converted to a range(N) iterator. Then a loop is constructed from the Cartesian product of all iterables.

**kwargs: keyword arguments passed through directly to tqdm.

Full details are available at https://tqdm.github.io A few useful ones:

disable (bool): if True, hide the progress bar keep (bool): if True, delete the progress bar after completion unit (str): unit name for the display of iteration speed unit_scale (bool): whether to scale the displayed units and add

SI prefixes

desc (str): message displayed in front of the progress bar

Returns:

At each iteration, a tuple of indices is returned, corresponding to the values of each input iterator (in the same order as the inputs).