Usage

Note

This project is under active development. Documentation is publicly available to demonstrate the working applications of this package. Version-controlled source code will be released as manuscripts are published.

There are five main modules:

  1. image with the Image class, which handles the construction and image post-processing of a single HRTEM micrograph

  2. crystal_peaks with the CrystalStack and CrystalStack3D classes, which handle the analysis of crystalline signal extracted by Fourier analysis of an Image.

  1. spatial which handles the spatial and statistical analysis, including domain clustering

  2. tomography which handles tilt series alignment and reconstruction

Quick-Start

Input Parameters

image_dir =  'path/to/images'
filename_list = glob.glob(os.path.join(image_dir,'*.tiff'))
ctffilename_list = [filename.removesuffix('.tiff') + 'ctffind_output.txt' for filename in filename_list]
savedir = '/path/to/results'

# Initialize parameters
q022_pars = Parameters()
q022_pars.update({
   'q':0.22,
   'q_low':0.18,
   'q_high':0.26,
   'processor':'cuda:1',
   'threads':8})
pixel_resolution = 0.944 # Angstrom/pixel

overwrite=True

Standard Image processing

from polyTEM import image as pyimg
from polyTEM.params import Parameters

img = pyimg.Image.load(
   filename,
   format=re.search('(\w+)$',filename).group()[0],
   res=pixel_resolution,
   processor=q022_pars['processor'],
   savedir=savedir
)
img.load_ctf(ctffilename)
ctf_corrected_img = img.correct_ctf(
   snr_array=np.full((np.min(img.dim),np.min(img.dim)),0.7))
ctf_corrected_img.saveas_mrc()

## Process Image using q022_pars
bp_img = ctf_corrected_img.bandpass_filter(
   q_low=q022_pars['q_low'],
   q_high=q022_pars['q_high'])
crystalstack = bp_img.featurize(
   pars=q022_pars,
   kind='lamellar',
   plot_freq=0)
crystalstack.outdir=savedir

from polyTEM.crystal_peaks import flow_fields
flow_maps = crystalstack.plot_flow_field(
   perpendicular=True,
   curve_resolution=3,
   line_spacing=1,
   spacing_resolution=1,
   bend_tolerance=15)

Domain Analysis

from polyTEM import spatial_analysis as spatial

crystalstack.conditional_prob()

crystalstack.get_clusters(plot=False)
crystalstack.save_stack()

cluster_df = spatial.create_polygons(crystalstack.peaks_df, alpha = 0.18)
spatial.plot_polygons_df(
   cluster_df,
   resolution=crystalstack.resolution,
   xlim=[0,crystalstack.sparse_peaks_mat.shape[1]],
   ylim=[0,crystalstack.sparse_peaks_mat.shape[0]])

image module

The Image class is useful for loading, viewing, and post-processing the HRTEM micrograph (note: does not contain analysis). The main methods include:

  • CTF correction

    • CTF correction is handled by the ctf submodule and CTF class, which takes the .txt output of the CTFFIND4 software

  • Frame alignment (for dose-fractionated images)

  • Applying masks and bandpass filters

  • Computing the FFT and power spectrum

    • Computing a sliding FFT scan will also output a CrystalStack object to enable further analysis.

crystal_peaks module

CrystalStack class handles the scanning fft peak results from a single projection image, while CrystalStack3D handles a list of CrystalStacks for 3D analysis to produce a networkx graph of connected backbone nematic directors.

CrystalStack

  • Finds peaks in scanning FFT windows, stored as one-hot sparse matrix

  • Distribution of overlap angles

  • Conditional probability of backbone misorientation given separation distance

  • (v0.1) Handles domain clustering

  • 2D backbone flowline visualization is handled by the flow_fields submodule.

CrystalStack3D

  • Creates 3D nematic director fields

  • Aligns director fields based on AlignmentResult

  • Constructs networkx graph representation of 3D connected backbone directors

    • Calculates adjacency probability matrix from bending probability

    • Constructs graph by sampling the adjacency probability matrix

  • For 3D graph visualization, see :doc:’3Dviz.rst’

spatial module (v0.2)

Crystalline domains are clustered using HDBSCAN which outputs a DomainCollection object, whose domains attribute is a list of Domain objects for each cluster. Domain geometries are represented using alphashape and shapely polygons. DomainCollections can then be analyzed for

  • Orientation correlation length

  • Size and Shape distribution

The stats module handles statistical methods including:

  • Extrapolations and Interpolations

  • Model fitting

    • 2nd Legendre Polynomial

    • exponential decay

    • Frank-Oseen’s bending probability

  • Hypothesis Testing

    • Z-test and Fisher’s Z-test

    • Kolmogorov-Smirnov test

  • Statistical analysis

    • Auto-correlation and cross-correlation

    • Spatial autocorrelation (Global and local Moran’s I)

Version Release Notes: In v0.1 these functions were contained in separate modules. In v0.2, they will all be handled by the main spatial module. Code is still being migrated and refactored.

tomography module (v0.2)

The AlignmentResult class handles alignment of tilt series image frames using fiduciary marker alignment based on Jing and Sachs, [JingSachs].

  • Marker locations can be manually inputted or found using unsupervised clustering

  • Calculates alignment error (rotation and displacement)

  • chain_affine_transformation_mats provides transformation between original image frame

    coordinates to aligned projection coordinates

  • aligned projection coordinates are mapped to sample coordinates using proj_tilt_mat inverse

[JingSachs]

Jing ZQ, Sachs F. Alignment of tomographic projections using an incomplete set of fiducial markers. Ultramicroscopy. 1991 Jan;35(1):37-43. doi: 10.1016/0304-3991(91)90042-5. PMID: 2063493.

Unit-cell reconstruction, adapted from single-particle electron tomography, using weighted back-projection and filtered back-projection are still in development.