Table of Contents

I) Introduction

II) Supported data types

III) Creating a working directory

IV) Volume vs slicewise data file storage

A) Creating an mtif file from tiff slices
B) Name convention for time series files
C) Analyzing multiple static images

V) GUI Execution

A) Dendritic Spine Analysis

1) Project Raw Image
2) Resize Raw Image
3) Enhance Image
4) Image Volume Histogram
5) Spine Detection Routines
6) Edit Detected Spines
7) Static Spine Analysis
8) Set and Run Timeseries

B) Neuron Tracing

1) Project Raw Image
2) Resize Raw Image
3) Enhance Image
4) Image Volume Histogram
5) Preprocessing Routines
6) Neuron Tracing

VI) References

I) Introduction      Back to Table of Contents

3DMA-Neuron (which, in this version, still retains remnants of its historical label "med_ax") was initially designed to execute under command line control. Full analysis of a data set requiried running a succession of command lines, each of the form

3dma[_OS_designator] [options] > [outfile] &

Much* of the command line control has now been upgraded to operate under GUI (graphical user interface) control

3dmaGUI[_OS_designator] &

This document describes how to run 3DMA-Neuron. Examples are provided. Those having the label "Test Example" use test data provided with the 3DMA-Neuron distribution, so that a user can simultaneously learn how to run the software and test the installation. For the Test Example cases, we assume that the 3DMA-Neuron distribution has been installed in a directory

/home/med_ax

---------------
*A minor amount of ancillary processing has not yet been upgraded.

**The full functionality of 3DMA-Neuron can still be accessed without the GUI by performing explicit successions of command line calls.

II) Supported data types:      Back to Table of Contents

For purposes of discussion, it is assumed that the data set(s) to be analyzed sits in a directory whose absolute path name is /home/data. There are four supported options for the format of a user's data set:

Single 3D volume stored in cfd format, e.g. /home/data/mydat.cfd

Single 3D volume stored in mtif format, e.g. /home/data/mydat.mtif

Single 3D volume stored slicewise in files of tiff format, e.g. /home/data/mydat.XXX.tif where XXX (e.g. 001, 002, 003, ...) denotes slice number

Multiple 3D volumes, all appearing in the /home/data directory, each 3D volume stored in ONE of the above formats:

mydat1.mtif, mydat14.mtif, mydat19.mtif, ....

or
mydat1.cfd, mydat14.cfd, mydat19.cfd, ....

or
mydat1.0001.tif, .... mydat1.0512.tif,
mydat14.0001.tif, .... mydat14.0512.tif,
mydat19.0001.tif, .... mydat19.0512.tif,

Note: the filename extensions above must be used on the appropriate data sets. There are two further filename extensions ".rsz" and ".deb" recognized by 3DMA-Neuron. These files are in fact mtif files; the two filename extensions are used as a mnemonic to indicate special pre-processing (See sections V.A.2 and V.A.3).

As imaged data sets are large, storing compressed files saves disk space. 3DMA-Neuron recognizes the compressed extension ".gz" or ".Z" on any user data file; compressed files will be automatically uncompressed when read in (using temporary storage in /tmp ). Such uncompression may place large temporary space demands on the /tmp directory. The user must therefore determine whether raw data should be stored compressed or not in the /home/data directory.

III) Creating a working directory      Back to Table of Contents

We assume that the data is to be analyzed in an (existing) directory "mywork". An organizational structure for this working directory is created using the utility "create_wdir".

% cd mywork
% create_wdir [datafiles***] &

Test Example: The directory med_ax/Test accompanies this 3DMA-Neuron
|	release. Thus the user can proceed to test newly installed
|	code by following this example.
|
|	% cd mywork
|_	% create_wdir /home/med_ax/Test/raw/ex_*.rsz.gz &

---------
**For the soft links to be created, absolute path names for the raw data must be used in the "create_wdir" command above.

***If no user filenames are listed, no links are created, and the user must manually move data into the "mywork/raw/" directory.

IV) Volume vs slicewise data file storage      Back to Table of Contents

As stated in II), 3DMA-Neuron handles a limited set of data types. Our preference is for file formats which store an entire 3D volume in a single file. This creates a problem for users whose microscope's produce tiff files, one file per slice. A command line facility is provided to convert tiff slice files into mtif files.

IV.A) Creating an mtif file from tiff slices

To create an mtif file from several tiff slices so that the raw data can be read by the GUI, 3DMA-Neuron must be run* in explicit command line mode. These instructions assume that "mywork/raw" contains (soft links to) slicewise stored files with the name convention mydat.XXX.tif, where XXX denotes slice number (e.g. 001, 002, ....)

% cd mywork/cases
% 3dma_lnx mydat > tif2mtif.out

The command line mode then prompts the user with a succession of scrolled menu options from which selections must be made.

From the "Input Data Options" menu select

(1) tomographic data;

(3) resize tomographic data,

From the "Data File Type" menu select "stif".

Further prompts allow the user to utilize the entire data volume, or to carve a sub-block of the data volume for analysis by specifying a subset of slices (z-direction), rows (y-direction) and columns (x-direction) to use.

The user should also ensure that voxel dimension is correctly entered at the appropriate prompt.

This commnd line will store an mtif file "mydat.rsz" in the "raw/" directory, which can be read by the GUI. A graphics file "mydat_rsz_proj.ras.gz" containing projection views of the data is also created in the "raw/draw/" subdirectory.

-------------
* The "3dma" command line must be run from the "cases/" subdirectory. It is critical that "." (i.e. current directory) be included in the environmental path variable if 3DMA-Neuron executables are to run correctly. (See Section D.1 in the installation instructions: http://www.ams.sunysb.edu/~lindquis/3dma/3dma_neuron/3dma_neuron_install.html.)

IV.B) Name convention for timeseries data

