2p analysis for dummies - analyzing responses of cells in time series raster images

Concepts and terminology

Here we discuss how to analyze a time series recording of raster-scanned images of cells that have been labeled with some sort of activity indicator.

Directory structure

This software assumes that the data from each experiment is stored in a directory, called the experiment directory , and that the recording epochs (sometimes called test directories) are stored in subdirectories of this experiment directory. Typically, these directories are numbered t00001, t00002, t00003, etc. Complete information on the types of data that is generated by our recording software can be found here. These subdirectories all contain a reference.txt file that indicates the type of data that was recorded for each epoch, and a reference number. An example directory structure and reference.txt file for a 2-photon experiment might be:




name ref type

tp 1 prairietp



name ref type

tp 1 prairietp

This directory includes 2 recording epochs (t00001 and t00002); the reference.txt files indicate that these 2 recording epochs have the same reference number, which indicates to the program that they were recorded at the same imaging location.

Organizing principles for analysis

We have several tasks for performing the analysis. We must

  1. Create some sort of structure that indicates the relative positions of images that were recorded at different depths

  2. Deal with the fact that the images can drift or shift positions during the recording, and align recordings that were made at the same locations so that we can identify the same cells in both recordings

  3. Identify regions of interest that correspond to individual cells within the recordings

  4. Correct any errors made in our automatic procedures that align recordings across imaging sessions

Step 1, the structure:


To do this, we have created a software framework that is built around the concept of an image stack. In our terminology, a stack is a collection of image series that were acquired at approximately the same location at the cortical surface (or at the same location within a brain slice). For example, imagine you recorded at 2 locations in opposite hemispheres of the brain, and you recorded at several depths at each location. Each depth at each location would have a unique reference number, and we would use our software (in the steps below "Performing the analysis") to identify the images that belong to the same stack.


Each stack is comprised of individual slices, which just means a time-series imaging epoch at a certain location.

An example of dividing data into Stacks and Slices

For example, one might have made the following recordings in the left hemisphere at position on the cortical surface: t00001, t00002, t00003. Further, one might have made the following recordings in the right hemisphere at some position: t00004, t00005, t00006, t000007. Suppose further that t00001 and t00002 were at the same depth (that is, they are 2 recordings of the same location), and t00005 and t00006 were made at the same depth as well. Then, logically, we can divide these into 2 stacks. We want to create a stack that we might call 'site 1' for the left hemisphere recordings, and another stack we might call 'site 2' for the right hemisphere records. Then, we would add slices t00001, t00002, and t00003 to the 'site 1' stack, and t00004, t00005, t00006, and t00007 to the 'site 2' stack. The reference numbers of t00001, t00002, t00003,t00004, t00005, t00006, and t00007 might be 1, 1, 2, 3, 4, 4, 5, respectively. Note that t00001 and t00002 have to share a reference number since they were made at the same location, and t00005 and t00006 have to do the same. Note there is no relationship between the name of a recording epoch and its reference number.

Steps 2-4: Drift correction, alignment, identifying ROIs, correcting ROI errors

We'll just look at them in the analysis

