General Information¶

The recommended way to use the ETSpy library is by importing the api module:

import etspy.api as etspy

Running this command is approximately equivalent to running:

from etspy import align, io, utils  # (1)!
from etspy.base import TomoStack
from etspy.io import load

Note

If you wish to import things directly from etspy, this approach is perfectly valid. The etspy.api is just a helper module to expose a more limited set of commonly used features.

The etspy.api module exposes the most commonly used features of ETSpy in a convenient interface. In particular, it provides access tothe align, io, and utils sub-modules. It also directly exposes the TomoStack constructor and the load method, which allow for creation of TomoStack objects either directly from NumPy arrays, or by loading data from .mrc, .dm3, or .dm4 files.

Tip

For more examples, please consult the example notebook on the Example Usage page.

Signals¶

ETSpy provides two dedicated signal types that are extensions of the regular HyperSpy Signal2D class. TomoStack objects provide the majority of the functionality of ETSpy, and represent a tomographic tilt series data set. RecStack objects provide a (currently limited) set of additional operations useful for visualizing and processing the results of a tomography reconstruction. For more details on these classes, please consult the following pages:

class etspy.base.TomoStack(CommonStack)[source]: Create a TomoStack instance, used to represent tomographic tilt series data.

class etspy.base.RecStack(CommonStack)[source]: Create a RecStack instance, used to hold the results of a reconstructed volume.

class etspy.base.CommonStack(Signal2D)[source]: An abstract base class for tomography data.

class etspy.base.TomoShifts(Signal1D)[source]: Create a TomoShifts instance to store image shift values of a tomography stack.

class etspy.base.TomoTilts(Signal1D)[source]: Create a TomoTilts instance, used to hold the tilt values of a tomography stack.

exception etspy.base.MismatchedTiltError(ValueError)[source]: Error for when number of tilts in signal does not match tilt dimension.

File I/O¶

Experimental data files can be easily loaded into ETSpy using the load function. If your data is already held in memory as a NumPy array, a TomoStack signal can also be created directly using TomoStack() constructor. Additionally, the io module provides a number of other helper functions:

etspy.io.load(filename, ...) → TomoStack[source]: Create a TomoStack object using data from a file.

etspy.io.get_mrc_tilts(stack, ...) → ndarray | None[source]: Extract tilts from an MRC file.

etspy.io.get_dm_tilts(s: Signal2D | TomoStack) → ndarray[source]: Extract tilts from DM tags.

etspy.io.parse_mdoc(mdoc_file, ...) → tuple[dict, ndarray | float][source]: Parse experimental parameters from a SerialEM MDOC file.

etspy.io.load_serialem(mrcfile: str | Path, mdocfile) → TomoStack[source]: Load a multi-frame series collected by SerialEM.

etspy.io.load_serialem_series(...) → tuple[Signal2D, ndarray][source]: Load a multi-frame series collected by SerialEM.

etspy.io.parse_mrc_header(filename: str | Path) → dict[str, Any][source]: Read the mrc header and return as dictionary.

Alignment Methods¶

The align module provides a range of tools to correct for misalignments of tilt image series that are common during an experimental data collection:

class etspy.AlignmentMethod(str, enum.Enum)[source]: Allowed values for the stack alignment method.

etspy.align.get_best_slices(stack: TomoStack, nslices) → ndarray[source]: Get best nslices for center of mass analysis.

etspy.align.get_coms(stack: TomoStack, slices: ndarray) → ndarray[source]: Calculate the center of mass for indicated slices.

etspy.align.apply_shifts(stack: TomoStack, shifts) → TomoStack[source]: Apply a series of shifts to a TomoStack.

etspy.align.pad_line(line: ndarray, paddedsize: int) → ndarray[source]: Pad a 1D array for FFT treatment without altering center location.

etspy.align.calc_shifts_cl(stack: TomoStack, ...) → ndarray[source]: Calculate shifts using the common line method.

etspy.align.calculate_shifts_conservation_of_mass(...) → ndarray[source]: Calculate shifts parallel to the tilt axis using conservation of mass.

etspy.align.calculate_shifts_com(stack: TomoStack, ...) → ndarray[source]: Align stack using a center of mass method.

etspy.align.calculate_shifts_pc(stack: TomoStack, ...) → ndarray[source]: Calculate shifts using the phase correlation algorithm.