A single 3D volume, imaged repeatedly in time, is a timeseries. 3DMA-Neuron is capable of analyzing a timeseries, provided each separate 3D image is stored in a single file, and the files are sequentially labeled

mydat.TTT.mtif

IV.C) Analyzing multiple static images

In addition to analyzing multiple images forming a timeseries, 3DMA-Neuron can analyze multiple static images in one run. In such a case, statistics are accumulated for the entire set of images.

V) GUI Execution      Back to Table of Contents

The GUI, "3dmaGUI", must be run from the "cases/" subdirectory:

% cd mywork/cases
% 3dmaGUI_lnx & // Note the instruction "&" to run in background mode

When run in background mode, the historical 3DMA "splash screen" appears. Click on the splash screen to bring up the "3dma Output and Runtime Control" window. The "process status" section of this window will echo completion status lines each time a process is executed by the GUI. The "output menu" section will enable graphical/text access to output/data files produced by each processing step.

To begin,

select "New Run"

select A) "Dendritic Spine";

select B) "Neuron".

V.A) Dendritic Spine Analyses      Back to Table of Contents

click on "Dendritic Spine"

Project Raw Image
Resize Raw Image
Enhance Image
Image Volume Histogram
Spine Detection Routines
Edit Detected Spines
Static Spine Analysis
Set and Run Timeseries

This option produces a graphical (SUN Rasterfile format) file in "../raw/draw". The file contains a single image showing three views (XY, XZ, and YZ planes) of the user's image.

Test example: (data is  "mywork/raw/ex_*.rsz.gz").
|
|		click on Project Raw Image
|
|	This brings up the "Project Raw Image" input window.
|
|	In the "Specify raw data" area, from the pull down menu
|
|		click on "resized".
|		click on "Load Data"
|
|	Two files will appear in the right, datafile list area.
|	
|		Click on "../raw/ex_spine.rsz.gz"
|
|	to highlight it, and press the spacebar to delete all other
|	files from the list.
|
|	In the main "over-ride header option" area, do nothing.
|	Default values will come from the raw data file headers or
|	hard-coded defaults.
|
|		click on "Run"
|
|	A "View Output Data" window will pop up and the following
|	informational text will appear in the "Process Status" area
|	of the "3dma Output and Runtime Control Menu"
|
|	----------------------------------------------------------
|	Project image (../projraw.pm.8029):
|	started at Thu Oct  2 16:45:21 2003
|	runtime output will be written to "case1.12.*.out"
|	nohup: appending output to `nohup.out'
|	/home/med_ax/bin/run3dma:
|		line 23: test: =: unary operator expected
|	finished at Thu Oct  2 16:46:15 2003
|	See image file "../raw/draw/ex_spine_rsz_proj.ras.gz" under
|					output menu.
|	----------------------------------------------------------
|
|	In the "output menu" area of the "3dma output and runtime
|	control" window,
|
|		click on "image"
|
|	and then
|	
|		click on "../raw/draw/ex_spine_rsz_proj.ras.gz"
|
|	An  "xv" (XView)  picture of the three principle directional views
|
|		XY   YZ
|		XZ
|
|	of this 3D image will pop up.  Standard "xv" manipulations in this
|	"xv" window can then be performed.
|
|		click on  "text"
|
|	and then
|	
|		click on  "case1.12.ex_spine.out"
|
|	and a scrolling window will bring up the output file
|	produced by the Project Raw Image  run. This output
|	file echoes all data (default or over-ride) used by
|_	the "3dma"  executable to produce the plot.

Fig. 1:   The projected picture ../raw/draw/ex_spine_rsz_proj.ras.gz

V.A.2) Resize Raw Image      Back to Table of Contents

This option excises a subvolume of a data set for future analysis. The subvolume is stored in an mtif file in the raw directory with the extension ".rsz".

Test Example: (data is "mywork/raw/ex_*.rsz.gz")
|		
|	Note: Since the test data already has the extension ".rsz.",
|	attempting to run "resize raw image" on the test data will
|	overwrite the existing data file unless care is made to
|	rename the newly created resized data set.
|
|	Recall, to get here
|			click on "New Run"
|			click on "Dendritic Spine"
|			click on "Resize Raw Data"
|
|	This brings up the "Resize Raw Data" input window.
|	In the "Specify raw data" area, from the pull down menu
|
|		click on "resized".
|		click on "Load Data"
|
|	Two files will appear in the right, datafile list area.
|	
|		click on "../raw/ex_spine.rsz.gz"
|
|	to highlight it and press the spacebar to delete all other
|	files from the list.
|
|	In the main "over-ride header option" area
|
|	unset "Detect first column from header?" and enter an xs value of 50
|	unset "Detect last column from header?" and  enter an xe value of 150
|
|	make sure both
|		"Detect x-pixel spacing from header?"
|		"Detect y-pixel spacing from header?"
|	read "Yes".
|
|	set "Specify output file basename" to "Yes". Enter a base name
|						of "my_ex_spine"
|
|		click on "Run"
|
|	The "View Output Data" window will pop up and the following
|	informational text will appear in the "Process Status" area
|	of the "3dma Output and Runtime Control Menu"
|
|	----------------------------------------------------------
|	Project image (../resize.pm.8029):
|	started at Thu Oct  2 16:45:21 2003
|	runtime output will be written to "case1.3.*.out"
|	nohup: appending output to `nohup.out'
|	/home/med_ax/bin/run3dma:
|		line 23: test: =: unary operator expected
|	finished at Thu Oct  2 16:46:15 2003
|	See image file "../raw/draw/my_ex_spine_rsz_proj.ras.gz" under
|					output menu.
|	----------------------------------------------------------
|
|	In the "output menu" area of the "3dma output and runtime
|	control" window,
|
|		click on "image"
|		click on "../raw/draw/my_ex_spine_rsz_proj.ras.gz"
|
|	and an "xv" picture of the resized volume will pop up.
|
|		click on "text"
|
|	and a scrolling window will bring up the output file produced
|	by the "Project Raw Image"  run. This output file echoes all data
|	(default or over-ride) used by the 3dma  executable to produce
|_	the plot.

Fig. 2:   The resized projected picture ../raw/draw/my_ex_spine_rsz_proj.ras.gz

V.A.3) Image Enhancement (Median Filtering & Deconvolution)      Back to Table of Contents

Application of the spine dection routines requires a segmented image (one in which each voxel in the image has been identified as either neural or background tissue.) For optical microscopy, segmentation should be preceded by an "image enhancement step" involving deconvolution of the image to reverse the effect of the optical point spread function (PSF).

We also preceed the deconvolution step, by a median filter step to reduce the effects of "shot noise" (noise related to photomultiplier tube detectors).

Numerous deconvolution algorithms exist in the literature, typically employing either measured or estimated evaluations of the PSF. In our own work we have either used Iterative Deblurring [3] with measured point spread functions, or the commercial package AutoQuant [AutoQuant Imaging, Inc] to perform the deconvolution step. AutoQuant employs a blind deconvolution method which performs its own estimate of the PSF.

The 3DMA-Neuron distribution provides median filtering/iterative deblurring image enhancement. For full details on using this applition, see the 3DMA Users Manual for Dendritic Spine Analysis [5].

Note that a file containing the PSF, prepared as described in [5], is needed as input to this application. For the iterative deblurring algorithm we used an experimentally determined point spread function obtained by imaging (sub-focal volume sized) plastic beads which were embedded in the (upper part of) the tissue culture and could be imaged simultaneously with the neuron. Several small volumes, each containing the point spread function image from a single bead are then extracted from the large image volume. A single PSF image volume is obtained by averaging over there several bead images. This averaged PSF volume image is used as input for the "Image Enhancement" step.

As the images provided with in the "Test" directory with this distribution have already been deconvolved, no test example is given for the image enhancement step. However with an appropriate PSF and an image to be enhanced, the steps for running this application are similar to options 1) and 2) above:

click on "New Run"
click on "Dendritic Spine"
click on "Enhance Image"

An "Enhance Raw Data" window pops up which allows for Data Loading and overriding of default input options. With the Data loaded and input values set (possibly with over-ride of default input values)

click on "Run"

The image enhancement application produces stores the enhanced image in the "raw/" directory, in mtif format (with the file extension ".deb"), and produces a graphics file (in "raw/draw") showing the XY, XZ and YZ projected views of the enanced image.

V.A.4) Image Volume Histogram      Back to Table of Contents

This option produces a histogram of the intensity values in any raw data file. Examination of the histogram for the enhanced image is useful in the image segmentation step, (see V.A.5) to pick either the threshold for simple segmentation or the lower and upper thresholds for indicator kriging.

Test Example: (data is  "mywork/raw/ex_*.rsz.gz")
|		
|	Recall, to get here
|			click on "New Run"
|			click on "Dendritic Spine"
|			click on "Image Volume Histogram"
|
|	This brings up the "Raw Data Histogram" input window.
|	In the "Specify raw data" area, from the pull down menu
|
|		click on "resized".
|		click on "Load Data"
|
|	In the datafile list area on the right of this window,
|	follow instructions to delete all but the file
|	"../raw/ex_spine.rsz.gz"
|
|	In the main over-ride header option area, do nothing (leave
|	all options default).
|
|		click on "Run"
|
|	A "Proceed with Run" window pops up.
|
|		click on "OK"
|
|	The "View Output Data" window will pop up and the following
|	informational text will appear in the "Process Status" area
|	of the "3dma Output and Runtime Control Menu"
|
|	----------------------------------------------------------
|	Image volume histogram (../phicut.pm.11349):
|	started at Fri Oct  3 14:34:15 2003
|	runtime output will be written to "case1.6.*.out"
|	/home/med_ax/bin/run3dma: line 23:
|				test: =: unary operator expected
|	finished at Fri Oct  3 14:34:35 2003
|	See "jgraph" file "../raw/jgr/ex_spine_rsz_pcut.jgr" under
|							output menu.
|	----------------------------------------------------------
|
|	In the "output menu" area of the "3dma output and runtime
|	control" window,
|
|		click on "jgraph"
|		click on "../raw/draw/ex_spine_rsz_pcut.jgr"
|
|	and a postscript viewing window (either "ghostscript" or "ggv"
|	depending on your system) will pop up displaying a histogram
|	of the intensity distribution. Typically two peaks appear in
|	the histogram, one corresponding to background tissue, the
|	other to neural (fluorescing) tissue. For most microscopes,
|	neural tissue has high intensity values, and non-fluorescing
|	tissue has low. The two peaks overlap, though often with a
|	very broad valley between.
|
|		click on "text"
|
|	and a scrolling window will bring up the output file
|	("case1.6.ex_spine.out") produced by this run. This output file
|	echoes all data (default or over-ride) used by the 3dma
|_	executable to produce the plot.

Fig. 3:   The jgraph plot of the histogram in the file ../raw/draw/ex_spine_rsz_pcut.jgr showing the (broader) background tissue peak (left) and the (narrower) neural tissue peak (right).

V.A.5) Spine Detection Routines      Back to Table of Contents

The spine detection application performs a sequence of 3dma command line calls, depending on whether a static image analysis or a timeseries analysis is to be performed. For static analysis, the sequence order consists of

Image Segmentation
Medial Axis Extraction
Medial Axis Cleanup
Spine Detection
Static Spine Merging

Timeseries Spine Tracing
Timeseries Data Analysis

For information on these specific algorithms, and their controlling parameters, see [4].

Test Example:
|	Recall, to get here
|			click on "New Run"
|			click on "Dendritic Spine"
|			click on "Spine Detection Routines"
|
|	The "Spine Routines" window pops up. A pull down menu allows
|	selection of  "Static Image Routines" or "Timeseries Images"
|	routines. This test example uses a single static image, therefore
|
|			click on "Static Image"
|			click on "Continue"
|
|	The "Spine Detection Data and Parameter Settings" window pops up
|_

The "Spine Detection Data and Parameter Settings" window controls data loading and parameter default value over-riding

Test Example (cont'd):
|	Continuing this test example, we are going to perform spine
|	analysis on the file  "raw/ex_spine.rsz", which has been
|	resized from a larger data set and deconvolved using AutoQuant.
|	If the image had been enhanced using the iterative deblurring
|	algorithm, it would have the extension ".deb" rather than ".rsz"
|
|	In the "Specify raw data" area, from the pull down menu
|
|		click on "resized"
|		click on "Load Data"
|
|	Of the filenames that appear in the righthandside datafile list
|	area, delete all files except 	"../raw/ex_spine.rsz.gz"
|_

Two segmentation algorithms are provided in 3DMA-Neuron, simple thresholding and Indicator Kriging [6,7].

For simple thresholding a single threshold value is chosen. Often this threshold is picked through a trial and error basis: using the histogram produced in application V.A.4 above to choose an initial value; running application V.A.5 (with ONLY the "Image Segmentation" step enabled) to produce a segmented image; and examination of projected views (produced at the same time) of the segmented image to judge the quality of the segmentation.

For indicator kriging, two thresholds establishing a window are required [6,7]. The tolerance on choice of these thresholds is less critical and can often be set successfully from one observation of the histogram of the enhanced image produced by V.4.

Test Example (cont'd):
|	In the "Spine Detection Data and Parameter Settings" window
|	use the default values  "Simple Thresholding" and "lower
|	threshold = 128". (There is only a single threshold needed
|	in simple thresholding. It is entered through the lower
|	threshold setting in the window.)
|
|	Ensure the "Use fiducial polygon" options is "NO". For
|	further information on using fiducial polygons, see [6].
|
|	These settings must be saved,
|
|		click on "Save Simple Settings"
|
|	and confirm with a
|
|		click on "Save Simple Settings"
|
|	on the "Confirm Settings" pop up.
|	A "Message_popup" window will report start and end timesteps
|	of 1.
|
|_		click on "OK"

There are additional default value over-ride settings available through the "Additional Settings" button. These options control parameters of the spine detection algorithms discussed in [4]. In particular:

As described in Section 3.2 (Dendritic Backbone Extraction) of [4], by default a dendritic backbone is traced through each dendritic branch according to a minimum deviation angle criterion. For some applications however, (such as when dendritic branch order is important), it is desirable to identify distinct dendrite segments for all branches at a branch point. To obtain these distinct segments, the user should set "Terminate dendrites at branch points" to "YES" under the "Additional Settings" menu.

To illustrate this, under the default setting the following sketch would be interpreted as 2 dendrite branches labeled as indicated:

		               2
	                     /
	                    /
	                   /
	    1 --------------------- 1

		               2
	                     /
	                    /
	                   /
	    1 --------------------- 3

Test Example (cont'd):
|	Once all parameters have been confirmed
|
|		click on "Run"
|
|	Confirm "proceed with run?" on the "Message" pop_up
|	Note this run will take on the order of 10 minutes.
|
|	The "View Output Data" window will pop up and the following
|	informational text will appear in the "Process Status" area
|	of the "3dma Output and Runtime Control Menu"
|	----------------------------------------------------------
|	Spine detection routines (../spine.run.12253):
|	started at Fri Oct  3 15:45:26 2003
|	runtime output will be written to "case1.5.*.out"
|	runtime output will be written to "case2.2.*.out"
|	runtime output will be written to "case4.11.*.out"
|	runtime output will be written to "case4.19.*.out"
|	runtime output will be written to "case6.4.*.out"
	|	nohup: appending output to `nohup.out'
|	/home/med_ax/bin/run3dma: line 23:
|				test: =: unary operator expected
|	finished at Fri Oct  3 15:56:43 2003
|	See image file "../seg/draw/ex_spine_proj.ras.gz" under
|							output menu.
|	See image file "../ma/draw/ex_spine_ma_proj.ras.gz" under
|							output menu.
|	See image file "../ma/draw/ex_spine_trim_proj.ras.gz" under
|							output menu.
|	See text file "../spine/detect/ex_spine_den_len" under
|							output menu.
|	See image file "../spine/draw/ex_spine_spine_proj.ras.gz" under
|							output menu.
|	See image file "../spine/draw/ex_spine_merge_proj.ras.gz" under
|							output menu.
|	See text file "../spine/detect/ex_spine_den_len" under output
|							menu.
|	See jgraph file "../spine/jgr/ex_spine_shape.jgr" under output
|							menu.
|	See jgraph file "../spine/jgr/ex_spine_shape.jgr" under output
|							menu.
|_	----------------------------------------------------------

Each successive command line call produces output files and images used either as input data for a subsequent step or as informational purposes for the user. The files produced are outlined below:

Command line	files stored in	file content
Segmentation	seg/*.seg.gz	the segmented image
	seg/draw/*_proj.ras.gz	projective views of the segmented image
		Fig. 4:   The projected picture ../raw/draw/ex_spine_seg_proj.ras.gz of the segmented data
Medial Axis Extraction	ma/*.ma.gz	medial axis data
	ma/draw/*_proj.ras.gz	projective views of the medial axis
		Fig. 5:   The projected picture ../raw/draw/ex_spine_ma_proj.ras.gz of the medial axis displayed in the segmented image.
Medial Axis Cleanup	ma/*.trim.gz	trimmed medial axis data
	ma/draw/*_trim_proj.ras.gz	projective views of trimmed medial axis
		Fig. 6:   The projected picture ../raw/draw/ex_spine_trim_proj.ras.gz of the trimmed medial axis.
Spine Detection	spine/detect/*_den_len	text file of spine data
	spine/draw/*_spine_proj.ras.gz	projective view of identified spines before any detached spine head/base merging
		Fig. 6:   The projected picture ../raw/draw/ex_spine_spine_proj.ras.gz of identified spines before any detached spine head/base merging. (Colors differ for different spines.)
	spine/jgr/*_shape.jgr	graphical file of spine volume vs length scatterplot
Static Spine Merging	spine/detect/*_den_len	text file^ of spine data after any detached spine head/base merges
	spine/detect/*_merge.gz	binary data file of spine data after merging
	spine/draw/*_spine_merge_proj.ras.gz	projective view of identified spines after any detached spine head/base merging (and rejection of some spines based upon boundary or distance criteria)
		Fig. 7:   The projected picture ../raw/draw/ex_spine_merge_proj.ras.gz of identified spines after any detached spine head/base merging. (Colors differ for different spines).
	spine/jgr/*_shape.jgr	graphical file^ of spine volume vs length scatterplot
-------------
^ overwrites file of same name from previous step

The graphics files produced can be viewed from the GUI using the "jgraph" and "image" buttons on the "output menu" of the "3dma output and runtime control" window.

Test Example (cont'd):
|
|		click on "image"
|		click on "../seg/draw/ex_spine_proj.ras.gz"
|
|	an "xv" image showing three projective views of the segmented
|	image pops up.
|
|		click on "image"
|		click on "../ma/draw/ex_spine_ma_proj.ras.gz"
|
|	an "xv" image showing the XY projective view of the medial
|	axis of the neural tissue pops up.
|
|		click on "image"
|		click on "../ma/draw/ex_spine_trim_proj.ras.gz "
|
|	an "xv" image showing the XY projective view of the backbone
|	of the dendritic branches pops up.
|
|		click on "image"
|		click on "../spine/draw/ex_spine_spine_proj.ras.gz "
|
|	an "xv" image showing the XY projective view of the identified
|	spines pops up. This is before detached spine head/base merging.
|	Spines are labeled different colors.
|
|		click on "image"
|		click on "../spine/draw/ex_spine_merge_proj.ras.gz "
|
|	an "xv" image showing the XY projective view of the identified
|	spines pops up. This is after detached spine head/base merging
|	and any "spine" touching the boundary has been eliminated.
|	Spines are labeled different colors.
|	
|		click on "jgraph"
|		click on "../spine/jgr/ex_spine_shape.jgr"
|
|	A "ggv" image of a volume/length scatterplot for the population
|	of spines detected in the image is displayed. The spines are
|_	categorized by shape in the scatterplot.

The _den_len file has the following format:

int * 1		number of dendrites
float * 3	voxel dimensions (x,y,z)

int * 2		dendrite number, number of ma voxels on dendrite
int * 3		coordinates of first ma voxel on dendrite
 ...
int * 3		coordinates of last ma voxel on dendrite

(repeat above pattern for each dendrite)

int * 2		dendrite number, number of (putative) spines
float * 5	length, volume and center of mass coordinates (x,y,z) of first spine
 ...
float * 5	length, volume and center of mass coordinates (x,y,z) of last spine

(repeat above pattern for each dendrite)

int * 2				dendrite number, number of (putative) spines
float * 5 char float * 2	length, volume and center of mass coordinates (x,y,z),
				shape classification, neck width, head width of first spine
 ...
float * 5 char float * 2	length, volume and center of mass coordinates (x,y,z),
				shape classification, head width, neck width of last spine

(repeat above pattern for each dendrite)

This option allows user input to remove any obvious false positive spines and/or dendritic segments.

Test Example:
|	Recall, to get here
|			click on "New Run"
|			click on "Dendritic Spine"
|			click on "Edit Detected Spines"
|
|_	The "Spine Removal" control window pops up.

The "Spine Removal" window requires designation of static or timeseries data, and allows the user to select the appropriate

spine/detect/*.merge.gz

Test Example (cont'd):
|	From the pull down menu,
|
|		select "Static"
|
|	spine file type. From the data file selection list,
|
|		doubleclick on "../spine/detect/ex_spine.merge.gz"
|
|_	A "Spine Editing" window pops up.

In the "Spine Editing" window, the appropriate xy projective view (../spine/draw/*_merge_proj.ras.gz) will appear in the left area of the window, showing each dendrite and spine identified. The list of spines identified in this image appears in the area to the right, with certain information (Spine Index, Dendrite Index, X, Y, and Z position, Length, Volume, Number of Voxels) given each spine. Spines and/or dendrites can be edited by mouse clicks on the image in the left area, or by toggling buttons in the spine index or dendritic index columns in the list on the right. Changes made to the image will be reflected in the spine list, and vice versa.

a) Editing from the image

Left-clicking on an object in the image allows displays cross referencing information to the table:

• Left-clicking on a colored dendritic spine will display

  * Spine Y of Dendrite X *

  where Y and X are the respective spine and dendrite index numbers.
• Left clicking on a colored dendritic backbone will display

  * Dendrite X *

  where X is the dendrite index numbers.
• Left clicking on an undefined space in the image will display

  * No spine is selected *

Right (or center) clicks toggle select/deselection of an object (spine or dendrite). When deselected, the color of the object disappears; if reselected the color appears.

NOTE: Deselecting a dendrite will simultaneously deselect all spines along that dendrite. Deselection of a dendrite must be confirmed via a pop up window.

NOTE: If a dendrite is re-selected, its spines are NOT re-selected automatically. The user must re-select each spine individually.

b) Editing from the spine list

Spines can be selected/deselected by clicking on buttons in the spine index column. Dendrites can also be selected/deselected via buttons in the dendrite index column.

NOTE: As with clicking in the image, deselecting a dendrite from the spine list will simultaneously deselect all spines along that dendrite. However there is no confirmation required to deselect a dendrite from the spine list.

NOTE: As with clicking in the image, if a dendrite is re-selected, its spines are NOT re-selected automatically. The user must re-select each spine individually.

The organization of the spine list can be changed by the "Sorting" drop-down box whicih appears below the spine list. Spines can be sorted by any column in the list; the default is to sort by dendrite index.

Test Example (cont'd):
|	In the image in the left area, left-click on the large orange
|	ojbect in the middle bottom of the view. This is clearly a
|	false positive spine (too large, too far from the dendrite).
|	The information
|
|		* Spine 11 of Dendrite 4 *
|
|	appears. A glance at the right hand table identifies the
|	characteristics of this "spine".
|
|	Left clicking on the purple dendritic backbone produces
|
|		* Dendrite 4 *
|
|	indicating the dendritic segment with which spine 11 is paired.
|	Right click on "dendrite 11" (either by clicking the orange
|	"spine" or by clicking the spine index 11 box in the table.
|	The orange color vanishes and the corresponding box in the
|	rhs table shows deselection.
|
|		click "Save"
|
|_	A "Save Edited Data" pop up appears.

When all the appropriate edits have been made, click "Save" to save the edits, or "Quit" to quit without saving changes. When saving edited data, the original spine file will be overwritten unless the user identifies an alternate basename to be used.

Test Example (cont'd):
|	In the "Save Edited Data" window
|
|		click "NO"
|		enter "ex_spine_edit"
|
|	to save the edited data in a new file (without destroying
|	the old).
|
|		click "Continue"
|
|	----------------------------------------------------------
|	Detected spine editing (case6.7):
|		started at Fri Oct  3 18:42:38 2003
|		runtime output will be written to "case6.7.ex_spine.out"
|	nohup: appending output to `nohup.out'
|		finished at Fri Oct  3 19:17:32 2003
|	See image file "../spine/draw/ex_spine_edit_merge_proj.ras.gz"
|	under output menu.
|	----------------------------------------------------------
|
|	appears in the process status area of the "3dma output and 
|	runtime control" window. In the "output menu" area of this
|	window,
|
|		click "image"
|		select "../spine/draw/ex_spine_edit_merge_proj.ras.gz"
|
|	to bring up an  "xv"  window showing the xy projection of the
|	edited spine image. This should be identical to the last image
|_	seen in the left hand area of the spine editing window.

V.A.7) Static Spine Analysis      Back to Table of Contents

Static Spine Analysis uses the files

spine/detect/*_den_len

Test Example:
|	Recall, to get here
|			click on "New Run"
|			click on "Dendritic Spine"
|			click on "Static Spine Analysis"
|
|_	The "Static Spine Analysis" control window pops up.

The "Static Spine Analysis" control window allows the user to select appropriate data files (by default the "../spine/detect/*_den_len" files) and chose an output file name for the analysis (by default "../spine/detect/analysis.txt"). There is a futher option to ignore analysis of any dendrite shorter that a specified length. (This can also be used to eliminate short, false positive dendrites.)

Test Example (cont'd):
|	
|	Edit the "Data Filename" entry: "../spine/detect/*_edit_den_len"
|		click on "Load Data"
|		click on "Run"
|
|	The following text,
|
|	*** Check and delete data files if necessary ***
|	See text file "../spine/detect/analysis.txt" under output menu.
|	nohup: appending output to `nohup.out'
|	****************************************************
|
|	will appear in the "process status" window of the "3dma output
|	and runtime control" window. In the "output menu" area of
|	this window,
|
|			click "text"
|			select "../spine/detect/analsys.txt"
|
|	a scrolling window will show the contents of the "analysis.txt"
|_	file.

Note: If the default output file ("spine/detect/analysis.txt") already exists, its contents will be overwritten.

Note: The contents of the output file ("spine/detect/analysis.txt") are well documented internally.

Note: In the static spine analysis, the reported spine volumes are normalized to the focal volume of the imaging microscope.

8) Set and Run Timeseries      Back to Table of Contents

This will analyze timeseries spine data. For details see [4].

V.B) Neuron Tracing      Back to Table of Contents

3DMA-Neuron also has the capability of tracing dendtritic trees, providing labeling of separate brushes leaving the soma and of dendritic branch segments. It also performs standard morphological measures (Sholl sphere, Ralls ratio, branch angle) analysis on the brushes.

In the "Applications" window,

click on "Neuron"

Project Raw Image
Resize Raw Image
Enhance Image
Image Volume Histogram
Preprocessing Routines
Neuron Tracing

V.B.1- 4)      Back to Table of Contents

For a discussion of the purposes for, and instructions on, running applications V.B.1) through V.B.4), refer to V.A.1 through V.A.4 noting that the string "ex_spine" should now be replaced by the string "ex_neur" everywhere in the Test Examples.

V.B.5) Preprocessing Routines      Back to Table of Contents

The so-called "preprocessing" module performs three operations on the (enhanced) neuron image: image segmentation, medial axis extraction, and medial axis trimming, which must be completed before the final dendritic tracing step can be performed. (Dendritic tracing utilizes the medial axis backbones of the dendrites obtained from the trimmed medial axis of the neuron.)

Test Example:
|	Recall, to get here
|			click on "New Run"
|			click on "Neuron"
|			click on "Preprocessing Routines"
|
|_	The "Neuron Routines" control window pops up.

The "Neuron Routines" control window allows the user to turn off/on four command lines

Image Segmentation
Disconnected Volume Distribution
Medial Axis Extraction
Medial Axis Cleanup

By default, the "Disconnected Volume Distribution" routine is "off" and the other three are "on". The "Disconnected Volume Distribution" is useful as a quantitative test for the quality of the segmentation step by measuring how disconnected the neuron image becomes after segmentation. It only produces informative information.

Test Example (cont'd):
|	
|	Retain the default on/off setting in the "Neuron Routine Selection"
|	area.
|
|		click on "Continue"
|
|_	This brings up the "Neuron Tracing Data and Parameter Settings" window.

The "Neuron Tracing Data and Parameter Settings" window enables the user to choose the data file(s) to process and algorithmic parameters values to use during the processing. It is similar to the "Spine Detection Data and Parameter Settings" window of section V.A.

Test Example (cont'd):
|	In the "specify raw data filename and format" area, from the pull
|	menu
|
|		click on "resized"
|		click on "Load Data"
|
|	Of the filenames that appear in the righthandside datafile list
|	area, delete all files except 	"../raw/ex_neur.rsz.gz"
|_

Section V.A.5 discusses the two segmentation algorithms provided in 3DMA-Neuron. As choice between those is provided in the "Neuron Tracing Data and Parameter Settings" window.

Test Example (cont'd):
|	In the "Spine Detection Data and Parameter Settings" window
|	use the default value
|
|		"Simple Thresholding"
|
|	BUT set
|
|		"lower threshold = 14"
|
|	(There is only a single threshold needed in simple thresholding. It
|	is entered through the lower threshold setting in the window.)
|
|	Ensure the "Use fiducial polygon" options is "NO". For
|	further information on using fiducial polygons, see [6].
|
|	Ignore the "Soma Shape" input option.
|
|	These settings must be saved,
|
|		click on "Save Simple Settings"
|
|	and confirm with a
|
|		click on "Save Simple Settings"
|
|	on the "Confirm Settings" pop up*.
|
|	------------------------
|	* Note that the "Confirm Settings" window may not disappear correctly.
|_	This will not affect your run.

There are additional default value over-ride settings available through the "Additional Settings" button. These options control parameters of the neuron detection algorithms discussed in [Weaver, 2003].

Test Example (cont'd):
|		click on "Run"
|
|	In the "Message pop-up" window
|
|		click on "OK"
|
|	The following text,
|
|	----------------------------------------------------------
|	Neuron tracing routines (../neuron.run.12479):
|		started at Tue Oct  7 17:37:36 2003
|		runtime output will be written to "case1.5.*.out"
|		runtime output will be written to "case2.2.*.out"
|		runtime output will be written to "case4.11.*.out"
|	nohup: appending output to `nohup.out'
|	/home/med_ax/bin/run3dma: line 23: test: =: unary operator expected
|		finished at Tue Oct  7 17:40:23 2003
|	See image file "../seg/draw/ex_neur_proj.ras.gz" under output menu.
|	See image file "../ma/draw/ex_neur_ma_proj.ras.gz" under output menu.
|	See image file "../ma/draw/ex_neur_trim_proj.ras.gz" under output menu.
|	----------------------------------------------------------
|
|	will appear in the "process status" window of the "3dma output
|	and runtime control" window. In the "output menu" area of
|	this window,
|
|			click "image"
|
|	to see a menu
|
|		../seg/draw/ex_neur_proj.ras.gz
|		../ma/draw/ex_neur_ma_proj.ras.gz
|		../ma/draw/ex_neur_trim_proj.ras.gz
|	
|_	of three output images for display.

The three images for display are xy projected views of, respectively, the segmented image, the medial axis of the neuron before cleanup, and the medial axis of the neuron after cleanup.

V.B.6) Neuron Tracing      Back to Table of Contents

This module performs the tracing of the dendritic brushes, using the medial axis backbone extracted from the trimmed medial axis. The tracing is automated except for two steps. The user must perform a click and drag operation to place an ellipsoidal cylinder around the soma, removing it (and it's medial axis components) from consideration. The user must click on the apical brush (if one is present) to distinguish it from basal brushes.

Test Example:
|	Recall, to get here
|		click on "New Run"
|		click on "Neuron"
|		click on "Neuron Tracing"
|
|_	The "Neuron Tracing" control window pops up.

The "Neuron Tracing" window allows the user to pick the trimmed data set(s) for analysis.

Test Example (cont'd):
|	In the datafile list space
|	
|		highlight "../ma/ex_neur.trim.gz"
|		hit the spacebar to delete all other files from the list
|-		doubleclick on "ex_neur.trim.gz"

The "Neuron Editing" window will appear and an xy projection\ of the selected *.trim file will be displayed in the area on the left of the window. The medial axis of the neuron will appear in color.

This window allows the user to select an elliptical region containing the soma. This region will be excluded from branching analysis. The user can also (optionally) select the apical brush, allowing 3DMA-Neuron to output separate results for the apical brush and basal brush(es).

Soma Selection

The mouse is used to draw an ellipse around (part of) the soma on the displayed picture on the left. As an ellipse is drawn, information on its center point and size appear in the "Mouse Selection" area on the upper right. Clicking the "Add" button will save this information. If the "Add" button is not pressed, this ellipse information is not saved. This allows a user to redraw the ellipse multiple times until satisfied. If a single ellipse does not sufficed the user may draw and save multiple ellipses. (The "Add" button must be clicked for each ellipse to be saved.) The soma is defined to be the area enclosed by the union of the ellipses.

As the automated dendrite branching analysis traces through the medial axis of the neuron, the only essential information needed is the medial axis segments lying within the elliptical area. Thus all axis segments contained within the ellipse area omitted from subsequent dendritic branching tracing. With each click of the "Add" button, medial axis segments lying within (union of) elliptical region are colored blue.

Test Example (cont'd):
|	In the image on the left
|
|		perform a "click and drag" operation to generate an ellipse.
|
|	repeat the "click and drag" until an ellipse with  satisfactory
|	placement/size is generated.
|
|	In the "Add Selection to Soma Area" 
|
|		click on "Add"
|
|	In the image, note the medial axis in the elliptical region is now
|	colored blue.
|
|_		click on "Next Step"

Soma (medial axis segments within the elliptical region) terminates when the "Next Step" button is clicked.

Note, there is no current means of gracefully deleting an ellipse that has been saved during this process. At this point the user must press "Quit" and follow obvious prompts to restart.

Apical Brush Selection

Right-clicking on any medial axis segment exiting from the soma region will identify that segment as the (root of) an apical brush. All branches associated with this segment will be displayed in pink. Repeated clicks on root segments of other brushes will allow for multiple apical brush selections. If an error is made in selecting a brush, clicking on "Clear Selections" will clear all apical selections, allowing for re-entry of selection.

Apical brush selection is terminated when the "Save" button is clicked. After "Save" is clicked, neuron tracing is performed automatically. Relvant statistical graphs are output to the neuron/jgr directory and Images are printed in neuron/draw. A file, with the extension ".swc", in standard SWC format (see [1]) containing summary data on the neuron branching structure is placed in the neuron/ directory.

Test Example (cont'd):
|	In the image on the left
|
|		click on the medial axis (root) segment on the apical brush
|	which is leaving the soma on the upper right hand side.
|
|	The brush should turn pink.
|
|		click on "Save"
|
|	The following appears in the "process status" region of the
|	"3dma output and runtime control" window:
|
|	----------------------------------------------------------
|	Neuron tracing (../neuron.run.16967):
|	started at Wed Oct  8 15:58:27 2003
|		runtime output will be written to "case4.20.*.out"
|		nohup: appending output to `nohup.out'
|	finished at Wed Oct  8 18:24:52 2003
|	See image file "../neuron/draw/ex_neur_apical_brush_proj.ras.gz" under output menu.
|	See image file "../neuron/draw/ex_neur_apical_neuron_proj.ras.gz" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_moi.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_sholl.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_vec2leaf.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_branch_radius.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_branch_angle.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_rall.bo.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_rall.tk.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_rall.bo_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_rall.r_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_taper.bo.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_taper.r.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_taper.bo_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_taper.r_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_apical_dendrite_len.jgr" under output menu.
|	See image file "../neuron/draw/ex_neur_basal_brush_proj.ras.gz" under output menu.
|	See image file "../neuron/draw/ex_neur_basal_neuron_proj.ras.gz" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_moi.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_sholl.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_vec2leaf.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_branch_radius.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_branch_angle.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_rall.bo.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_rall.tk.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_rall.bo_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_rall.r_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_taper.bo.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_taper.r.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_taper.bo_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_taper.r_std.jgr" under output menu.
|	See jgraph file "../neuron/jgr/ex_neur_basal_dendrite_len.jgr" under output menu.
|-	----------------------------------------------------------

The image "../neuron/draw/*_basal_brush_proj.ras.gz" shows xy, xz and yz projective views of the basal brushes, with each separate brush leaving the soma plotted in a different color. The (medial axis for the) soma is plotted in pink.

The image "../neuron/draw/*_basal_neuron_proj.ras.gz" shows xy, xz and yz projective views of the basal brushes, with each separate branch order plotted in a different color. The (medial axis for the) soma is plotted in pink.

The two remaining images labeled "apical" show the respective plots for the apical brush(es).

For the basal and apical brushes separately, 14 statistical plots are generated (stored as jgraph plots in the directory "../neuron/jgr"). The name and contents of each plot are briefly described in the following table. Each plot can be access through the "jgraph" pulldown menu in the "output menu" section of the "3dma output and runtime control" window.

3DMA-Neuron

File	Contents
"*_moi.jgr"	moment of inertial analysis of brush
"*_sholl.jgr"	Sholl sphere analysis of brush
"*_vec2leaf.jgr"	projective plot of dentritic tips in 2D planes defined by the principle directions of the brush
"*_branch_radius.jgr"	branch points vs radial distance from soma
"*_branch_angle.jgr"	histogram of branching angles
"*_rall.bo.jgr"	scatterplot: Rall's ratio vs branch order
"*_rall.bo_std.jgr"	mean and standard deviation for above plot
"*_rall.tk.jgr"	scatterplot: Rall's ratio vs branch thickness
"*_rall.r_std.jgr"	mean and standard deviation for above plot
"*_taper.bo.jgr"	scatterplot: tapering ratio vs branch order
"*_taper.bo_std.jgr"	mean and standard deviation for the above plot
"*_taper.r.jgr"	scatterplot: tapering ratio vs branch thickness
"*_taper.r_std.jgr"	mean and standard deviation for the above plot <
"*_dendrite_len.jgr"	histogram: soma to tip length in brush

VI) References      Back to Table of Contents

[1] Cannon RC, Turner DA, Pyapali GK, Wheal HV. An on-line archive of reconstructed hippocampal neurons. J Neurosci Meth 84 (1998) 49-54.

[2] http://www.cs.utk.edu/~plank/plank/jgraph/jgraph.html

[3] Kawata S, Ichioka Y. Iterative image restoration for linearly degraded images, I. basis and II. reblurring procedure. J Opt Soc Am 70 (1980) 762-772.

[4] Koh IYY, Lindquist WB, Zito K, Nimchinsky EA, Svoboda K. An image analysis algorithm for fine structure of neuronal dendrites. Neural Comput 14 (2002) 1283-1310.

[5] Koh IYY Lindquist WB. 3DMA Users Manual for Dendritic Spine Analysis. SUNY-Stony Brook report SUNYSB-AMS-00-03, 2000.

[6] Lindquist WB. 3DMA General Users Manual, SUNY-Stony Brook report SUNYSB-AMS-99-20, 1999.

[7] Oh W, Lindquist WB. Image thresholding by indicator kriging. IEEE Trans Pattern Anal Mach Intell 21 (1999) 590--602.