User's manual for optical_tools v.1.0
November 15, 1999
Naoum Issa
naoum@phy.ucsf.edu

To Full Manual

Optical Tools for Dummies:  Steps to follow for Ocular Dominance Analysis (by MPS)

    (Note: if program ever hangs, generally one can just recompile it with the compile button on the toolbar in order to recover from crash and restart):

Launch from Optical Tools icon on pc23.

Select Hemisphere Left Hemisphere or Right Hemisphere

Enter something appropriate in Provide Experiment Prefix (typically 4-character animal name, e.g., k214, followed by <return>).  This is only used for naming output files.

Enter something appropriate in Provide File Prefix (typically aob followed by <return>).  This is ued for finding input files, so it better be correct.

Click Get Filepath for Maps and find an analyze output file (suffix something like .1ac) in the appropriate directory.  The particular file does not matter, as the program records only the directory in which it resides.

Click Auto Select Images

Click Load Images and observe the sequence of image filenames as they are loaded.

Click Make ROI Template to bring up a new popup window called Masking….

From this popup window, you may choose Vascular Outline to use a blank image (the blurred image of the vasculature produced as the average response to the grey screen) for delineating the ROI by excluding high and low extremes of image intensity.  Usually this blank image is named in the analysis file as something like ablank.xrr where x is the experiment (1 digit) and rr are the run (two letters) numbers of the original data.
You can also or instead choose to Make a New Template by tracing the ROI counterclockwise onto a blank image that pops up.

The ROI that is used in future steps is taken as the logical AND of the vascular outline template and the one that you have traced (with the whole image taken as the ROI if you don’t do one or the other).  Click Save This Template if you want to save and reuse the same logically ANDed ROI.  Finally, click Quit in the ROI popup window to go on, and observe the sequence of templated images that are then displayed.


Click Calculate CBI to get a quick summary of the CBI for the templated region, or else you may bring up a more elaborate popup menu by clicking Ocular Dominance Columns.

From the Ocular Dominance Columns popup menu, you select the type of OD map you by choosing the appropriate radio button. To draw OD contour lines select the "OD contour line" button. To place OD contour lines on a vascular map select "OD contour on green". To save a tiff file of the most recent map, select "Make a figure"; a tiff file gets saved to 'c:/temp/figure.tiff' - rename it so you don't lose it later. CBI from this menu does the same thing as Calculate CBI did in the menu above.
 

General

Optical_tools is a set of programs written in the IDL5.2 environment for use in analyzing optically imaged intrinsic signals. It operates on normalized images (either blank-normalized or cocktail-blank normalized), not sum files. The current distribution set includes functions for analyzing ocular dominance columns (calculating the optical contralateral bias function and finding ocular dominance columns peaks) and animating data sets (allows you to see orientation domains rotating around pinwheel centers). Other functions are in the alpha-testing stage.

This code was written in the Stryker lab. Authors of various parts include M. Crair, J. Trachtenberg, N. Issa, M. Stryker.
 

System Settings

Please set your monitor to display in true color (24 bit color).
 

File Names

File names for images are assumed to have the following structure:

        aobr000_.0ac

where:
optional characters:
    a    => 'analyzed' file
    o    => orientation
    b    => blank normalized
required characters:
    r         => right eye (l =>left eye)
    000     => orientation, for 'Auto select' only 000,022,045,... are allowed
    _.0ac   => 5 character trailer
 

Main Menu

Here's where you load your images and choose what to do with them.

Column 1:

Number of angles: Select the number of orientations. Each orientation (for a given) corresponds to one file.

Eye selection:
    'Left eye first':

will load in images from both eyes, but will load the left eye first. The program keeps track of which is loaded first, so will calculate the CBI accordingly. This only makes a difference in the animation routines. Number of images to load = Number of angles * 2
    'Left eye only':
will load only images made using the left eye. Number of images to load = Number of angles
    'Right eye only':
will load only images made using the right eye. Number of images to load = Number of angles


Hemisphere selection:
    'Left hemisphere':