Performing the analysis

  1. Start the program

    1. Make sure your machine has Matlab, vhtools and Github installed. vhtools can be added via the ndi_install (ask Steve, Dan or Zoey if you need help with this). If you're accessing from a personal laptop, ensure that you can connect to the server via Pulse Secure (ask Steve, Dan or Zoey if you need help with this too).

    2. Run Matlab

    3. Type twophotonbulkload; a window should pop up (might look different as versions change)

  1. Open an experiment for analysis

    1. Click the "choose" button to choose a directory where your data of interest reside. Navigate to the experiment directory (e.g., e:\2photon\mydata\2031-05-21)

    2. Your experiment should show up in the right window

  2. Create a new STACK

    1. Pull down the New Stack menu and choose "New Blank Stack"

    2. Enter a name for your stack, such as Site 1

    3. Your stack name should show up in the left panel; click the "Edit" button. A new figure will pop up.

  1. Add SLICES to the STACK

    1. To add the slices, go to the "Slice command" and choose "Add new slice"; choose the directory number (like t00001) and click OK.

    2. Note: If multiple slices were recorded at the same location (that is, they have the same reference number in the reference.txt file), then those slices will be indented under the first recording at that location.

  2. Correcting the possible existence of any drift (Drift Correction)

    1. Select one slice in the slice list (t00001, t00002, etc.)

    2. Enter in the correct depth for the slice (189 microns, 200 microns, etc.)

    3. Under Drift Correction click Manual and MATLAB will generate a figure with a Reference image, Frame image and Frame Drift (in the past we used the Default option, but using Manual is best)

    4. Zoom into a few cells in the Reference image and add 3 marks to 3 cells of your choice

    5. Make sure you're at frame 1, and click > to the left of Drift control (it looks like << < > >>>). Now you will see a short movie of all the frames being played. Make sure that the Frame image does not move or stray from the marks.

    6. If you do see a shift, correct the displacement of the Frame image with Drift Control and click fill down. You will see the changes reflected in Frame drift.

    7. Continue playing through the frames and make necessary adjustments while clicking fill down every time you adjust via Drift Control.

    8. ****Now click Save**** or else any cells you draw will be unusable.

    9. Repeat steps 5.1 through 5.8 for all slices in the stack while remembering to update the Depth for each slice.

          1. A common error: extra triggers present in the recording

                1. If during acquisition you failed to stop the spike 2 program before using the 2p, you may have more recorded twophotontimes than corresponding stimulus information. As a result you will not be able to correct drift. You will need to open the twophotontimes.txt file in the folder for that slice and delete any extra times. To identify extra times look at the end of the list of numbers for large jumps in time

                2. 1165.32256 1167.05656 1168.79056 1170.52456 1172.25856 1173.99256 1175.72860 1177.46262 1179.19662 1180.93060 1182.66460 1184.39860 1186.13464 1187.86864 1189.60266 1191.30604 1414.05162

                3. Delete the numbers after the large leap

  1. Draw cells

    1. Type an appropriate diameter (ex ~12 for a 40x objective, ~8 for a 16) circle that will most closely match the size of cell bodies into the Dia box.

    2. Then, hit the Draw circles until button. This means that you will be able to draw cell centers until you hit the enter/return button on your keyboard. After hitting this button you must draw at least one circle before you are allowed to hit enter and use another tool.

    3. Center the cross hairs and click. To stop drawing at any time, click Enter/Return

    4. Adjust the lighting to better view cells by switching [2000 2000 2000 2000] to [4000 2000 2000 2000] or to [700 2000 2000 2000] and so forth.

    5. Helpful tip: Most, if not all of your drawings will be made in one slice (e.g. t00001) assuming that drift correction has been done correctly. You may find some cells that appear in other slices (e.g. t00002, t00003, etc.) and that is okay. But you may also not find any additional cells and that is also okay. When you move to the next depth however, you will have to draw new cells.

    6. To hide cells that you have drawn, simply check the box that says "draw cells" and it will hides the drawings. This will be helpful for when you move into a different depth

  1. Check the quality of drift correction

    1. Select a cell in the cell list. Choose a bright cell.

    2. Click Check drift

    3. Zoom in on some early images and late images to check if the bright spots stay inside the circle for the whole session. If the drift correct did a bad job you may want to adjust the way that the drift correct works by modifying the defaults in the window that pops up when you hit the drift correct button.

    4. If drift correct didn’t do a great job on a majority of the cells you can manually move all the cells in a slice (does not apply to subsequent slices) by typing shiftdriftcorrect('e:\folder name\folder name\experiment number', x movement, y movement) in the Matlab command window. For example shiftdriftcorrect('e:\rebekah\2010-02-23\t00010-001',-5,0 will move the cells to the right 5 pixles in the x direction and none in the y direction. After hitting return you need to open up another slice and go back to the file you are working on to see the change.

  2. It is a good idea to hit Save occasionally to save your work.

  1. Checking the alignment across image series recorded at the same location.

      1. Circles drawn in higher slices will appear in lower slices but not vice versa. To remove a circle from a lower slice, highlight the slice number in the slice window so that that slice is displayed and then highlight the circle number in the Cell id# window. The circle will turn from blue to yellow then press the ### cell button. The cell will be deleted from the displayed slice and all subsequent slices but not previous (higher) slices. To remove the cell completely hit the delete cell button. The cell will completely disappear.

      2. To move a circle follow these steps but press the move cell button. Move cross hairs to where you want the cell moved and click. Hierarchy rules are the same. You can also add cells to lower slices and have them not appear in higher slices by highlighting the desired slice in the slice window and drawing cells there.

      3. If you move a circle in a lower slice and then move it in a higher slice the circle will not move again in the lower slice it will stay where you originally put it.

  2. Analyze the responses

    1. If the data were collected using vhtools / Fitzpatrick lab stimulus programs, then you can click Analyze By Param (to analyze with the stated parameter on the X axis) orAnalyze by Number (to analyze with the stimulus number on the X axis). If not, click Analyze Raw. The computer should compute for a few minutes and pop up the tuning curves (in the case of Analyze By Param or Analyze By Number).

  1. Add the responses to the experiment database

    1. Add slices to the data base in order to run the fitting analysis. First finish all cell drawing and checking, hit “analyze parameter” button for each slice. Dir window determines which slice you are analyzing not which file name is highlighted in the list above. Hit the “add slice to DB” button. You will be asked to identify the stimulus condition for each recording.

  1. Perform any fitting

The following is old:

To analyze ocular transfer experiement type

tpf=’e:\file name\file name’


Do you want to analyze (y\n) y

This should take all night

Do you want to read cells to database (y\n) y

Do you want to plot all stacks?(y\n)

To analyze cells for direction index before and after the training and select for cells that fit the OD and DI criteria

Go to Editor


Vanhooser\Fitzlab tools\directionanalysis_ylsv\oculartransferDIanalysis3

Change experiment file name

Push run button

First window shows cumulative probability histogram of DI (for all the cells that fit the criteria) before and after training in each eye.

Last window shows direction tuning curves for each of these cells

Middle window shows B (before) or A (after) OD index, DIte (trained eye), Dine (non-trained eye)

Wish list for improvements:

Split screen so that you can see more than one slice at a time. This will help with matching up the AOI

A ctrl z function where you can undo the last thing that you did (ei move a cell, draw a cell, delete a cell etc)

And a way to stop what you are doing without having to make an action first. If you click ‘draw cell until” then you need to draw a cell in order to get out of that. If you click move cell you have to move a cell first. Maybe a clear function button?

A “reminder to save” pop up


The initial version of this tutorial was contributed by Rebekah Corlew.

Zoey Keeley and Daniel Shin have updated it since 5/15/2020

It's a living document, so users, please update it!