TREE-TRACING MACROS: User's Manual
For: TreeTraceMacros version 01I 11/3/97(8/7/95 dkh+ G.O. mods)
Copyright (C) 1995 D.K. Hartline {for changes: see end of file}
These NIH Image macros were designed for tracing neuronal processes
through a stack of confocal microscope images (or the equivalent). The
processes are digitized as a tree of straight-line cylindrical "sections" [called
"segments" within the program] recording x,y,z coordinates of the beginning and
end of each "section", process diameters (using a "selection circle" adjusted to
just fill the process), connectivity data and mean grey scale values in the
selection circle.
INITIAL TRACING PROCEDURE (Starting a new neuron)
1. Prepare NIH Image if this is your first-time use, or if your default
settings have been changed in other uses of the program. Follow the steps
indicated in FIRST-TIME SET-UP below.
2. Prepare stack: Read in your image stack and the macro file
(TreeTraceMacros). Set the LUT to reserve 3 colors (Options Menu).
3. Prepare macros: Place cursor at the origin for the tree (normally the
center of the soma). Repeatedly key "+" to increase the diameter of a
"Selection Circle", which appears outlined in "crawling ants" (use "-" to
decrease it when you overshoot). Each touch of the + or - keys changes the
diameter by 1 pixel; use "*" and "=" keys to change by 10-pixel increments. Use
Space-bar to leave the diameter unchanged, but recentering the circle on the
cursor position. Adjust the selection circle to best fit the soma size and
center. When everything is set, key "F1" to initialize colors, counters, etc.
before commencing tracing. The reconstruction process is designed to start with
a single length of "neurite" that would normally represent a monopolar soma
leading to an initial process which later branches repeatedly. The anchor node
cannot be multiply branched. For a multipolar soma, you will want to create a
dummy initial process that is very short and fat, from the termination of which
the various multipolar processes can branch.
4. To trace a length of neural process: Adjust the stack position using the
"<" and ">" keys to obtain the best "focus" for the process at the point of
intended measurement. Place the cursor in the middle of the process and, using
the +,-,*,=, keys, adjust the diameter of the selection circle to just fit
within the process. The circle diameter being recorded includes the outermost
pixels in the crawling ant pattern, hence the need for a completely inscribed
circle. When all is set, key "L" to record the measurements.
5. Key "L" to produce subsequent Line sections after repositioning cursor
and adjusting the circle diameter and stack position as before. Line sections
will appear in red, with a green dot at the distal end. The selection circle
will not move to the new cursor position unless one of the circle-size keys is
depressed. If the first line originates in the upper-left corner instead for the
soma center, the F1 key was omitted. If the trace lines are white instead of
red, the LUT was not set properly (Step 2: setting it now will make the colors
appear).
6. Key "D" to Delete the last line section drawn if an error is made in
tracing a process. Repeated keying of "D" will delete successively earlier
sections (i.e. from the bottom of the list, regardless of location on tree).
7. Key "U" to Undelete a just-deleted line section (only 1 level of undelete
is available).
8. Key "B" to mark Branch points on a growing process. The branch will be
placed at the distal end of the active line section (= last defined unless
specifically changed). A newly-marked branch point will be coded by a green
square. When the second branch from a point has been digitized ("resolved"), the
color is changed to blue. To mark branch points AFTER process elongation has
gone beyond the branch point, first activate the "node" (section-end) nearest to
the desired branch point (using "F": see Other Tracing Operations) then key "B";
to then resume additions to the previous process, use "R" (see Other Tracing
Operations).
[Programming note: A list (Count value, or "line number") of unresolved
branch points is kept in the array "rAngle" (pointer = nUnresolved)].
9. Key "E" to Erase all marked branch points on the current active section.
10. When one branch of a tree is done, key "N" in order get back the Next
branch point to be resolved. Stack and circle will reposition ready to draw the
first line section of the next branch with "L". Unresolved branch points are
resolved in reverse order of their creation.
11. Saving results. When finished with a tree, or when digitization must be
suspended for a while, the current results ("measurements") may be saved for
later restoration. Keying "S" will Save the traced image stack in a file the
name of which will be requested in a standard Macintosh dialog box. Be sure
there is enough disk space before saving. The active (top-most) window must be
the image one (i.e. not the measurements or macro windows). The Results Table
will be saved in another file of the same name but given the extension ".svr".
This is a "pseudo-image" file storing measured parameters in 2-byte
integer-format. It also saves the unresolved branch list and other critical
variables. .svr files may be decoded in NIH Image using the Value displayed in
the Info window, pairs of columns corresponding to single columns in the Results
table. It is a good idea, as a precaution, to check the .svr image to be sure
that it has 27 columns of data (including column 0) and that the last row of
pixels (which corresponds to the last row in the Results table) has a y value
(displayed in the Info window) equal to the number of sections digitized (= the
number of entries in the Results table); This number should equal 256*Pixel(2,0)
+ Pixel(3,0) (where the pixel value is also displayed in the Info window when the
cursor is placed on it in the image ... the magnifier should be used to make the
pixels large enough to be individually distinguishable under the cursor). The
.svr table is left on the screen so that it may be checked as suggested [it is
advisable to close it before storing an updated image, as this "beta release" of
the macros has not been fully tested] .
12. Restoring the results table in order to resume digitizing a cell, etc.:
a. The image saved with "S" (see 11.) should be read in with the
"Open" command in the "Files" menu. The TreeTraceMacros should be activated, and
the LUT should be changed as in point 2 of Initial Tracing Procedure above.
b. Key "F12" to Restore the Results Table and other variables saved .
c. When the dialog box opens, click on the .svr file (not one of the
other files).
d. The last active section will be marked with an appropriate
selection circle. Tracing of tree may be resumed. The .svr window should have
closed automatically.
e. Results may still be restored if there is no stack present (e.g.
for purposes of generating a plan, or for exporting to a file). No
section-activation will occur (of course). {v01E mod 8/7/95}
13. Exporting results for use in other programs is done through the "Save
as" or "Export" facilities under the FIle menu (select Measurements button).
Even if the Results window do not show all of the measurements (>517 entries),
they should "Export" correctly. If these options are dimmed, it may mean that a
previous "Save" (e.g. of an image) has made the computer think there is nothing
new to save. Make a modification in a non-critical window and retry.
OTHER TRACING OPERATIONS
1. Changing the active section ["F" and "G"]: To alter the current active
section and node (the distal end of a section) in order to obtain information
about it, or in order to start digitizing one of its branches out of the marked
sequence, etc., two approaches may be used:
a. Move the cursor to within a few pixels of the desired node,
then key "F" ("FindNearestNode"). Use the "F" key to initiate adding a branch
in the middle of a tree (a branch point need not be defined to do this), or at an
inactive terminal section. Version 1.0D warning: "Nearest" is defined in x,y
plane only; if the cursor is placed too far from a desired node, other nodes in
other slices may end up being "nearer".
b. If the section number is known, key "G" and respond to
query with section number to Go to for that section.
2. Finding the current active section ["A"]: If the location of the active
section has been lost track of, keying "A" will retrieve it with slice and
correctly-sized selection circle set to x2,y2,z2 (the distal end coordinates).
This key also prints the section number, to aid identifying the section in the
Results Table.
3. To resume adding tree sections at the end of the section list
after having changed the active section to some other location, key "R" . Try
this if things get fouled up. Alternatively:
TRACED-TREE MANIPULATION MACROS and related procedures
1. To generate a projection of digitized processes ("plan"): First, create
a new window of appropriate dimensions (e.g. 768x512 for BioRad images) using the
File menu ("New"). Fill in the dimensions in the dialog box, and optionally give
the window a name. The "Create Plan" macro (no hot key) in the TreeTrace Macro
file will then generate a line drawing of a z-projection of the tree, using a
line thickness equal to the diameter of each section. Your will be asked for a
"Grey value" for the plan; the default is 255 (black). Answer "0" to make a
white plan. Alternatively, you can add a slice to your current stack, and the
plan will then be drawn on this slice. To check that a digitization is complete,
it may be helpful to create first a projection of the whole stack using the NIH Image
"Project..." utility in the Stacks menu (white on black background is usual), then
overlay a plan of the background color. Missed neurites will stand out clearly.
2. To print section numbers on the plan near the corresponding sections,
select the "Add Plan Numbers" macro (no hot key).
3. To generate color-coded plans in which the "descendants" of selected
branches are coded in one color, use the macro "Create Colored Plan". First, if
needed, set the LUT for up to 6 "colors" (grey-scale values 1-6; alternatively,
the various Color Tables schemes under the Options menu may be utilized). Next
inititate the macro, responding to the dialog with the number of the root (base)
branch. A black plan will be drawn first, then the color drawn over it.
Additional "colors" may be added by specifying non-zero roots. Specify "0" to
end the macro and return to NIH Image control. Grey scale codes for the "colors"
are incremented by 1 each time a non-0 number is entered.
4. To make a projection of the original cell:
a. If the contrast of the stack is reversed (negative: dark cell on
light background), reinvert the contrast for the stack (use "Invert Stack" macro
or individually invert each slice using "Invert" in the Edit menu). The reason
for this is that NIH Image makes appropriate projections based only on the
"brightest" (lowest density number) pixel value in a projection line through the
stack.
b. Select the "Project ..." option in Stacks menu. Settings in the
parameter boxes should be [abbr'd]: SS(P)=1, IA=0, TR=0, RAI=0, LTB=0, UTB=254,
SO=0, SDC=0, IDC=0. "Brightest point" should be selected as projection method,
then go.
c. The final projection should be reinverted (Edit menu) if it is to
be compared to the original stack.
5. To compare digitized to original cell to check completeness of
digitization, etc.:
a. Generate a regular plan of the digitized cell (1. above).
b. Execute the macro "Create Plan" specifying a grey-scale value of
0 to draw a white version of a plan superimposed on the projection.
Non-digitized portions of the cell will stand out in black (normally=255).
MISCELLANEOUS
1. Use "Rejuvenate Variables" macro (no hot key) to avoid reinitializing and
zeroing critical variables after an editing session on the macros (if you are
modifying them or adding new ones).
2. Use "Display Results" from the Analyze menu to view measured parameters of
sections of the growing tree. Columns as follows (NOTE: many NIH Image column
titles have beenrenamed & variables reassigned):
Names: Area Mean (StdDev) X Y Length Major Minor (Angle) Min Max User1 User2
Actual: diam -- -- x1 y1 length Parent nChild (unresBr) x2 y2 z1 z2
-->diam (Area): diameter of the circle at the distal end of the line seg.
-->Mean (&StdDev): NIH Image fcts; NOTE: affected by drawn lines/symbols!
-->x1 (X) & y1 (Y): coordinates in pixels of the PROXIMAL end of line section.
The value will be identical with the x2,y2 coordinates of parent section.
-->Length: 3D length of line sect., computed using the set stack-spacing value.
-->Parent (Major): section (line) number of the parent to a given section.
-->nChildren (Minor): nbr of branches from a given node (= 0 for a terminal sect.).
-->(unresBr [Angle] array: undisplayed list of unresolved branch points).
-->x2 (Min) & y2 (Max): coordinates of the DISTAL end of the line section.
-->z1 and z2 (User1; User2): slice #'s for the section's proximal and distal ends.
Note that there is a limit to the size of the Results table that will be displayed.
However, the full Results table will be saved (for later analysis) via the File/Save menu
Note that the calculated Length variable is inaccurate, being an integer. It is
advisable to recompute lengths using floating-point operations in processing applications.
FIRST-TIME SET-UP
The first time you use these macros, certain defaults in NIH Image must be
set. If you or other users reset these options for other purposes, they must be
reset before using the macros.
a. Before running, select the NIH Image icon in Finder, key
"Command-I" (or select Information from the Files menu) and set the Preferred
Size to a value large enough to accommodate your largest stack, plus your undo
and clipboard buffer, plus a few extra windows at least (if not an extra stack).
We use 50000 for stacks of ca 20MB size. Be sure to check your system for
appropriate memory and/or implementation of virtual memory.
b. Run NIH Image and open Options/Preferences menu. Set
Y-coordinates to NOT inverted. Also set Undo and Clipboard Buffer size large
enough to accommodate one stack slice (e.g. 3000). If changes had to be made in
any of these settings, you will need to do a Record Preferences operation (Files
menu), then restart NIH Image.
c. Open Analyze/Options menu and "X" all of the first column of
Measurement options except numbers 3,5,9, and 10.
d. Ample space for the results table must be allocated (Max
Measurements (1-8000)). We typically use 8000.
e. Set Field Width (1-18) to a small velue (preferebly 4). Owing to
storage space limitations in NIH Image, only 32K characters can be DISPLAYED in
the Results window, although up to 8K measurements can be stored and exported
---------------------------------------------------------------------------------------------------------
SAVE FILE FORMAT (.svr):
Row 0:
Byte 0: version number (vers) = 1 for late v01D and later
Bytes 1: width of .svr window (=27 for v01)
Bytes 2&3: length of file (=rCount)
Bytes 4: number of unresolved branch points (nUnresolved)
Bytes 6&7: slice spacing in pixels x100
Subsequent rows:
Byte 0: blank? (32?)
Bytes 1&2: diam (rArea)
Bytes 3&4: mean density (rMean)
Bytes 5&6: std dev (rStdDev)
Bytes 7&8: x1 (rX)
Bytes 9&10: y1 (rY)
Bytes 11&12: Length (rLength)
Bytes 13&14: Parent (rMajor)
Bytes 15&16: Child (rMinor)
Bytes 17&18: Unresolved branch points (rAngle)
Bytes 19&20: x2 (rMin)
Bytes 21&22: y2 (rMax)
Bytes 23&24: z1 (rUser1)
Bytes 25&26: z2 (rUser2)
------------------------------------------------------------------------------------
PROGRAM NOTES:
Diameter-area conversion for sel. circle: 1-1, 2-4, 3-9, 4-12, 5-21, 6-32, 7-37,
8-52, 9-69, 10-80, 11-97
------------------------------------------------------------------------------------
CHANGES IN TREE TRACE MACROS
VERSION 01I 11/3/97
1. "Change slice spacing" macro added.
VERSION 01H 10/24/95
1. "Create Plan" replaced by "Create Z Plan" to delimit slices projected.
VERSION 01G 8/31/95
1. Colored plan no longer generates just a black plan first. Must do manually, or omit.
VERSION 01F 8/30/95
1. Get Parent macro activates the parent of the current active segment
2. DisplayActive procedure displays the vital parameters of the active segment
VERSION 01E features added without changing number:
(none)
Version 01E FROM VERSION 01D
1. Create Plan asks for grey-scale value (replacing Create Plan [=255] and
Create White Plan [=0])
2. Restore Results [F12] no longer requires a stack
Version 01D features added without changing number
1. Version code "1" added to .svr (pixel [0,0])
2. Slice spacing query and storage added to .svr (Save Results) as 100-x
integer in pixels [6,0] and [7,0]
3. Create colored plan ... grey-codes branches beginning with number specified
in response to query.
Development of this software was made possible by a grant from the Human Frontier
Sciences Program via subcontract from Brandeis University.
Return to Hartline Home Page.
PBRC Anonymous FTP area
Return to PBRC Home Page.