Ardem Patapoutian - iPALM

These scripts were developed to create a particle-averaged PIEZO structure from iPALM localization data. The code is separated into modules which can be run separately as desired. The scripts save .mat files and image files of figures as output. The analysis workflow described below was used in Mulhall, et. al.:

Eric M. Mulhall, Anant Gharpure, Rachel M. Lee, Adrienne E. Dubin, Jesse S. Aaron, Kara L. Marshall, Kathryn R. Spencer, Michael A. Reiche, Scott C. Henderson, Teng-Leong Chew, and Ardem Patapoutian. Direct Observation of the Conformational States of PIEZO1. (2023).

Analysis Workflow

The current analysis tools are designed to work in tandem with the software PeakSelector, which allows for filtering of iPALM localizations and pixelated image rendering of the underlying data. The bead removal approach can be used separately from any downstream analysis to clean up localization data for better visualization in PeakSelector. The candidate PIEZO segmentation approach looks for three nearby peaks in a pixelated/rendered image of the data, and uses this information to segment the underlying localization data into candidate PIEZO 'particles.'

Acknowledgments: The subfunctions bpass, cntrd, and pkfnd were adapted for MATLAB by Daniel Blair and Eric Dufresne from the IDL Particle Tracking software developed by David Grier, John Crocker, and Eric Weeks.

Bead Removal

Bead removal takes as input an image and txt file generated by PeakSelector and outputs a new txt file with localizations corresponding to beads removed. This txt file can be reloaded into PeakSelector for further exploration and visualization of the data.

To use this approach:

1. Load the data of interest into PeakSelector and ensure it is properly filtered. For example, set quaulity control settings such as sigma rtNPh < 0.06 or set bounds on the unwrapped z value.
2. Export the PeakSelector data as an ASCII file with the option of xy values in pixels.
3. Open the 'Cust. Tiff' menu and export the Total Raw Data as a tiff file with 133.33 nm per pixel.
4. Fill in appropriate filenames for the ASCII and tiff files under the USER PARAMETERS section of beadRemoval_v0_anisotropic.m.
5. Optionally adjust the parameters for bead removal:
   • rRemoveX and rRemoveY indicate the size of the region in pixels (133.33 nm/pixel) removed around each bead, in the X & Y directions respectively.
   • rParticle indicates the approximate size of beads in the total raw data image, in pixels.
   • beadThresh is a threshold for distinguishing beads from the background.
6. Run beadRemoval_v0_anisotropic.m. Figures will provide a check on the regions of data that were removed, and a new txt file will be generated without localizations from beads.

The bead-removed txt file can be reloaded into PeakSelctor through the menu option Import User ASCII with xy coords in pixels, the box for headers checked, and the values 0 to 48 for columns (see the file peakSelector_columnIndices for an easy list of values to copy and paste).

Segmentation of Candidate PIEZOs

Segmentation of the candidate PIEZO 'particles' is based on the assumption the PIEZOs will appear in a rendered image as 3 neighboring peaks. Data is stored as a .mat file in a format that can be used for further processing a single particle averaging routine developed by Heydarian, et. al.. Data in the PeakSelector format is also included in the particle structure, and thus the data can also be pulled back into PeakSelector for further rendering.

To use this approach:

1. First run beadRemoval_v0_anisotropic.m (described in the Bead Removal section) or otherwise remove beads from the data.
2. Load the bead-removed localization data into PeakSelector.
3. Select the option: PeakSelector > SpecialFunctions > SwapZ with Unwrapped Z. (This makes sure any filtering on unwrapped Z is properly used in the rendering.)
4. Open the 'Cust. Tiff' window
   • Make sure "Filter" is set to "Frame Peaks"
   • Set "NM per Image Pixel" to 2
5. Click "Render." Note that this process could be slow due to the size of the image.
6. Click "Save TIFF float" and save the file to the appropriate directory.
7. Fill in the USER PARAMETERS for piezoSegment_beadsRemoved.m. The data directory and file basename are required. Other parameters should be held constant across images.
   • dataDir is the folder containing the txt data and rendered images.
   • saveTag is the basename for the files and will be used for saving figures and data.
   • xyScale is the scale of pixels in the txt file, which should be 133.33 nm for iPALM data.
   • nmPix is the scale of pixels in the rendered image, which should be 2 for clear visualization of peaks in the rendered image.
   • rBlade is the scale in pixels of a blade-blob in the rendered image.
   • peakThresh is a threshold on the bandpassed image used to find blade-blobs.
   • rThresh is used to exclude peaks that are too close together.
   • neighborNumber is the number of neighbors each candidate PIEZO blade should have (i.e., each particle in a group of 3 has 2 neighbors)
   • neighborDist is the maximum distance for two blobs to be considered neighbors.
   • minDist is the minimum distance for two blobs to be considered neighbors; this parameter gets rid of self comparisons and over-finding artifacts
   • bord is the size of the region around each candidate PIEZO to include in the localization segmentation.
8. Run piezoSegment_beadsRemoved.m. Outputs include sanity-check figures, a .mat file containing the entire workspace (for current troubleshooting purposes), and a particles.mat file containing the data for later averaging.

Particle Averaging

The particle averaging workflow relies on the *particles.mat file generated in the previous segmentation-of-candidate-PIEZOs step. The processing is completed by the function piezoAveraging, which is called by the script batch_piezoAveraging. To run the piezoAveraging function, you must have installed smlm_datafusion3d_iPALM (see Windows installation instructions here). Several PIEZO-specific parameters are hard-coded inside the piezoAveraging function; the batch script requires parameters related to the specific experiment.

For large files or hundreds of candidate particles, the processing will be slow. In this case, batch_piezoAveragingIntermediate is recommended as this script will save its progress as it goes, allowing for the processing to be interupted and restarted as necessary. Animated visualizations that rotate around the resulting superparticle can be created using animateParticle.

To use this approach:

1. First make sure you have installed smlm_datafusion3d_iPALM and have run the previous PIEZO candidate segmentation step on one or more experiments, resulting in one or more particle.mat files.
2. Set the parameters at the top of the script batch_piezoAveraging.m:
   • directories is a list of the folders to be analyzed. Each folder should contain one particles.mat file.
   • zThresh is a threshold, in nm, for removing localizations from the segmented particles. The previous segmentation step only considers 2D information; this parameter allows for the removal of particles far from the average z localization. The batch script will run the analysis function twice: once with this filter, and once without it.
   • spaPATH is the full path to the smlm_datafusion3d_iPALM repository.
   • spaBUILD is the full path to the build of the smlm_datafusion3d_iPALM repository. If you follow the Windows installation instructions, it will be located at [spaPATH 'build'].
   • overwrite is set to false (0) by default. This means the script will skip over any previously analyzed datasets. If you would prefer for it to replace exisiting .mat files, set overwrite to true/1.
3. Run batch_piezoAveraging.m. Outputs include figures describing the generated superparticles (one direct and one with 3-fold symmetry) and intermediate processing steps; a .mat file for the intermediate scale sweep step; a .mat file saving the processing workspace; and .txt files of the superparticles in PeakSelector format.
4. For structures that are not necessarily flat in the xy plane, symmetry enforcement will add artifacts (as it only rotates around the z-axis). To address this, the script batch_piezoSymFold can be used to fit a plane to the initially aligned particles, rotate that plane to the xy plane, and then run the symmetry enforcement bootstrapping.

Additional Tools

The scripts in the AdditionalTools subfolder were used in the development of the code to check features of the particle averaging scripts. They are not necessary to recreate the particle averaging results, but can be used for further exploration as useful.