Feb 17, 2023
Version 2
Basic Analysis Protocol V.2
- 1University of Pennsylvania
Protocol Citation: Clark Fritsch 2023. Basic Analysis Protocol. protocols.io https://dx.doi.org/10.17504/protocols.io.n2bvjx24xlk5/v2Version created by Clark Fritsch
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: February 17, 2023
Last Modified: February 17, 2023
Protocol Integer ID: 77153
Abstract
This protocol is meant to describe the basic procedure needed to go from .nd2 files that are recorded using NIS-ELEMENTS during a standard single-molecule FRET experiment to usable FRET time traces that can be used for further downstream analysis.
In NIS-Elements, we record our single-molecule FRET movies with a .nd2 file format. However, to analyze our data we must first convert our movies from .nd2 files to .tiff files.
We can convert .nd2 files to .tiff files in several ways, depending on whether you used alternating laser excitation (ALEX) during your movies or not. For Steps 3 - 5 we will assume that you did not use ALEX for your experiments and instead just excited your donor fluorophore with the green 532 nm laser. If you used ALEX for your experiments, skip to Steps 6 - 8.
To convert your non-ALEX .nd2 files to .tiff files, first open Fiji / ImageJ. Then go to File and open the ND2_tiff1.ijm program that is provided below:
ND2_tiff1.ijm Once you open the ND2_tiff1.ijm program, you should see the following screen:
Once the program is open, you will need to paste in the path to your .nd2 files between the " " for the path variable (highlighted in yellow in the above image).
- Note that when you paste your path into the program, you may have the different directories in the path separated by backward slashes (\). You will need to replace these back slashes with forward slashes (/) for imagej to recognize the path.
- Additionally, you will have to make sure that your path ends with a /. Otherwise the program will not process all of the files in the directory that you are interested in.
- Example:
Change: D:\Basic_Analysis_Guide to D:/Basic_Analysis_Guide/
Once the correct path has been entered into the path variable, click the "Run" button at the bottom of the ND2_tiff1.ijm program window. The program will then begin processing your files and will open two additional windows. The first window is the Log window, which simply gives a progress report for which files in your directory of interest have been processed. The other window is an ImageJ Bio-Formats Import Options window that allows you to change the settings of your movies. For our case, however, you simply want to click "Okay" in the ImageJ Bio-Formats Import Options window. None of the settings needs to be changed.
The program may take a minute or two to process each movie, depending on how large each movie is. Once the program has finished converting one .nd2 file to a .tiff file, it will move on to the next movie in the directory and you will once again have to click "Okay" when the Bio-Formats Imports Options window opens up.
To convert your ALEX .nd2 files to .tiff files, first open Spyder (or whatever Python IDE that you prefer). Then go to File and open the ND2_to_Split4b32.py program that is provided below:
ND2_to_Split4b32.py When recording movies using ALEX, your movies will alternate between frames recorded in the green channel (when you are directly exciting your donor fluorophore with the 532 nm laser) and frames recorded in the red channel (when you are directly exciting your acceptor fluorophore with the 648 nm laser). This can be seen in the movie below:
However, this alternation of frames makes it difficult to perform additional analysis on the movies later on, so the ND2_to_Split4b32.py program not only converts the .nd2 files to .tiff files, but also formats the movies so that the first half of the movie will contain all of the green channel frames in a row, while the second half of the movie will contain all of the red channel frames in a row, as seen in the following movie:
Once you have opened ND2_to_Split4b32.py, you can process your files by copying the path to the directory that contains your movies and pasting it between the " " in the path variable at the top of the program, as highlighted in blue in the image below:
Then you simply run the program by clicking the green triangle button on the top bar of the Spyder tool bar and the program will begin processing your files. You can see the program's progress in the IPython Console in the lower right corner of the Spyder IDE, as shown below:
The ND2_to_Split4b32.py will output your formatted .tiff movie into your path directory with the file name changed to show that the movie has been rearranged. An ND2 file named "s0101.nd2" before processing will be named "s0101-rw.tiff" after being rearranged and converted to a .tiff file.
- Note that the ND2_to_Split4b32.py program can be fairly slow if you have a large number of movies to process.
Regardless of whether you started with non-ALEX or ALEX movies, you will then want to move each individual .tiff file to a separate directory for further processing. I like to name each directory according to the sample number for the movie. For example, a .tiff file named "s0101-rw.tiff" would go into a new directory called "s0101". You can probably automate this step, but I have never bothered to do so and just do it by hand.
Now that we have our .tiff files in separate directories, we want to go ahead and detect any fluorophore spots that overlap in the green channel (emission from donor fluorophores that have been directly excited by the 532 nm laser) and the red channel (sensitized emission from acceptor fluorophores that have been excited by emissions from the donor fluorophore). We do this by using an imagej program that we call "3 spots detector", which is included below:
3 spots detector.zip The directory for the spots detector program contains three sub-directories:
- ImageJ test Jan 11
The ImageJ test Jan 11 directory contains an old version of the spots detector program and is saved simply for having a backup just in case something goes wrong with the most current version.
- ImageJ1.8
The ImageJ1.8 directory contains the most recent version of the program and all of the required plugins that are needed to run the program.
- NewDualview
The NewDualview directory contains the PSM files that contain information that the program needs to run properly. There are many different PSM files in this directory for a variety of different types of analyses, most of which you don't really need to worry about.
The PSM files contained in the NewDualview directory need to be modified depending on the experimental conditions:
For the time being, the main settings that should be modified for each experiment are the minimum intensity thresholds for the donor (left) and acceptor (right) panels of each movie (highlighted in the above image). This point is discussed in further detail later on in the protocol. In addition to the minimum intensity thresholds, another setting that you may want to change is the number of initial frames that the Spot Detector program scans through to find overlap (and therefore FRET) between the spots in the left and right panels of each movie. Essentially, if you don't expect to see FRET in your movie until 300 frames into the movie, then you need to set the initial frames for the left and right panel to 300. If you expect to see FRET immediately upon starting the movie (which is the most common scenario), then you can set the initial frames to 100 or another similarly low number. Just note that the more frames that you make the program scan through to find overlap between spots in the different channels, the slower the program is going to run. If the program scans through the first 100 frames of a movie to find overlapping spots, the analysis might only take 5 minutes. If you make the program scan through all of the frames in a movie to find overlapping spots, then it might take an hour just to analyze one movie.
Begin the analysis by opening the ImageJ1.8 directory and double clicking on the ImageJ.exe program that is highlighted below:
Once imageJ is open you want to go to Plugins > ZD8 > PSM Analyze, as shown below:
You then want to navigate to the NewDualview directory in the original 3 spots detector directory and select a PSM file that contains settings appropriate to your movie:
After you select your PSM file and click "open" a program control window will open:
If you are analyzing ALEX movies, you want to make sure to check the "ALEX Style" box. If are analyzing non-ALEX movies, make sure to uncheck the "ALEX Style" box. Also check the "Show histograms" box to see the intensity distribution of the movie that you are analyzing. Additionally, you can check the "Show pairboxes" box if you want to see the pairs that the program selects for your movie. Note, however, that for the average movie, the boxes that the program displays are too dense to make any sense of. It is mainly good for troubleshooting and verifying that the program is analyzing the movie correctly. It also makes the program run very slowly, so I would avoid checking the "Show pairboxes" box unless absolutely necessary. The rest of the settings in the program control window can remain unchanged. Then click "OK".
Another window will then open and you will want to navigate to the directory that contains the .tiff file that you want to analyze. In this case, I want to analyze the "s0101-rw.tiff" movie, so I will navigate to the s0101 directory:
Note that your movie won't show up in the directory. That is fine. After navigating to your directory, just click "Open" and the program will begin running.
After the program begins running, three different windows will open (only one window if you didn't check the "Show histograms" box initially). The first window is the intensity histogram for the left side of your movie (the green channel):
For the above histogram, what you are seeing are the pixel intensities for every pixel on the left panel of the movie. This means that you are measuring the intensity of not only the fluorophore spots that you are interested in, but also the background. Ideally, you will select a minimum intensity threshold in your PSM file that allows you to ignore the intensity from the background, although it is not always possible to do this cleanly. If you look at the above histogram, you can see that there are three distinct peaks. I assume that the peak that is farthest to the left is from the background intensity, whereas I assume that the peak that is farthest to the left is from the fluorophore spot intensity. I am not sure what the middle peak is from, so I set the minimum intensity value in my PSM file to be roughly 1800. This is largely empirical, though. In general, I want to avoid setting the minimum intensity value too high. If I was to set the minimum intensity value to 4000, for example, I would be excluding most of my fluorophore spots from being analyzed any further. Because of this, I would likely get very few pairs between the red and green channels of the movie. If I set the minimum intensity value too low, however, the only downside is that I would likely get a lot of pairs between the red and the green channels that were complete junk / noise. Note that the part of the histogram that is in green is the part of the intensity spectrum that will be considered for pairing with the red channel.
The second window is the intensity histogram for the right side of your movie (the red channel):
For the above histogram, what you are seeing are the pixel intensities for every pixel of the right panel of the movie. Unlike the histogram that was generated for the green channel, there is one distinct peak for this histogram and one small shoulder coming off to the right of the main peak. In this case, the main peak is likely to be attributable to the background intensity of the movie and is therefore not useful to us. The shoulder, however, is likely to be made up of the intensity values from our sensitized emission spots. Because the sensitized emission spots are typically fairly dim, it is fairly common to simply get a small shoulder to the right of the main peak when analyzing the right panel of the movie. As you can see from the above histogram, I set the minimum intensity value in this case to be about 1300, so that I could exclude the background intensity values from the pairing procedure while keeping the intensity values from the sensitized emission spots. This, again, is determined empirically.
The third window is a log of the program's progress:
The log window contains a large amount of information regarding the number of spots that the program is trying to match between the two panels of you movie, the location of the spots in each panel of the movie, how many pairs the program finds between the two panels of the movie, etc. For the time being, the most relevant information that the program outputs can be found at the bottom of the window after the program has finished running. This information includes how many distinct spots the program found in the left panel of the movie (donor fluorophore / green channel) and the right panel of the movie (sensitized emission / red channel). Additionally, you can see how many overlapping spots the program found between the two panels of the movie (in this case the program found 71 spots that overlapped between the right and left panels). If you see, like in the above example, that you get many spots in the left panel (in this case 1383 spots) while you get relatively few spots in the right panel (in this case 121 spots), then you may consider lowering the minimum intensity threshold that you set in your PSM file. However, this is not guaranteed to result in more paired spots. Just because there are more spots does not mean that they overlap with spots in the opposite panel.
Note that the spot detector program can be quite slow. Sometimes taking upwards of 15 - 30 minutes to run per movie. However, the time that it takes to run the program can be minimized depending on the settings used in your PSM file (discussed above). Once you have finished running the spot detector program on one movie, you will want to repeat the analysis on each of your other movies, one at a time, by repeating Steps 12 - 14.
After running the Spot Detector program on all of your movies, navigate to the directory that contains your rearranged .tiff file. You will now see that the directory is filled with pairProfiles that contain the donor intensity and acceptor intensity as measured by the Spot Detector program:
You will also find the log file that was outputted from the Spot Detector program. While there are other files that the program outputs, we don't currently use them for any of our analyses and so I will not discuss them here.
While you do not really have to open the pairProfile.csv files for any reason most of the time, it is useful to know how they are formatted:
As you can see from the above excel file, each pair profile really only has two columns. The first column contains the intensity values over time of the donor fluorophore that the program found in the left panel / green channel of the movie. The second column contains the intensity values over time of the sensitized emission / acceptor fluorophore that the program found in the right panel / red channel of the movie. The first entry of each column is the coordinate location of the spot in either the left or right panel of the movie. The second entry of each column is the intensity value of either spot during the first frame of the movie, the third entry of each column is the intensity value of either spot during the second frame of the movie, so on and so forth.
As discussed previously, if you are analyzing ALEX movies and have rearranged them properly, then the intensity from the direct excitation of the acceptor fluorophore with the 648 nm laser will be located at the second half of the .csv file. For example, if your movie was 892 frames then the intensity values from frames 1 - 446 would be from direct excitation of the donor fluorophore with the 532 nm laser, whereas the intensity values from frames 447 - 892 would be from direct excitation of the acceptor fluorophore with the 648 nm laser.
Now that you have generated the pair profiles from each of your movies, you can now go through each of the pair profiles (FRET time traces, also simply called traces), and select which of the traces are good and which are just junk. You can do this using one of the following programs:
PltPPsALEX3.py - Use this program if you have generated traces from an ALEX movie.
PltPPsALEX3.py PltPPS4.py - Use this program if you have generated traces from a non-ALEX movie.
PltPPs4.py Functionally, these programs are exactly the same. They are both used to plot the traces that you have generated so that you can visually determine whether the trace you are looking at is good or not. The PltPPsALEX3.py program simply has an additional space for the intensity caused by direct excitation of the acceptor fluorophore.
To run these programs, simply open them in Spyder (or your preferred Python IDE) and enter the path to the pair profiles that you want to analyze between the " " for the path variable, as shown below:
Then run the program as described previously.
Once you run the program, you will see a window pop up that contains the plotted traces (shown individually) that are contained in your path directory. You will also see the controls for the program in the IPython Console in the lower right hand corner of the IDE:
I recommend dragging the IDE to the right hand of the screen and dragging the trace plot to the left hand of the screen. It will make it easier to cycle through the traces quickly.
As you can see at the bottom of the IPython console, the controls for the program are as follows:
- (S)ave - type s into the console where the cursor is to save a good trace in a file called "GoodOnes.txt".
- (B)ack - type b into the console where the cursor is to go back one trace in the directory.
- (Q)uit: type q into the console where the cursor is to quit the program after you are done.
This step of the analysis can be extremely time consuming, depending on how many traces you have per movie and how many movies you have to analyze. It can easily take a week or two to get through a couple of days worth of experiments.
While cycling through your traces, make sure to pay attention to what index your are on. The program will not warn you when you have finished cycling through all of the traces in a directory. It will reach the last trace in the directory and then simply start again from the first trace in the directory. If you are not careful, you might end up getting duplicates in your "GoodOnes.txt" file if you select the same traces multiple times.
As you can see from the above image, the directory that I am analyzing has 71 traces in it that need to be looked at. The first trace is at index = 0, whereas the last trace is at index = 70. Once you have gone through all of the traces in the directory, the program will simply display the first trace again (i = 0).
Ideally you will have generated a catalog of traces that you consider worthy of further analysis by saving the good traces to the "GoodOnes.txt" file for a given directory. These files are very simply contain the name of the traces that you have selected and the index of the trace within the path directory. These "GoodOnes.txt" files can then be fed into other programs for downstream analysis, depending on what exactly you want to do with them: