adaptiveSPT Files

*******************************************************************************
adaptiveSPT (Adaptive Single Particle Tracking) - README
*******************************************************************************

12 December 2014

These directories contain the Matlab code for the algorithm adaptive Single 
Particle Tracking, described in 
"Adaptive settings for the nearest-neighbor particle tracking algorithm", J. Mazzaferri, 
J. Roy, S. Lefrancois, S. Costantino. Publication in Bioinformatics on December 4th, 2014.
doi: 10.1093/bioinformatics/btu793

The code was tested in MatlabR2013a for MAC, and MatlabR2014a for Linuxx, but is written to be platform independent.

All functions are fairly documented.

% -------------------------------------------------------------------------
% Copyright (C) 2014 Javier Mazzaferri
% javier.mazzaferri@gmail.com
% Centre de Recherche, Hopital Maisonneuve-Rosemont
% www.biophotonics.ca
% 
% 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 3 of the License, or
% (at your option) any later version.
% 
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
% 
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
DIRECTORY CONTENTS
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Directory "tracking": Contains the functions to perform adaptive SPT. 
The main function is trackAdaptive.m. The rest of files in the directory are subroutines called by trackAdaptive.m, or other tracking related functions for the study.

Directory "tools": Contains functions used by tracking routines and study routines.

Directory "detection": Contain functions to detect objects for tracking

Directory "study": Contains the code to generate the figures in the paper. They provide an example of how to use trackingAdaptive.m. In general, for each results figure in the paper there are two files: performance_###.m and plotperformance_###.m. The first generates the data, that is stored in the directory "data", one step upstream from the code directory. The second, read the generated files and makes the plots.

Directory "study/SPTChallenge": Contains the code used to process the datasets of the SPT challenge (Chenouard, N.Meth., 2014).

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
BASIC DESCRIPTION OF trackAdaptive.m
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
FUNCTION HEADER:
function [oTracks, status] = trackAdaptive(oPos,[],trackPar,imSz, combTol, avgSz)
                             

INPUT PARAMETERS:
   oPos(array): with columns [x, y, t]. Each row describes a particle position in a 
                specific frame.  
   imSz(array): image size [rows columns] 
   trackPar   :    Structure with fields
        mem               = frames a particle can be lost
        dim               = Dimensionality of problem (2D)
        good              = minimal trajectory length
        quiet             = Verbosity
        minDisplacement   = Minimum limit of mD
        toMaxDisplacement = Maximum limit of mD
   
   combTol : Limit number of bond combinations used to compute mD
   avgSz   : Diameter of the circular averaging neighborhood used to compute Dphi(x,y)
   

 OUTPUT:
   oTracks(array): with columns [x, y, t, ID]. Each row describes a particle position in a 
                   specific frame, for a specific particle (ID)  
   status: 
      0: Success
     -1: Low number of objects
     -2: Excesive combinatorics
     -3: All Particles at same time
     -4: Wrong Time order

TYPICAL USE:
   see "performance_vs_inhom.m", as an example.