Stochastic Tractography Batch

(0) Requirements:

This module was tested on
(1) Python 2.5.4 (should work on 2.6, 3.0 was not tested so far) : http://www.python.org
(2) Numpy 1.2.1 or 1.3.0 : http://numpy.scipy.org/
(3) Parallel Python 1.5.7 : http://www.parallelpython.com/

remark: I advice ipython to do your development and test : http://ipython.scipy.org/

remark: It is a documentation in construction, be patient ;). Feel free to address any question or comment to me (see contact at the end of that doc)

(I) Overview:

This code implements a parallelization scheme to achieve stochastic tractography. It does not require the Slicer3 platform to run per se. However, the stochastic tractography generator from Slicer3 must be used to generate configuration set containing all Numpy format required files as inputs. It was successfully tested on a Dell cluster of 250 computing nodes. This batch system can be customized easily to any network of machines. So far, it was only tested on Linux 64bits systems. 

(II) Description:

(2.a) structure of folders: To accordingly run the scripts you must follow this folder structure (folder names are just for examplification purpose - you may use yours but for the Level3 that are assigned by the generators and are uniquely assigned - based on time stamp)

    Level0   Level1   Level2
   
--- compute/
        --- /comp1
               --- /1234561
               --- /1234562
               ...
        --- /comp2
               --- /1234571
               --- /1234572
               ...
        ...
        --- /compN
               --- /1234581
               --- /1234582
               ...

remark: N of Level1 can be 1 to any positive number. It is useful sometimes depending on your hardware resource to subdivide the configuration sets in different groups you can launch on different machines simultaneously (adding another degree of parallelization). 

remark: The folder structure have basically 3 levels. Level0 is the root. Level1 contains the groups of configuration sets you want to compute. Level2 (digit based format) contains the configuration sets and are generated by the Slicer3 generator module.


(2.b) scripts you can launch:

WARNING: never launch the autoTractoxxx.py scripts from Level0! It would erase your configuration sets. I will improve the behavior of the scripts on that matter.

(2.b.1) autoTracto2Regions.py: used when a 2 roi based tractography is to be done, takes no argument, must be launchned from Level1 (see 2.a) 

USE: shell>> python autoTracto2Regions.py

 
(2.b.2) autoTracto2RegionsWithMask.py: idem as (2.b.1) but your configuration contains an external brain mask (more specifically a white matter mask)

USE:  shell>> python autoTracto2RegionsWithMask.py 


(2.b.3) autoSlicerTracto2Regions.py: idem as (2.b.1) but communicates the results to a unique Slicer3 platform started on a remote(/local) machine, takes 2 arguments  

remark: care must be taken
  - for that script, the slicer dameon must be activated. If not, it must be and the Slicer3 restarted once again
  - a unique instance of Slicer3 must be launchned on the target machine. You should shutdown any other Slicer2/Slicer3 because of the fact that any slicer daemon runs on the same port (18943) for any Slicer2/3 launched!

USE:  python autoSlicerTracto2Regions.py <IP address of the machine running the Slicer3> <port of slicer daemon=18943>
 e.g. shell>> python autoSlicerTracto2Regions.py 127.0.0.1 18943


(2.b.4) autoSlicerTracto2RegionsWithMask.py: idem as (2.b.3) but your configuration contains an external brain mask (more specifically a white matter mask)  

USE: shell>> python autoSlicerTracto2RegionsWithMask.py


(2.b.5) ModifyHeader.py: used to modify on the fly the parameters *.in file of your configuration set. Any parameter generated through the Slicer3 interface could be modified

USE: (1) shell>> python ModifyHeader.py : display the whole list of parameters without modification
     (2) python ModifyHeader.py <tag of parameter to modify> <value of parameter you want to set>
    e.g. shell>> python ModifyHeader.py totalTracts 300

  
(2.b.6) AnalyzeData.py: used to compute in row min, max, mean values of FA, mode, Trace, axial/radial diffusivity

remark: this script is the only one you can launch from Level0!

USE:  python AnalyzeData.py < measure (FA, mode, trace, diffusivity) weighted by probability = value(0 or 1)> < threshold=value(0.0->1.0) >
  e.g. shell>> python AnalyzeData.py 0 0.1

remark: two files are created: cases.data and stats.data 

format of stats.data: each line is doubled indeed, because the analysis is done for region A to region B and for region B to region A
   <case id> <min FA> <max FA> <mean FA> <min mode> <max mode> <mean mode> <min trace> <max trace> <mean trace> 
   <case id> <min axial diffuse> <max axial diffuse> <mean axial diffuse> <min radial diffuse> <max radial diffuse> <mean radial diffuse>


Contact: Julien de Siebenthal, jdesiebenthal at gmail.com
         Computational Radiology Laboratory
         Harvard Medical School
         Department of Radiology
         Children's Hospital Boston

         http://www.crl.med.harvard.edu
         