etspy.align.calculate_shifts_stackreg(stack, ...) → ndarray[source]: Calculate shifts using PyStackReg.

etspy.align.calc_shifts_com_cl(stack: TomoStack, ...) → ndarray[source]: Calculate shifts using combined center of mass and common line methods.

etspy.align.align_stack(stack: TomoStack, method, ...) → TomoStack[source]: Compute the shifts for spatial registration.

etspy.align.tilt_com(stack: TomoStack, ...) → TomoStack[source]: Perform tilt axis alignment using center of mass (CoM) tracking.

etspy.align.tilt_maximage(stack: TomoStack, ...) → TomoStack[source]: Perform automated determination of the tilt axis of a TomoStack.

etspy.align.align_to_other(stack: TomoStack, other) → TomoStack[source]: Spatially register a TomoStack using previously calculated shifts.

etspy.align.shift_crop(stack: TomoStack) → TomoStack[source]: Crop shifted stack to common area.

Reconstruction¶

The recon module contains a number of lower-level helper methods that run directly on NumPy arrays. These functions make extensive use of the ASTRA Toolbox and are primarily designed to be used internally by other parts of the code, but can be used directly, if desired.

Tip

For an easier way to reconstruct a TomoStack signal, use the etspy.base.TomoStack.reconstruct() function instead.

etspy.recon.run_alg(sino: ndarray, iters: int, cfg, ...) → ndarray[source]: Run CPU-based FBP, SIRT, or SART reconstruction algorithm using dask.

etspy.recon.run_dart(sino: ndarray, iters: int, ...) → ndarray[source]: Run discrete algebraic reoncsturction technique (DART) algorithm.

etspy.recon.run(stack: ndarray, tilts: ndarray, ...) → ndarray[source]: Perform reconstruction of input tilt series.

etspy.recon.dart_segment(rec: ndarray, thresholds, ...) → ndarray[source]: Segmentation step for DART Reconstruction.

etspy.recon.get_dart_boundaries(segmented: ndarray) → ndarray[source]: Boundary step for DART Reconstruction.

etspy.recon.astra_error(sinogram, ...) → tuple[ndarray, ndarray][source]: Perform SIRT reconstruction using the Astra toolbox algorithms.

Data Simulation¶

The simulation module provides tools to create model data, which can be used to test various reconstruction routines:

etspy.simulation.create_catalyst_model(...) → Signal2D[source]: Create a model data array that mimics a hetergeneous catalyst.

etspy.simulation.create_cylinder_model(...) → Signal2D[source]: Create a model data array that mimics a needle shaped sample.

etspy.simulation.create_model_tilt_series(model, ...) → TomoStack[source]: Create a tilt series from a 3D volume.

etspy.simulation.add_noise(stack: TomoStack, ...)[source]: Apply noise to a model tilt series and return as a copy.

etspy.simulation.misalign_stack(stack: TomoStack, ...) → TomoStack[source]: Apply misalignment to a model tilt series.

Example Datasets¶

The datasets module provides two experimental datasets distributed along with the ETSpy code that can be used in examples or for testing reconstruction and alignment routines:

etspy.datasets.get_needle_data(aligned: bool = False)[source]: Load an experimental tilt series of needle-shaped specimen.

etspy.datasets.get_catalyst_data(...) → TomoStack[source]: Load a model-simulated catalyst tilt series.

Utilities¶

The utils module provides a few miscellaneous functions that perform assorted tasks related to tomographic reconstruction:

etspy.utils.multiaverage(stack: ndarray, nframes, ...) → ndarray[source]: Register a multi-frame series collected by SerialEM.

etspy.utils.register_serialem_stack(stack, ...) → TomoStack[source]: Register a multi-frame series collected by SerialEM.

etspy.utils.weight_stack(stack: TomoStack, ...) → TomoStack[source]: Apply a weighting window to a stack perpendicular to the tilt axis.

etspy.utils.calc_est_angles(num_points: int) → ndarray[source]: Caculate angles used for equally sloped tomography (EST).

etspy.utils.calc_golden_ratio_angles(tilt_range, ...) → ndarray[source]: Calculate golden ratio angles for a given tilt range.

etspy.utils.get_radial_mask(mask_shape, ...) → ndarray[source]: Calculate a radial mask given a shape and center position.

etspy.utils.filter_stack(stack: TomoStack, ...) → TomoStack[source]: Apply a Fourier filter to a sinogram or series of sinograms.