tells the program that the images are of the left hemisphere. Letting the program know the hemisphere is necessary for it to calculate the correct CBI. If the wrong hemisphere is selected, the actual CBI = 1 - the calculated CBI.
    'Right hemisphere':
tells the program that the images are of the right hemisphere. Letting the program know the hemisphere is necessary for it to calculate the correct CBI. If the wrong hemisphere is selected, the actual CBI = 1 - the calculated CBI.
    'Both hemispheres':
tells the program that both hemispheres were imaged simultaneously. A CBI calculated from both hemispheres is meaningless, and should be done for each hemisphere in the map independently. To do this, make a template including the hemisphere of interest, and select that hemisphere ('Right hemisphere' or 'Left hemisphere') in this menu. Repeat for the other side.


Column2: File selection

'Provide file prefix':

If you will be using the 'Auto Select Images' option, you will have to provide the file prefix. The file prefix includes all the optional characters listed above (can be anything).
'Get Filepath':
After getting the filepath, set the filter for the file in the editable window below the 'Get Filepath...' button; e.g.    c:\temp\aob*.*
'Clear List':
Clears the selected files from the display window imediately above the button.
'Auto Select Images':
You can select files individually by clicking on them (you must click as many files as needs to be loaded), or use this button. To select the images automatically, image files must conform to the convention listed above. The names of the selected images can be seen in the idl log window.
'Load Images':
Once the file names have been selected either manually or automatically, you must load the images into memory using this button. If you have not selected the correct number of images (as determined by the product of number of angles and number of eyes), no images will be selected. If the files selected do not exist, the program will crash. Simply recompile the the program, hit 'Clear List', and start over with the file selection process.


Column 3: Function selection

'Make ROI Template': Lets you construct a Region Of Interest template.

    'Open an Existing Template':

Loads in a previously saved template, overwriting any currently loaded template.
    'Whole Image is Template':
erases any template, putting the entire image in the region of interest.
    'Vascular Outline Template':
allows you to construct a template based on the vascular pattern. You will be asked to selected the image that has the vascular pattern (usually the average blank image). Using the slider bars at the bottom of the menu, set the template levels  such that only the vascular pattern is templated out. Because of smoothing and edge effects, the program will usually blank out all four sides of the image,even though much of the area is fine. Increasing the upper limit (templating out fewer of the pixels in the white range) often solves this problem. When you're satisfied with the vascular template, you can change your template using teh 'Make a New Template' option.
    'Make a New Template':
Allows you to make a freehand template. Select points on the map with the left mouse button, and complete your ROI by pressing the right mouse button. Each 'New Template' that you construct gets added to the template already there. Use the 'Whole Image is Template' button to start with a clean slate.
    'Save This Template':
Writes the template to a file name of your chosing.
    'Quit':
Returns to the main menu.


'Animate Images':

This will group images by eye and display orientations sequentially. This allows you to see orientation domains "rotate" about a pinwheel center. It also lets you eyeball the difference in oreintation selectivity and response strength between the two eyes.


'Calculate CBI':

This will calculate the optical CBI as described in Issa et al. (1999) J. Neurosci. in press. Blank-normalized images should be used. If you have selected the appropriate hemisphere, the CBI will be correct. If you have selected the opposite hemisphere, the actual CBI = 1- the calculated CBI. Optical CBI is linearly proportional to the CBI calculated by electrophysiology, in cats, the relationship has a slope of 0.61 and y-intercept of 0.19 (R2 = 0.94, measured in 14 hemispheres); in ferrets the relationship has a slope of 0.8 and y-intercept of 0.06 (R2 = 0.80, measured in 12 hemispheres). Optical_CBI = m*Electrophysiology_CBI + b.


'Ocular Dominance Columns': Helps analze ocular dominance images.

Making an OD map

1. Select which eye is deprived; the deprived eye will appear dark and the non-deprived eye will be bright in OD ratio maps. If 'NO deprived eye' is selected, the left eye dominance columns will appear dark.

2. Select the radio button of the type of OD map you want in column 2:

    'Load OD map'

lets you select a clipped ocular dominance map. The file selection dialog has a filter of 'aod*.*'
    'average resp OD map'
calculates a standard OD map after averaging responses over all orientations
    'max response OD'
calculates an OD map using the ratio of the responses at the preferred orientation (defined for the dominant eye)
    'max/ave OD map'
calculates the ratio of the max and average response maps; only useful for seeing the difference between the two types of OD maps
    'CBI OD map'
calculates the the OD map defined by the optical ocular dominance score that goes into making the optical CBI.


OD Contour function:    Draws contours of equal eye dominance on maps.

    'Contour OD map':

smooths the OD map, then draws a red contour line at the equal ocular dominance contour on the OD map that was most recently constructed.
    'OD contour on green':
asks you to select the appropriate green (vascular) image, then draws the equal ocular dominance contour line on the vascular pattern.


Contralateral Bias Index:    Calculates the optical contralateral bias index

    'CBI - traditional':

to have a correct CBI value, make sure you have selected the correct hemisphere on the front "optical tools" panel. This routine calculates the optical CBI, and displays a CBI map. It also displays a histogram of ocular dominance ranking; the peak on the left is the number of pixels preferring the left eye, and the peak on the right is the number of pixels preferring the right eye.
    'CBI in an ROI':
displays the orientation tuning curve, OD histogram, and CBI for an elliptical Region Of Interest (ROI). The ROI is defined by the 4 sliders above the button. 'x axis' sets the length of the horizontal elipsoid axis in micrometers,  'y axis' sets the length of the vertical elipsoid axis in micrometers,  'x position' sets the horizontal center of the elipsoid in micrometers, 'y position' sets the vertical center of the ellipsoid in micrometers. When you change one of the values of these sliders, it draws an ellipse to show you where the ROI is.
    'CBI arbitrary ROI':
calculates the CBI in an Region Of Interest (ROI) that you draw. Click the left button to set points on the ROI boundary, click the right button to close the ROI.


Choosing peaks of ocular dominance columns

    'Manually Select DE/ND ODC peaks':

You select peaks associated with the deprived (second-loaded) eye or the non-deprived (first-loaded) eye. Press the left mouse button when the arrow is positioned over the peak. When you have selected all the peaks for the eye, press the right mouse butoon.
    'Select Centroid of DE/ND peaks':
This lets you use an objective criterion to define an ocular dominance peak. On an ocular dominance map in which contour lines encircle ocular dominance peaks (see Lower Limit and Upper Limit sliders), use the mouse to circle an ocular dominance peak. The program finds the ocular dominance peak by calculating the centroid position of the area within both the contour line and your circle. The 'Select Centroid ...' button must be pushed for each peak you want to select.
    'Clear last ND/DE peaks':
Removes the last peak you selected from the list of ocular dominance peaks.
    'Upper Limit' and 'Lower Limit' sliders:
Sets the contour lines for the 'Select Centroid ...' functions. Adjust these values so that they surround your ocular dominance peaks.
    'Save ODC peaks':
Saves a text file containing the positions of ocular dominance peaks.
    'Load ODC peaks':
Load in positions of ocular dominance peaks from a text file.
    'Display ODC peaks':
Displays the position of the selected ocular dominance peaks using X and O on an ocular dominance map.


Miscellaneous functions

    'Write a figure':

writes a tiff file of the most recently manipulated image. Writes the tiff file to 'c:/temp/figure.tiff'
    'QUIT':
Returns to Main Menu.


'Single Image': Lets you measure absolute response intensities in a templated region of interest on a single image.

    'Filter image' radio button:

sets the program to analyzed a high-pass filtered version of the single image. Setting this button will display the filtered image.
    'DO NOT filter' radio button:
sets the program to analyzed an unfiltered version of the single image. Setting this button will display the unfiltered image.
    'Response intensity':
clicking this button will display a filtered version of the single image (even if you selected 'DO NOT filter'). Circle the region of interest with the mouse then right click. A distribution of response intensities will be displayed, and the mean response intensity will be printed.
    'QUIT':
Returns to Main Menu.


'QUIT': That's all folks!