Jan 31, 2025
Synaptic analysis workflow using SEQUIN_v15
- Andrew D Sauerbeck1,
- Terrance T Kummer1
- 1Department of Neurology, Hope Center for Neurological Disorders, Knight Alzheimer's Disease Research Center, Washington University School of Medicine, St. Louis, MO 63110, USA.
Protocol Citation: Andrew D Sauerbeck, Terrance T Kummer 2025. Synaptic analysis workflow using SEQUIN_v15. protocols.io https://dx.doi.org/10.17504/protocols.io.q26g7mwx3gwz/v1
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: January 06, 2025
Last Modified: January 31, 2025
Protocol Integer ID: 118331
Keywords: Synaptic analysis, SEQUIN, Neuroscience experiment
Funders Acknowledgements:
Aligning Science Across Parkinson's
Grant ID: ASAP-020616
Abstract
Identification and quantification of synaptic loci is a critically important question for numerous neuroscience experiments. This protocol provides for the analysis of super-resolution images acquired on a Zeiss Airyscan microscope. Endpoints provided by this analysis workflow include identification of synaptic loci, quantification of a third label in the proximity of identified synaptic loci, and localization of identified synaptic loci to labeled neurites. The code described in this protocol can be obtained from https://github.com/KummerLab/SEQUIN .
Processing of raw imaging data using SEQUIN_V15_step1 python code
Processing of raw imaging data using SEQUIN_V15_step1 python code
In the steps outlined below, the section headings are shown for each step to help guide the reader through the code. For each user specified parameter required for processing, additional information pertaining to the settings are provide with the code itself.
- To process Airyscan images and identify synaptic loci, the user must first load all required python packages defined in the code.
After the required packages are loaded, the user must next define the input parameters for the given experiment. These parameters are specific to a given experiment, may require adjustment for experimental conditions, and must be confirmed appropriate by the experimenter.
The folder structure required for processing is a main 'Input Folder’ which contains three different subfolders: ‘Experimental image folder’, ‘Channel Alignment imagefolder’, and ‘Main output folder’. These names can be adjusted by the user in the parameters sections but must exactly match how the images are organized. If the user needs the rerun the analysis using different parameters, the user can define the 'out_name' variable to an appropriate name, this folder will be automatically created.
The SEQUIN_v15 code is compatible with two or three channel images. Since the acquired channel order may vary between imaging data by how the user configured the microscope at data acquisition, the user must define which channel, based on order in the image, to use as the ‘sequin_reference’, ‘sequin_partner’, or ‘third_channel’ in the analysis. This order in in standard Python indexing counting from zero. The ‘third_channel’ is the imaging data that will used when performing analysis of fields centered around synaptic loci and their constituent partner spots. Since 3D fluorescent analysis is sensitive to intensity variation as a function of depth within the tissue specimen and/or the image itself, the user must ensure signal intensity it stable throughout the image. This can be performed at the microscope using auto brightness adjustments or in the code using the ‘z_intensity_correction_on’ parameter. The user must select what percentage of spots based upon brightness to use during analysis. The variable 'percent_main' selects the percentage of spots for each channel to use during analysis based on the brightness of each spot.
All fluorescent labeling experiments are subject to non-specific background. If correction of this is required when analyzing the ‘third_channel’, the user may set a predetermined correction value.
SEQUIN_V15 was created with the functionality to labeled and mask neurites in the images and then localize identified synaptic loci to these neurite mask. Prior to implementing this analysis, the user must define intensity values and cutoffs to be applied to the images. To improve processing efficiency, the user must specify the maximum distance from a synaptic loci to look for a neurite.
SEQUIN_v15 was created with the functionality to parse user defined fields around identified synaptic loci in order to measure an additional fluorescent label included in the experiment. The channel parsed during this analysis is the previously defined ‘third_channel’ in Step [ go to step #4 ]. The user can set multiple radii to test and the code with automatically test each radius.
A critical step of SEQUIN analysis is careful measurement and correction for chromatic aberration. This is done through the staining, imaging, and analysis as Channel Alignment images. It is recommended to use a subset of the brightest puncta in the images for this measure, with the top 5% being a good reference point. The user must specify which channel in the original raw image to use as the reference and which channel(s) to align to this image. If doing three channel imaging, it is recommended to use the fluorophore with the most central wavelength to reduce the effect of image cropping that is applied after aligning the channels. XY chromatic aberration may be variable across the image field and of low magnitude, as such correction XY can be omitted if needed. If the user has a known set of chromatic aberration correction values, these can be directly applied and the measurement step overridden.
To save time, the user can specify a maximum separation distance for analysis of synaptic pairs to analyze.
Since experimental conditions and imaging requirements may vary, the user may specify background subtraction values to apply to the images prior to spots analysis. The IDs of these channels correspond to the image # IDs that were defined for the reference, partner, and third_channel channels for the analysis.
Once the user required parameters above are defined, the user must Run that block of code to store all the parameters.
The user must next Run the core code which load all the processing steps and perform measurement of the correction for chromatic aberration if specified to do so by the user.
SEQUIN_V15 has the functionality to process multiple images simultaneously. The number of simultaneous jobs is dependent on computer resources and must be carefully chosen by the user. Once this parameter is set, the user must Run the last block of code which will perform SEQUIN on the user defined imaging folders using the user defined parameters. The output for each image will be saved in the user defined output folders.
Apply pre-trained LightGBM model to output from SEQUIN_v15 using ‘SEQUIN_V15_step2_apply_pretrained_LightGBM_model.py’.
Apply pre-trained LightGBM model to output from SEQUIN_v15 using ‘SEQUIN_V15_step2_apply_pretrained_LightGBM_model.py’.
Identification of the trans-synaptic separation distance of pre- and post-synaptic proteins is the core feature of SEQUIN that allow for the identification of synaptic loci vs non-synaptic pairs. Though the identification of synaptic loci can be performed based on a user defined fixed nearest neighbor cutoff, this can result in the exclusion of actual synaptic loci and inclusion on non-synaptic loci based upon the noise level of the data. One method to address this is through the application of a LightGBM model that has been trained on data with a high signal to noise between synaptic and non-synaptic data.
- The user must first load all required python packages defined in the code.
The user must next define the input and output folders to uses. The input folder for this portion of the SEQUIN workflow must be the output of the SEQUIN_V15_step1 code.
The user must next define the output file name to use.
The user must define the location and filename of the pre-trained model.
Once the user required parameters above are defined, the user must Run that block of code to store all the parameters.
The user must next Run the main block of code. This will save the output file to the user defined folder.
Additional processing for large tilescan data using ‘SEQUIN_V15_step3_process_tilescan_data.py’
Additional processing for large tilescan data using ‘SEQUIN_V15_step3_process_tilescan_data.py’
If the output from [go to step #14 ] is from large tilescan imaging data, the output from Step [go to step #14 ] can be further processed to simplify the analysis of by tile imaging data using ‘SEQUIN_V15_step3_process_tilescan_data.py’. This piece of code can handle one or more tilescans at the same time through the use of a master ‘input_file_key’. This key file must match the example layout.
- The user must first load all required python packages defined in the code.
Define input parameters including the location of the key file and output folder location.
Because Airyscan processing of Tilescan results in empty voxels, the user must define the spacing of this. This is system dependent but a Zeiss 980 acquiring data in 8Y-SR-multiplex mode results in a spacing of 12.
If needed, the user can specify radial smoothing and tile subsamples. Leaving the radius set to zero and the scaling factor equal to the XY dimension of the image will result in processing data on a whole tile basis.
The final output data can be cropped down to user defined areas of the tile scan. This process will also save representative images of the tilescan with the sub-selection area for visual confirmation.
Once the user required parameters above are defined, the user must Run that block of code to store all the parameters.
The user must next Run the following block of code to perform the actual analysis.
The resulting data will be stored in Python and must be extracted manually by the user for analysis. The data for all this is stored in the variable named “density_psyn_correlation”. The indices for the data in this variable matches the row indices in the input_key_file.
The columns in this data contain the following variables.
a. Synaptic density
b. Average synaptic intensity of the third channel
c. Neurite counts
d. Average total intensity of the third channel
e. ROI ID
f. Tile ID
Each row in this data is a Tile from the tilescan.
Calculation of synaptic density in proximity to labeled neurites using output from Step 2 and ‘SEQUIN_V15_step4_calculate_synaptic_density_around_masked_neurites.py’ code.
Calculation of synaptic density in proximity to labeled neurites using output from Step 2 and ‘SEQUIN_V15_step4_calculate_synaptic_density_around_masked_neurites.py’ code.
The user must first load all required python packages defined in the code.
User must define the input and output folders for processing. The user must set neighbor cutoff to select synaptic loci for analysis. The user must define and create the output folder. The user must specify the location and filename for the image used for original analysis.
The user must specify the user defined intensity parameters for masking the neurites in the images.
The use must specify the channel alignment values for correcting the image. This must exactly match what was used during the initial SEQUIN_V15 step1.
The user must specify one or more radii to dilate the neurites by for synaptic density measurements.
Once all user parameters are set, the user must Run that block of code.
If needed, the user may Run the next core block of code. If this processing has already been completed once before, the user can skip to the next block of code and define the folder to read that output back into Python.
The expectation is that step [go to step #14 ] was just performed and analysis will continue from there. Optionally, if this workflow has been processed before, the user can manually define the location of the ‘input_folder’ and simply read that data back into Python. The user must Run this block of code to recompile the needed data.
In the last block of code, the user must define which column to process from the compiled data and what intensity interval to bin the neurites by. To determine what column to use, the user first needs to open the ‘compiled_data’ variable. Row 1 in this dataset indicates the radius the neurite was dilated by, Row 2 indicates whether synaptic loci detected inside the neurite mask should be included (‘raw’) or excluded (‘zeroed’). Once the appropriate of these two parameters have been chosen, the user then needs to choose the ‘counts’ column corresponding to user chosen Row 1 and Row 2 values. Next, the user must Run this block of code.
The results will be stored in the ‘all_data’ variable. The first column is the intensity bin start, the second is the intensity bin end, the third is the median neurite intensity for this bin, the last is the median synaptic density in this bin.
Recalculation of synaptic fields by distance from labeled neurites using ‘SEQUIN_V15_step5_synapse_associated_protein_levels_by_neurite_proximity’
Recalculation of synaptic fields by distance from labeled neurites using ‘SEQUIN_V15_step5_synapse_associated_protein_levels_by_neurite_proximity’
This code uses the output from the original SEQUIN_V15_step1 code as well as SEQUIN_V15_step4_calculate_synaptic_density_around_masked_neurites and allows the user to reprocess the fields around synaptic loci. The two common reason needing to do this reprocessing are the third channel background subtraction values needs to be altered/applied and/or the field radius needs to be changed.
- The user must first load all required python packages defined in the code.
The user must define the locations of both input folder requirements (Step 1 and Step 4 output folders) as well as the location of the originally processed image.
The user must define the amount of background subtraction to apply to the third_channel.
The user must define the radius to define around the identified synaptic loci for parsing the third_channel.
The user must define the channel alignment parameters exactly as used originally in the SEQUIN_V15_step1 code.
Once all parameters have been correctly set, the user must Run the first block of code.
The user must next Run the core block of code to perform the processing. When complete, a ‘compiled_neurite_data.csv’ file will be created in the input_folder. There are optional steps for binning the data after this step.
The user can optionally run the last block of code to bin the data by the distance a given synaptic loci is from a labeled neurite. This requires the user to choose the bin start, bin interval, and number of bins to be defined by the user.
Recalculation of Tile wise average synaptic fields with background subtraction using ‘SEQUIN_V15_step6_calculate_synaptic_subfields_with_background_subtraction.py’.
Recalculation of Tile wise average synaptic fields with background subtraction using ‘SEQUIN_V15_step6_calculate_synaptic_subfields_with_background_subtraction.py’.
This code use the output fromStep [go to step #14 ] to allow the user to apply or change to level of background subtraction applied to the third_channel when analyzing tilescan data. This performs faster than completely rerunning the original SEQUIN_V15_step1 code to make thes same parameter changes.
- The user must first load all required python packages defined in the code.
The user must define the input and output folders as well as the originally processed image. The user must also set the maximum nearest neighbor distance for identified synaptic loci.
The user must define which channel to use analyze within the synaptic fields and set the level of background subtraction to apply.
The user must set the radius to analyze around the synaptic centroids.
The user must set the required parameters for neurite masking to apply to the image.
The user must set the channel alignment parameters to apply to the image. This must be identical to what was used during the initial processing of SEQUIN_V15.
To align this analysis with the final by Tile analysis generated with ‘SEQUIN_V15_step3_process_tilescan_data.py’, the user must provide a file containing the Tile IDs needed to keep in the final output. These Tile IDs can be obtained in the final stage of Step[go to step #14 ] . As indicated above in Step [go to step #28 ], the last column for each image in ‘density_psyn_correlation’ contains the Tile IDs for that data. The user needs save these IDs in the file used to define ‘tile_id_key’. The first row in this file needs to be a tilescan identifier. Multiple tilescans can be saved in different columns within the same file and selected as needed in subsequent steps.
Once all user parameters are set, the user needs to Run this block of code.
The user then needs to Run the next block of code to process the data. This will save an output file into the user defined output folder. If this processing has already been performed. The user can skip this block and move to the next block.
The next block of code with compile the reprocessed output fields. If the user skipped the prior block and is picking up from a prior processing run, the 'output_folder' parameter must be defined appropriately. The user must define the column number corresponding the currently being processed tilescan in ‘tile_id_key’. This order in in standard Python indexing counting from zero.
Once all required parameters are set, the user must Run the last block of code to process that data.
Protocol references
Sauerbeck AD, Gangolli M, Reitz SJ, Salyards MH, Kim SH, Hemingway C, Gratuze M, Makkapati T, Kerschensteiner M, Holtzman DM, Brody DL, Kummer TT. SEQUIN Multiscale Imaging of Mammalian Central Synapses Reveals Loss of Synaptic Connectivity Resulting from Diffuse Traumatic Brain Injury. Neuron. 2020 Jul 22;107(2):257-273.e5. doi: 10.1016/j.neuron.2020.04.012. Epub 2020 May 8. PMID: 32392471; PMCID: PMC7381374.