This repository is a collection of image analysis tools for our 2019 PNAS paper on the dynamics of IRE1 clusters. Every plot in the paper can be reproduced with the included code, and this readme file contains step-by-step instructions for doing so. Generally, each analysis segment is split into two parts:

1. Primary image analysis in ImageJ or CellProfiler.
2. Secondary analysis of the processed data in Python (using Jupyter notebooks). This is the step that generates all the final plots.

The code has been explicitly tested with the software versions indicated below. Small code modifications may or may not be required to run it on your machine if your software versions differ from the ones listed here.

Operating systems: tested on macOS High Sierra and MS Windows 10.

• Python: Version 3.5.6 (Anaconda dist.). https://www.anaconda.com/distribution/
• Seaborn (for data visualization): Version 0.9.0. https://seaborn.pydata.org/
• CellProfiler: Version 3.1.8. https://cellprofiler.org/
• ImageJ: Version 1.52p (Fiji distribution). https://fiji.sc/
• TrackMate ImageJ plugin: Version 4.0.1. https://imagej.net/TrackMate/

The repository is organized into the following top-level folders:

1. cellprofiler_pipelines (containing all CellProfiler config files)
2. data (all source data, in 'raw' and 'processed' subfolders)
3. imagej_scripts (all ImageJ macros and scripts)
4. notebooks (all Jupyter [IPython] notebooks)
5. reports (all output figures generated by the Jupyter notebooks)
6. src (source Python files for frequently used analysis functions)

Fig. 2C (quantification of XBP1 mRNA splicing from gel images):

1. Open gel image in ImageJ and, using the rectangle selection tool, draw a rectangle around the unspliced XBP1 band in the first lane.
2. Check that 'Measurements' include the mean intensity, or 'mean'.
3. Measure band intensity, then drag the rectangular selection down without changing its area to the spliced band and measure again.
4. Finally, drag the selection down without changing its area down to an empty region immediately below the spliced band and measure one more time. This will be the local background region for background correction.
5. Repeat steps 3-4 for all lanes.
6. Save measurements as a .csv file.
7. Open the CSV file in an editor of your choosing (Excel works) and add three columns: "Band", "Sample", and "File_name". Populate them manually (or automate it as you prefer). The "Band" column should contain one of three words "bkgnd", "unspliced", or "spliced". The "Sample" is the ID of the sample corresponding to that particular lane on the gel. Once you're done, save the file.
8. Load the Jupyter notebook "01_Fig2C_Standard_Plots_from_csv".
9. Modify the "data_dir" and "xbp1_spliced_filename" to point to the file you just created.
10. If desired, modify exluded_samples and excluded_samples_2 to make custom subset plots that only show a few of the samples (useful for huge gels).
11. Run the notebook. You're done!

Fig. 3A, 3B, 3C, 3D (quantification of IRE1 clusters in fixed cells):

1. If your raw data are z-stacks, use ImageJ to collapse them into z-projections (you can use average or maximum intensity, depending on the experiment). Then, split the collapsed images into channels. At the very least, you need an IRE1 channel and a nuclear stain channel such as DAPI. To automate this process, as long as your images were acquired with uManager, you can use the included ImageJ macro called "uManager_split_stacks_by_channel_z_project_v1.1.ijm".
2. Load the CellProfiler pipeline "Fig3A-D_Fixed_cell_clusters.cppipe".
3. Point CellProfiler to the images prepared in step 1. Additionally, you must load a background correction image for each channel (Simplest way to do this is to take multiple images of different blank fields of view using EXACTLY THE SAME illumination settings as the actual experiment, then average them together and apply a smoothing filter).
4. Update the "Metadata" settings to pull out your experimental variables either from file names or from image headers. The current version of the pipeline looks for two variables, "hours_Tm" (duration of stress treatment) and "dox" (presence of doxycycline induction). Yours may look different.
5. Make sure the "NamesAndTypes" tab correctly sorts your images into DAPI, IRE1, and background categories. --- NOTE on steps 3 through 5: Ensuring that images get correctly loaded into CellProfiler and their metadata is properly parsed is probably the trickiest part of adapting this analysis to your individual dataset. Refer to CellProfiler tutorials if you are unfamiliar with this software and are having a hard time configuring it.
6. Run the pipeline. I recommend first running it in test mode and checking whether clusters, nuclei, and ER masks get identified reliably. Your imaging settings may require you to modify thresholding parameters in the "Identify[]" modules. Once you are satisfy your results and run the pipeline in normal mode, it will save several images of identified cluster, ER, and nuclear outlines for each individual image so that you can go back and check a random selection as a sanity/quality check.
7. Load the Jupyter notebook "02_Fig3A-D_FixedCell-cluster-analysis".
8. Modify the parameters in the first cell to fit your experiment (most important are the file/folder names and pixel size).
9. Go through the cells in the notebook. Each one generates a separate plot, and almost every box has a parameter called "excluded_conditions", which is a list of conditions that are not plotted in that particular plot to avoid clutter. If left empty, all conditions are plotted. Modify these as you see fit for your dataset.
10. Run the notebook with "save_figs" in the first cell set to "False" (this will generate inline plots under each cell and allow you to tweak plotting settings as desired).
11. When ready for export, change "save_figs" to "True" and run the notebook. You will now have .pdf exports of all the figures!

Fig. 3E (quantification of IRE1 clusters in tracked live cells):

1. If your raw data are z-stacks, use ImageJ to collapse them into z-projections (you can use average or maximum intensity, depending on the experiment). Then, split the collapsed images into channels. At the very least, you need an IRE1 channel and a nuclear stain channel such as DAPI. To automate this process, as long as your images were acquired with uManager, you can use the included ImageJ macro called "uManager_split_stacks_by_channel_z_project_v1.1.ijm".
2. Load the CellProfiler pipeline "Fig3E_Live_cell_clusters.cppipe".
3. In the "Images" tab, point CellProfiler to the images prepared in step 1.
4. Update the "Metadata" settings to pull out your experimental variables either from file names or from image headers. The current version of the pipeline looks for two variables, "position" (microscope stage position) and "file_base_name" (uManager filename with the stage position removed). Yours may look different.
5. Make sure the "NamesAndTypes" tab correctly sorts your images into DAPI and IRE1 categories.
6. Under the "Groups" tab, make sure the image sets get grouped properly into movies.
7. Run the pipeline. I recommend first running it in test mode and checking whether clusters, nuclei, and ER masks get identified reliably. Your imaging settings may require you to modify thresholding parameters in the "Identify[]" modules. Once you are satisfy your results and run the pipeline in normal mode, it will save several images of identified cluster, ER, and nuclear outlines for each individual image so that you can go back and check a random selection as a sanity/quality check.
8. Load the Jupyter notebook "03_Fig3E_Live-cell-tracking-analysis".
9. Modify the parameters in the first cell to fit your experiment (most important are the file/folder names, pixel size, and time step).
10. Run the notebook with "save_figs" in the first cell set to "False" (this will generate inline plots under each cell and allow you to tweak plotting settings as desired).
11. When ready for export, change "save_figs" to "True" and run the notebook. You will now have .pdf exports of all the figures!

Fig. 4C, 4D, 4E, 4F (FRAP of unclustered and clustered IRE1 with tracking):

1. In ImageJ, open a FRAP video in which one or more clusters (or unclustered ER regions) get bleached. If analyzing cluster FRAP data: 1.1a. Open the TrackMate plugin in manual mode. 1.1b. Starting at the first frame of the video, focus on the cluster that will be bleached and track it until the bleaching frame using TrackMate's semi-automatic tracking mode (Refer to TrackMate documentation for details, e.g. here: https://imagej.net/Manual_tracking_with_TrackMate). 1.1c. Keep "tracking" the bleached cluster manually, with a spot centered on the last detected pre-bleach position of the cluster, until fluorescence begins to recover (this only takes a few frames in our experiments). 1.1d. Once fluorescence of the cluster reappears, continue tracking it in semi-automatic mode as long as is feasible. Typically you'll want to have at least 50 recovery frames, ideally more. 1.1e. Repeat steps 2b through 2d for each bleached cluster in this movie. 1.1f. Save the TrackMate file for your records. Open TrackMate's Analysis Window while keeping the file open. This will transfer TrackMate's data to ImageJ tables. 1.1g. With the tables open, run the macro included with this project named "Extract_two_radii_TrackMate.ijm". This macro will use the centroids of the tracked spots and save inner and outer diameter intensities in a separate file. Note that if you are dealing with very large or very small clusters, you may want to change the "inner_radius" and "outer_radius" settings of the ImageJ macro. Alternatively, if analyzing unclustered protein FRAP data: 1.2a. Run the provided ImageJ macro, "Manual_FRAP_ROI.ijm". This macro allows the user to input the bleach radius and quickly identify bleached regions and corresponding local background regions by alternating mouse clicks. A left click draws a FRAP ROI, and a subsequent click draws a corresponding background ROI (this should be a region close to the one being bleached and with similar mean intensity). The macro terminates when the user presses the right mouse button and saves the data. Regardless of the choice above, continue with the following steps:
2. Load the Jupyter notebook "04_Fig4_FRAP-with-and-without-clustering".
3. Modify the parameters in the first cell to match your acquisition parameters and point the notebook to the location of your clustered and unclustered FRAP data. Set "excluded_trace_file" to "None" for the first pass or edit the file itself to be empty; this is a config file that you can use later to manually remove traces from analysis in which the FRAP fit failed.
4. Run the notebook and look at the generated fit traces in the output folder. If the fit obviously failed in any of them, change the fit parameters or add the traces to the excluded trace file. Repeat until the resulting fits look reasonable. The summary figure can be found in the "summary" subfolder of the output folder.

Fig. 5B, 5C, 5D, 5E, 5F (MSD plots, cluster diffusion constant estimate):

1. One by one, load your videos in ImageJ and track clusters using TrackMate's fully automated tracking mode. For consistency, make sure to use the same illumination conditions and TrackMate conditions across all files; otherwise, the results will not be directly comparable. Save all TrackMate results as .xml files in one folder.
2. Load the Jupyter notebook "05_Fig5B-F_Tracking_clusters".
3. Modify the file directories, imaging parameters, and fitting parameters in the first cell of the notebook.
4. Run the notebook. You're done!

Fig. 6C and 6D (photoconversion experiments):

1. Open your first video in ImageJ and manually draw the outline of the cell using the freehand selection tool. Measure ("Analyze" > "Measure") the ROI in the first post-photoconversion frame of the movie, making sure that the measured results include "Area", "Mean" (mean intensity), and "Slice". Also, make sure you are measuring in the photoconverted (red) channel!
2. Scroll forward until the last frame in the movie before the clusters begin to dissolve. Manually draw the cell outline and measure again.
3. Scroll forward until the first frame in the movie after the clusters finished dissolving. Manually draw the cell outline and measure again.
4. Choose a cell-free region of the movie and draw an ROI of comparable area to your cell in it. Measure it.
5. Save the measurement file as a .csv table. At this point, the file should have four rows in the order shown above (start of experiment, last frame before clusters begin to dissolve, first frame after dissolution is complete, and background region).
6. Repeat steps 1-5 for the remaining videos and save all files in the same folder.
7. Load the Jupyter notebook "06_Fig6_Photoconversion".
8. Change the parameters in the first cell of the notebook, making sure that frame_time and stress_start_min reflect the settings of your actual experiment.
9. Run the notebook. You're done!

• The script "plotting_settings.py" in the "src" folder is called at the beginning of each Jupyter notebook to set plot styles to be uniform across the notebooks. Feel free to make changes to this file to modify all your plots in a consistent manner.
• I have attempted to make the code reasonably well-documented and organized. It is my hope that a basic working knowledge of Python and Pandas (which is included in the Anaconda distribution) will allow you to quickly start making changes to make the analysis fit your specific needs.
• If you find errors in the code or write additional code that you think would be useful to contribute to this repository, either raise an issue on Github or contact me on the Image.sc forum (https://forum.image.sc/). I will do my best to respond as quickly as possible. My username on both resources is "TheTrappist".

Thank you, and hope this helps! Vladislav (Vlad) Belyy