[Brains-users] New scripts::Performing the Montreal PET method in brains2

[Greg Harris]

This announcement summarizes our most recent of several projects
to perform the Montreal PET method entirely within brains2.

We now have two script files in iplTclScripts,
iplWorsleyBackwardsCompatible.tcl and iplWorsleyAnalysis.tcl.
The difference between them is that WorsleyBackwardsCompatible
is for extending an existing analysis generated by worsley or NewWorsley
in the Iowa Brain Imaging Lab, while WorsleyAnalysis is for new studies.

Both use driver files as have always been generated by the wors.sh.maker
script generator.

In the course of developing this implementation of Montreal PET analysis
for brains2 users, we created several b2 commands to perform steps of 
this work:

    b2 convert talairach-parameters to montreal-transform
    b2 histogram-equalize image
    b2 extrude-acquisition-plane-clipping image
    b2 stat images
    b2 pooled-stddev-conversion

Perhaps only our general-purpose statistics-generating "swiss army 
knife" deserves mention here:
    b2 stat images [imageList] <supplied-masks= maskList>  <requests= 
keywordList> <data-type= type>
The mask list allows your statistical map images to draw from an 
individualized
subset of the list of images according to corresponding mask membership, 
respectively.
Requests are our way of programming in this case a basic statistical 
engine so it can produce
any or all of:  Minimum, Maximum, Median, Range, Cardinality, Mean, 
Variance,
StandardDeviation, PairedDifferenceT, PairedDifferenceTProbability, 
Skewness, Kurtosis.

In the present version, we compute a pointwise paired difference T and 
P, and then
a factor image to convert the PairedDifferenceT to a 
pooled-stddev-corrected T according
to the Montreal/Worsley standard.

= = = APPENDIX = = =
Usage   b2 convert talairach-parameters to montreal-transform  
[talairach-parameters]

Description     Creates the transform for converting an image to
             a Montreal-style image.  For use in stringing together 
transforms
             with 'b2 compose transforms' and then saving the boxed image
             in '.raw' format.

[talairach-parameters]

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.

= = = APPENDIX = = =
Usage   b2 histogram-equalize image [imageID] <data-type= type>

Description     This command generates a histogram-equalized image.
             It is computed in terms of Unsigned-16Bit voxels,
              and stored in the given datatype.

[imageID]       The (montreal-transformed) image to equalize the levels of.

<data-type= >   Specifies the storage type for the resulting image.
             The default is unsigned-8bit. Valid types are:
                     signed-8bit
                     unsigned-8bit
                     signed-16bit
                     unsigned-16bit
                     signed-32bit
                     unsigned-32bit
                     signed-64bit
                     unsigned-64bit
                     float-single
                     float-double

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.

= = = APPENDIX = = =
Usage   b2 extrude-acquisition-plane-clipping image [imageID] 
<data-type= type>

Description     This command generates a resampled image for which the 
legacy
             'PET chimney' is for some reason called for.  It is 
computed in terms of
             Float-single voxels, and stored in the given datatype.
             CAVEAT:  You MUST give an image that has a transform set.  
A typical
             transform chain would be the montreal boxing transform 
composed with
             the PET-to-MR-ACPC registration transform.
             This method is part of a piecewise, transparent replacement 
script for
             'b2 resample worsley-PET ... brains-interp= True'

[imageID]       The filtered PET image WITH a transform chain set.

<data-type= >   Specifies the storage type for the resulting image.
             The default is Float-single. Valid types are:
                     signed-8bit
                     unsigned-8bit
                     signed-16bit
                     unsigned-16bit
                     signed-32bit
                     unsigned-32bit
                     signed-64bit
                     unsigned-64bit
                     float-single
                     float-double

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.

= = = APPENDIX = = =
Usage   b2 stat images [imageList] <supplied-masks= maskList>  
<requests= keywordList> <data-type= type>

Description     This command generates pointwise statistics,
             possibly clipped to optional corresponding masks,
             and returns a whole image for each request that you name.
             This is done on a voxel by voxel basis.

[imageList]     A list of images used for computing voxel-wise statistics.
             They must all be the same dims and res. The length of the 
list must be
             greater than 1 and less than or equal to 256

   Note!  A simple and correct way to compute an imageList is
       [list $imageVar1 $imageVar2 ...]
<supplied-masks= maskList>      A list of masks used for computing 
voxel-wise statistics.
             They must all be the same dims and res. The length of the 
list must be
             the same as the length of the imageList.

   Note!  A simple and correct way to compute a maskList is
       [list $maskVar1 $maskVar2 ...]
<requests= keywordList> A list chosen from the following:
                  Minimum
                  Maximum
                  Median
                  Range
                  Cardinality
                  Mean
                  Variance
                  StandardDeviation
                  PairedDifferenceT
                  PairedDifferenceTProbability
                  Skewness
                  Kurtosis

   Note!  A simple and correct way to compute a keywordList is
       [list Mean Median ...]
<data-type= >   Specifies the storage type for the resulting
             maximum image. Valid types are:
                  signed-8bit
                  unsigned-8bit
                  signed-16bit
                  unsigned-16bit
                  signed-32bit
                  unsigned-32bit
                  signed-64bit
                  unsigned-64bit
                  float-single
                  float-double

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.

= = = APPENDIX = = =
Usage   b2 pooled-stddev-conversion [variance-diff-image] 
[cardinality-image] <requests= keywordList> <data-type= type>

Description     This command generates the PooledSbarSquared for use by
             'b2 autocorrelation-lambda-resels', and at your option, 
generates an
             image to multiply a pointwise-T by to get the 
Worsley/Montreal T image.

[variance-diff-image]   A variance image produced by 'b2 stat images'.
             The images in the sample must all have been differences of
             PET images co-registered to Montreal space.

[cardinality-image]     A number of supplied differences image that can be
             produced by 'b2 sum masks'.

<requests= keywordList> A list chosen from the following:
                  PooledStandardDeviationFactor
                  PooledSbarSquared

   Note!  A simple and correct way to compute a keywordList is
       [list PooledSbarSquared PooledStandardDeviationFactor]
<data-type= >   Specifies the storage type for the resulting
             maximum image. Valid types are:
                  signed-8bit
                  unsigned-8bit
                  signed-16bit
                  unsigned-16bit
                  signed-32bit
                  unsigned-32bit
                  signed-64bit
                  unsigned-64bit
                  float-single
                  float-double

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.