TITLE: Basic Analysis Protocol
AUTHORS: Clark Fritsch

[DESCRIPTION]
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.

[STEPS]
1. 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.

   

2. 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.
3. 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:

  

4. 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/

5. 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.

6. 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:

  

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:
 


7. 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:

  

8. 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. 

  

9. 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.

  

10. 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:

  

11. 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. 

12. 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:

  
13. 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".

14. 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.

15. 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):

  
The second window is the intensity histogram for the right side of your movie (the red channel):

  
The third window is a log of the program's progress:

  
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.
16. 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.

17. 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.

18. 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.

  

        PltPPS4.py - Use this program if you have generated traces from a non-ALEX movie.

  

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.
19. 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.

20. 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.

  

21. 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: