DISTRIBUTION NOTES
Creation date: 9/8/06
Last revision: 9/8/06

Copyright (C) 2006 by Mark-Anthony Bray, Disease Biophysics Group (DBG), School of
	Engineering and Applied Sciences. 
Email contact: b r a y m p {at} s e a s {dot} h a r v a r d {dot} e d u.
DBG director: Prof. Kevin Kit Parker

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
ABOUT THE SPARK DETECTION CODE:

The following is excepted from the SparkDetection help section and lists the expected inputs and the resulting outputs.

--------------------------------
INPUT: A structure, PARAMETERS, with the following fields:

PreProcessedData: Represents {\Delta}F/F_0. All pre-processing of the data, 
	including background subtraction and smoothing (of whatever type) should
	be accomplished prior to input into the program.
	Dimensions: The data matrix can be 2- or 3-D, i.e., (x,t) linescan or
	    (x,y,t) full-frame data.

RegionOfInterestMask: a logical matrix, representing the region of interest
	(ROI) in the field of view, containing ones for pixels that are within 
	the ROI, zeros for those that are not. 
	Dimensions: If the data matrix is m x n x p, with the spatial 
	    information contained in dimensions m and n, RegionOfInterestMask
	    is of size m x n. 

ThresholdHigh: The higher threshold for spark detection. Set by the user to 
	an appropriate value. Cheng et al. (1999) use a value of 3.5*sigma,
	where sigma is the standard deviation of the noise.

--------------------------------
OUPUT: A structure, PARAMETERS, with the above fields intact, plus two 
	additional fields:
  
CurrentSparkMap: A matrix containing a set of connected objects ("regions")
	with each region representing a spark receving a label. 
	The elements of CurrentSparkMap are non-negative integer values. The 
	pixels labeled 0 are the background. The pixels labeled 1 make up the 
	first spark, the pixels labeled 2 make up the second spark, etc.
	Dimensions: Same size as PreProcessedData.
  
DetectedPeaks: A logical matrix with the locations of the spark maxima
	receiving a 1, and 0's elsewhere.
	Dimensions: Same size as PreProcessedData.
  
The following MATLAB toolboxes are required (all R14 or higher): 
     ImageProcessing: bwlabeln, watershed, bwdist, bwulterode (all essential)

The following MATLAB toolboxes are also used but can probably subsituted with equivalent code:

Spline: csaps (optional: for derivative calculation, can be substituted with
	'gradient' function, but runs the risk of lower accuracy)
  
Statistics: regress (optional: can probably be substituted with appropriate
	matrix division	for same result)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
ABOUT THE SYNTHETIC DATA:

In order to test the performance of the algorithm under controlled conditions, 
we generated synthetic (x,y,t) data sets composed of sparks accompanied by 
embedded noise. A stereotypical spark was produced by averaging a set of sparks 
obtained from experimental episodes in which the tissue was quiescent, i.e., no 
Ca2+ transients took place which would skew the temporal development of the 
spark fluorescence. 

Each synthetic data set was generated with a random number of stereotyped sparks 
placed at random (x,y,t) locations with the single constraint that the entire 
spark be contained within the boundaries of the data field-of-view. The spatial 
field-of-view and the temporal sampling rate were scaled such that they were 
identical to the images collected experimentally. The number of sparks per data 
set varied from 1 to 480, so that for the spatial and temporal sampling 
parameters used, the maximum spark frequency for a given data set would be 0.05 
sparks/um2/sec. Each spark was added to a field of Gaussian noise with a mean of
0 and a standard deviation of 1, with the sparks scaled in amplitude according 
to a random uniform distribution so that the SNR would match that of 
the experimentally collected data.

These data sets represent the input to the spark detection program in two forms:
(1) The unmodified original format with uniform background fluorescence. This 
    data is found in the directory 'SyntheticDataFiles\Uniform_Ca_Flourescence'
(2) Modified with a non-uniform decrease in fluorescence representative of the
    falling phase of a Ca2+ transient. The stereotypical reduction in 
    fluorescence during Ca2+ reuptake was obtained from a section of raw data 
    obtained experimentally, during which the entire tissue area was activated 
    by a Ca2+ transient. The fluorescence curve was taken as the temporal 
    average of the fluorescence covering the period of time starting from 75% of 
    full recovery; this curve was then added to the sparks and noise in (a) to 
    form a new synthetic data set. This data is found in the directory 
    'SyntheticDataFiles\Ca_Reuptake'

Each directory contains 60 sets of files, containing the following for each set:
(1) A image file composed of a TIFF-stack of images. Each file is 128 x 128 
    pixels by 50 frames, with each pixel representing 1.015 um and each frame 
    representing 11.1 ms.

(2) A MATLAB MAT-file consisting of variable called 'stats', which is a 
    structure with the following fields:
    (a) Scaling: A number between 0 and 8 representing the scaling of the spark 
	amplitude.
    (b) LocationOfPeak: A 3-element vector representing the (x,y,t) locaiton of 
	the spark.
    (c) Amplitude: The absolute amplitude of the spark, prior to the addition of
	noise.
    (d) FullWidthHalfMaximum: A 2-element vector representing the full-width, 
	half-maximum of the sparks in the x and y directions, in units of
	pixels. Same for all sparks.
    (e) SparkDuration: A 2-element vector representing the duration of the 
	sparks. The elements represent the number of frames before and after the 
	time of peak amplitude, in units of frames. Same for all sparks.
    The length of the 'stats' structure is equal to the number of sparks 
    contained in the data set.

(3) An Excel file with the same information as that given in the MAT-file, 
    arranged in columns.

The files in 'Ca_Reuptake' directory contains the same sparks (amplitude, 
placement, etc) as those in the  'Uniform_Ca_Flourescence' directory, but with the 
fluorescence curve added. Therefore, the statistics for the corresponding files 
are the same.