View source

= Commands =

Are we replacing metric with Cifti Scalar?

TSC: no, processing cifti in nontrivial ways generally has to operate on each structure independently, which is far more convenient as metric files than trying to deal directly with the mappings.

NOTE: -cifti-convert is a HACK to get cifti data into cifti-unaware applications, like matlab.  -cifti-create-dense-timeseries is currently the main way to create cifti from non-cifti standard data files.

JWH: I thought our plan was to use CIFTI Scalar files but restricted to those containing a single surface structure.

TSC: no, all code that deals with dense cifti mappings must have the ability to deal with multi-structure cifti, so nothing can be simpler in code when using single structure cifti.  Dealing with cifti mappings is not something most algorithms should have to do, because it is generally the same each time.  Thus, the code to separate dense mappings into single-structure dedicated file types (metric, label, volume) is in one place, and calculation code uses the considerably simpler dedicated file types.

== caret_command -file-convert ==
	e.g., if you want to convert to/from VTK; wb_import doesn't like some gii, and I haven't decoded why

If there is a file that is failing to convert, let us know.

wb_import is part of the Caret5 source.  It may be possible to move it to the workbench source but may be a lot of work.

== caret_command -metric-information  ==

'''IMPLEMENTED''': USE wb_command -file-information

We should probably have either a "file information" command that works for any file and whose output is file dependent.    An alternative is a "map information" command that works for any map file (is selectable as an overlay).  For files that are mapped with a palette, the output should be very similar to the existing command since all of these files make descriptive statistics available.  For files mapped with a label table, we may want to output the map indices and names and optionally the contents of the label table (keys/names).

<pre>

 % caret_command -metric-information
   METRIC FILE INFORMATION
      caret_command -metric-information  
         <metric-file-name>
         
         Display Information about a metric file's contents.

 % caret_command -metric-information composite.func.gii 
 Filename: composite.func.gii 
 Number of Nodes: 71723 
 Number of Columns: 3
 Column      Minimum      Maximum           Mean     Sample Dev     % Positive     % Negative   Column Name
      1     -685.000      873.000         29.632        154.699         15.189          7.355   Attn shifts, case 1582.R, (Corbetta et al., 1998)
      2       -6.548       10.717          0.241          1.568         13.489          7.942   Attention shifts, pop avg (Corbetta et al., 1998)
      3      -13.215        4.059         -1.511          2.039         20.430         79.570   letter decision task - Gold & Buckner 2002

</pre>
 
TSC: I think having one command work on all file types could be fine, since it doesn't output a file.

DLD: Having it work on surfaces, metric, etc. would be nice.  I don't think we have anything like this for borders/foci, but this also would be nice (# borders/foci; list of border/foci names).  I like here how the you can extract certain info; grep; cut -f2 -d:; etc.  It might be nice to more clearly delimit the columns, but I don't find myself extracting this data very often.  I'm usually just i) making sure I have the right file; ii) making sure it has the right number of columns and column names; and iii) making sure the values look sane.

== caret_command -show-scene ==

There is a show scene in wb_command.  We should compare output to see if any needed functionality is missing.

<pre>
 % caret_command -show-scene
   SHOW SCENE
      caret_command -show-scene  
         <spec-file>
         <scene-file>
         <scene-name-or-number>
         [-image-file  image-file-name  images-per-row] 
         
         Render an image of a scene into an image file.
         Note: the scene numbers start at one.
         
         If the "scene-name-or-number" is numeric it is interpreted
         to be the index of the scene (1..N) in the scene file.  
         Otherwise, it is interpreted to be the name of the scene.
         
         If the "-image-file" option is specified, the images of
         the main and viewing windows will be placed into an image
         file.  "images-per-row" specifies how the images (if there
         are viewing windows displayed in the scene) will be layed
         out.



 % wb_command -show-scene

 OFFSCREEN RENDERING OF SCENE TO AN IMAGE FILE
      <scene-file>
      <scene-name-or-number>
      <image-file-name>
      <image-width>
      <image-height>

      Render content of browser windows displayed in a scene into image
      file(s).  The image file name should be similar to "capture.png".  If
      there is only one image to render, the image name will not change.  If
      there is more than one image to render, an index will be inserted into
      the image name: "capture_01.png", "capture_02.png" etc.

      The image format is determined by the image file extension.
      Image formats available on this sytem are:
      bmp
      ico
      jpeg
      jpg
      png
      ppm
      tif
      tiff
      xbm
      xpm
      Note: Available image formats may vary by operating system.

      Descriptions of parameters and options:

      <scene-file> - scene file
      <scene-name-or-number> - name or number (starting at one) of the scene in
         the scene file
      <image-file-name> - output image file name
      <image-width> - width of output image(s)
      <image-height> - height of output image(s)
</pre>

== caret_command -surface-border-projection ==

Note that in Workbench, there are only border projection files; there are no border files.  However, each border contains two coordinates: (1) a stereotaxic coordinate which is equivalent to a unprojected border as found in a Caret5 border file and (2) a projected coordinate that may be either barycentric (projected to a relative location within a triangle) or a van essen projection (projected to an edge).  The stereotaxic coordinate should always be valid while the projected coordinate may or may not be valid.
A projection algorithm is in Workbench and can be used here.

<pre>
% caret_command -surface-border-projection
   SURFACE BORDER PROJECTION
      caret_command -surface-border-projection  
         <coordinate-file-name>
         <topology-file-name>
         <input-border-file>
         <output-border-projection-file>
         
         Project the borders using the specified surface.
         
         Run "caret_command -help-global-options"
            for parameters available to all commands.

</pre>

== caret_command -surface-border-unprojection ==

An unprojection algorithm is in Workbench and can be used here.

<pre>

% caret_command -surface-border-unprojection
   SURFACE BORDER UNPROJECTION
      caret_command -surface-border-unprojection  
         <coordinate-file-name>
         <topology-file-name>
         <input-border-projection-file>
         <output-border-file>
         
         Unproject the borders using the specified surface.
         
         Run "caret_command -help-global-options"
            for parameters available to all commands.

</pre>

== caret_command -surface-border-draw-around-roi ==

Probably can incorporate the algorithm from Caret5.

<pre>

% caret_command -surface-border-draw-around-roi
   SURFACE BORDER DRAW AROUND ROI
      caret_command -surface-border-draw-around-roi  
         <coordinate-file-name>
         <topology-file-name>
         <region-of-interest-file-name>
         <input-border-projection-file-name>
         <output-border-projection-file-name>
         <border-name>
         [-output-all-borders]
         [-start-near-focus  foci-projection-file-name  focus-name]
         
         Draw a border around a surface region of interest.  
         
         By default, if there is more than one disjoint region in
         the ROI, only the border with the greatest number of links
         is output. 
         
         If the "-output-all-borders" option is specified, the
          borders for ALL disjoint regions are output.
         
         If the "-start-near-focus" option is specified, all 
         borders are set up so that the first link in the border is
         the link nearest the focus.  This option is only applied if
         "-output-all-borders" is NOT specified.
         
         Note: The input border projection file does not need to exist.
</pre>

== caret_command -surface-cell-projection  == 

Cells are not in Workbench but are the same as foci.

== caret_command -surface-cell-unprojection  == 

Cells are not in Workbench but are the same as foci.

== caret_command -surface-foci-projection   ==

We do not have foci files in Workbench, just foci projection. See not in border projection command.

Foci projection is in Workbench.

<pre>

% caret_command -surface-foci-projection
   SURFACE FOCI PROJECTION
      caret_command -surface-foci-projection  
         <coordinate-file-name>
         <topology-file-name>
         <input-foci-file-name>
         <output-foci-projection-file-name>
         [-project-onto-surface  onto-surface-above-distance]
         
         Project the foci to the surface and save into the foci
         projection file.
         
         "-project-onto-surface" is used to project the foci so that
         they are a specified distance above the surface.
</pre>

== caret_command -surface-foci-unprojection  == 

Foci unprojection is in Workbench.

<pre>

% caret_command -surface-foci-unprojection
   SURFACE FOCI UNPROJECTION
      caret_command -surface-foci-unprojection  
         <coordinate-file-name>
         <topology-file-name>
         <input-foci-projection-file-name>
         <output-foci-file-name>
         
         Unproject the foci projections to the surface and save
         the foci file.

</pre>

== caret_command -surface-folding-measures ==

Probably can copy from Caret5 but will need some updating.

<pre>

% caret_command -surface-folding-measures
   SURFACE FOLDING MEASURES
      caret_command -surface-folding-measures  
         <coordinate-file-name>
         <topology-file-name>
         <output-text-report-file-name>
         [-roi  region-of-interest-file-name]
         [-metric  output-metric-measurements-file-name]
         
         Generate a report of folding measurements on a surface.
         
         If an ROI is provided, the folding measurements are 
         limited to that region of the surface.
         
         If a metric measurements file is added, it will be output
         and contain folding measurements at each node.


Node Selection:  All Nodes

Surface: FIDUCIAL Human.colin.Cerebral.R.FIDUCIAL.SPM2.03-12.71723.coord

Topology: CLOSED Human.colin.Cerebral.R.CLOSED.71723.topo


71558 of 71723 nodes in region of interest

Total Surface Area: 110607.9
Region of Interest Surface Area: 110607.8
Region of Interest Center of Gravity: 32.0273 -18.2753 17.5317
Region Mean Distance Between Nodes: 1.30117

Intrinsic Curvature Index (ICI)                     0.01244
Negative Intrinsic Curvature Index (NICI)          -0.01081
Gaussian L2 Norm (GLN)                              0.00458
Absolute Intrinsic Curvature Index (AICI)           0.02325
Mean Curvature Index (MCI)                          0.07362
Negative Mean Curvature Index (NMCI)               -0.06083
Mean L2 Form (MLN)                                  0.03025
Absolute Mean Curvature Index (AMCI)                0.13444
Folding Index (FI)                                  0.08535
Curvedness Index (CI)                               0.20367
Shape Index (SI)                                    0.92224
Area Fraction of ICI (FICI)                         0.46345
Area Fraction Negative ICI (FICI)                   0.53655
Area Fraction of MCI (FMCI)                         0.58546
Area Fraction of Neg MCI (FNMCI)                    0.41454
SH2SH                                               0.22501
SK2SK                                               0.19713

</pre>

== caret_command -surface-identify-sulci ==
	This is a very large, complex operation.

TSC: this is mainly needed for depth, which we are going to reengineer anyway

<pre>
% caret_command -surface-identify-sulci   SURFACE IDENTIFY SULCI
      caret_command -surface-identify-sulci  
         <spec-file-name>
         <structure>
         <segmentation-volume-file-name>
         <closed-topology-file-name>
         <raw-coordinate-file-name>
         <fiducial-coordinate-file-name>
         <volume-write-type>
         
         Identify Sulci with shape and paint.
         
         Create a surface shape file containing depth and curvature measurements,
         a paint file identifying the sulci, and an area color file.  If there
         is no raw coordinate file, specify fiducial coordinate file instead.
         
         NOTE: This command MUST be run in the directory containing the files.
         
         structure  Specifies the brain structure. 
            Acceptable values are RIGHT or LEFT 
          
         write-volume-type   Type of volume files to write. 
            Specifies the type of the volume files that will be written 
             during the segmentation process.  Valid values are: 
                AFNI 
                NIFTI   
                NIFTI_GZIP (RECOMMENDED!!!!) 
                SPM 
                WUNIL </pre>

== caret_command -surface-region-of-interest-selection ==

This is a big command but may be able to use "wb_command -metric-math"

TSC: Selection logic and thresholding can be done with -metric-math and related, what do people think about separate commands to put things like surface coordinates, distance from coordinate, etc into metric files, and then use -metric-math to do the combination?  I'm not sure about "boundary-only", that could be another command, if it is needed...

<pre>
% caret_command -surface-region-of-interest-selection
   SURFACE REGION OF INTEREST SELECTION
      caret_command -surface-region-of-interest-selection  
         <input-coord-file-name>  
         <input-topology-file-name>  
         <input-region-of-interest-file-name.roi>  
         <output-region-of-interest-file-name.roi>  
         [-all-nodes] 
         [-border-projection 
            border-projection-file-name 
            border-projection-name 
            surface-view 
            dimension 
            z-minimum 
            SEL-TYPE] 
         [-boundary-only] 
         [-dilate  iterations] 
         [-dilate-paint  paint-file-name column  paint-name  iterations]
         [-edges   SEL-TYPE] 
         [-erode   iterations] 
         [-limit-x-lateral   x-value] 
         [-limit-x-medial    x-value] 
         [-limit-x-min       x-value] 
         [-limit-x-max       x-value] 
         [-limit-y-min       y-value] 
         [-limit-y-max       y-value] 
         [-limit-z-min       z-value] 
         [-limit-z-max       z-value] 
         [-limit-x-min-focus  fociProjectionFile  focusName] 
         [-limit-x-max-focus  fociProjectionFile  focusName] 
         [-limit-y-min-focus  fociProjectionFile  focusName] 
         [-limit-y-max-focus  fociProjectionFile  focusName] 
         [-limit-z-min-focus  fociProjectionFile  focusName] 
         [-limit-z-max-focus  fociProjectionFile  focusName] 
         [-metric  metric-file-name  column  min  max SEL-TYPE]
         [-invert-selection] 
         [-latlon file-name column min-lat max-lat min-lon max-lon SEL_TYPE]
         [-paint  paint-file-name  column  paint-name SEL-TYPE]
         [-remove-islands] 
         [-shape  shape-file-name  column  min max SEL-TYPE]
         
         The input region of interest file does not need to exist.
         
         Perform a surface node region of interest selection
         
         SEL-TYPE is one of 
            NORMAL    Applies selection to all nodes.
            AND       And (intersection) new selection with the
                      existing selection.
            OR        Or (union) new selection with the
                      existing selection.
            ANDNOT    And the inverse of the new selection with
                      existing selection.
         
         OPERATIONS
         "-all-nodes" will place all connected nodes into the ROI.
         
         "-border-projection" will place nodes that are inside of
            the border into the ROI.  When "dimension" is 3D, nodes
            within the border and whose screen Z-coordinate is greater
            than "z-minimum" are assigned to the ROI.  In most cases,
            a "z-minimum" of zero is sufficient.  If areas within the
            border are not assigned, load the surface, click the mouse
            on the unassigned nodes to find the value needed for 
            "z-minimum" and create the ROI again.
         
               "surface-view" is one of these single characters:
                  A - Anterior
                  D - Dorsal
                  L - Lateral
                  M - Medial
                  P - Posterior
                  R - Reset (default view)
                  V - Ventral
               "dimension" is one of:
                  2D 
                  3D 
         
         "-boundary-only" will retain only those nodes that have
            at least one neighbor that is NOT in the ROI (interior
            nodes are removed).
         
         "-dilate" will dilate the ROI for the specified iterations.
         
         "-dilate-paint" will dilate the ROI but only nodes that have
            the specified paint are added to the ROI.
         
         "-erode" will erode the ROI for the specified iterations.
         
         "-invert-selection" will invert the node selection.
         
         "-latlon" will add nodes to the ROI if the nodes lat/long values
            are within the specified range of the column.
         
         "-metric" will add nodes to the ROI if the nodes metric value
            is within the specified range of the column.
         
         "-paint" will add nodes to the ROI if the nodes paint name
            is the specified paint name for the column.
         
         "-remove-islands" will retain only largest set of 
            connected nodes in the ROI.
         
         "-shape" will add nodes to the ROI if the nodes shape value
            is within the specified range of the column.
         
         NOTES:
             The optional parameters (those enclosed in square
             brackets) are performed in the order they are
             listed on the command line.
         
             "column" is either the number of the column, which
             starts at one, or the name of the column.  If a
             a name contains spaces, it must be enclosed in double 
             quotes.  Name has priority over number.
         
             When finding nodes enclosed inside a border projection
             use a dimension of 2D for flat surfaces.  When the 
             dimension is 2D, the surface view is ignored.
             
             For three dimensional surfaces (fiducial, inflated,
             spherical, etc.), set the dimension to 3D.  When determining 
             nodes within a border projection on a 3D surface, the 
             surface-view is applied and those nodes with a Z-coordinate
             that is greater than Z-coordinate of the center of gravity
             and within the border projection are added to the region
             of interest.
         
             When limits are specified with foci, the last focus 
             with "focus-name" found in the file is used.


</pre>

== caret_command -surface-to-segmentation-volume ==
This is possible with wb_command -create-signed-distance-volume, followed by -volume-math 'x<0', could be provided as a separate command

<pre>
% caret_command -surface-to-segmentation-volume
   SURFACE TO SEGMENTATION VOLUME
      caret_command -surface-to-segmentation-volume  
         <input-coordinate-file-name>
         <input-topology-file-name>
         <output-volume-file-name>
         [structure-name]
         
         Intersect a surface with a volume and create a segmentation
         volume.
         
         The coordinate file must have its structure set to 
         one of "left" or "right" or else the command will
         terminate with an error message.  The structure may 
         be specified with the optional "structure-name"
         parameter.
         
         The output volume file must exist and it must be in the 
         same stereotaxic space as the surface.  A volume file may
         be created by using the "-volume-create" command.
         
         "structure-name" is optional and must be one of 
         "left" or "right".
</pre>

== caret_command -surface-topology-disconnect-nodes ==

Probably can copy from Caret5 but will need some updating.
 
<pre>

caret_command -surface-topology-disconnect-nodes
   SURFACE TOPOLOGY DISCONNECT NODES
      caret_command -surface-topology-disconnect-nodes  
         <input-topology-file-name>
         <output-topology-file-name>
         <region-of-interest-file-name>
         
         Disconnect all nodes that are in the region of interest.
</pre>

== caret_command -volume-create ==

IMPLEMENTED: wb_command -volume-create

Is there a desire to create with dimensions, spacing, origin?  Name of stereotaxic space?  Or both?

TSC: it should be quite easy - I would opt not to provide any standard spaces, since it is much more likely you will already have a reference volume for those.

There were two volume create commands in Caret5.

<pre>
% caret_command -volume-create
   VOLUME CREATE
      caret_command -volume-create  
         <x-dimension>
         <y-dimension>
         <z-dimension>
         <output-volume-file-name-and-label>
         
         Create a volume using the specified dimensions.


% caret_command -volume-create-in-stereotaxic-space
   VOLUME CREATE IN STEREOTAXIC SPACE
      caret_command -volume-create-in-stereotaxic-space  
         <STEREOTAXIC-SPACE>
         <output-volume-file-name-and-label>
         
         Create a volume in the specified stereotaxic space.
         Valid spaces are:
            AFNI
            FLIRT
            FLIRT-222
            MACAQUE-F6
            MACAQUE-F99
            MRITOTAL
            SPM
            SPM95
            SPM96
            SPM99
            SPM2
            SPM5
            T88
            711-2B
            711-2B-111
            711-2B-222
            711-2B-333
            711-2C
            711-2C-111
            711-2C-222
            711-2C-333
            711-2O
            711-2O-111
            711-2O-222
            711-2O-333
            711-2Y
            711-2Y-111
            711-2Y-222
            711-2Y-333
</pre>

== caret_command -volume-set-origin ==

IMPLEMENTED: wb_command -volume-set-space

Create a command that allows user to update a volume file's attributes (origin/spacing).

<pre>
% caret_command -volume-set-origin
   VOLUME SET ORIGIN
      caret_command -volume-set-origin  
         <input-volume-file-name>
         <output-volume-file-name>
         <x-axis-origin-at-center-of-first-voxel>
         <y-axis-origin-at-center-of-first-voxel>
         <z-axis-origin-at-center-of-first-voxel>
         
         Set the origin for the volume file.
</pre>

== caret_command -volume-set-spacing ==

IMPLEMENTED: wb_command -volume-set-space

See above.

TSC: these should be rolled into one command that just sets the entire sform

<pre>
% caret_command -volume-set-spacing
   VOLUME SET SPACING
      caret_command -volume-set-spacing  
         <input-volume-file-name>
         <output-volume-file-name>
         <x-axis-spacing>
         <y-axis-spacing>
         <z-axis-spacing>
         
         Set the spacing for the volume file.</pre>

== caret_command -volume-histogram  == 

This should probably be generalized to work with any mappable data file (displayed as overlay) that maps with a palette.

TSC: what would the output be?

JWH: It outputs a histogram as a "text image" as shown below.  The asterisks represent the distribution of the data.  The numbers in the right column are the quantity.  Numbers along the bottom are the voxel data values (the data ranges -81.9866 to 300.289).

TSC: do we really need this?  The histogram in the gui seems better to me (granted, it is a few more clicks to get there, but when do you want a text histogram while not visualizing the file?).

<pre>

% caret_command -volume-histogram Glasser_PilotIII1.nii.gz 

              ***                                                 353863.0
              ***                                                 345016.4
              ***                                                 336169.8
              ***                                                 327323.3
              ***                                                 318476.7
              ***                                                 309630.1
              ***                                                 300783.6
              ***                                                 291937.0
              ***                                                 283090.4
              ***                                                 274243.8
              ***                                                 265397.2
              ***                                                 256550.7
              ***                                                 247704.1
              ***                                                 238857.5
              ***                                                 230011.0
              ***                                                 221164.4
              ***             *                                   212317.8
              ***             **                                  203471.2
              ***            ***                                  194624.7
              ***            ***                                  185778.1
              ***            ****                                 176931.5
              ***            ****                                 168084.9
              ***           *****                                 159238.4
              ***           ******                                150391.8
              ***           ******      *                         141545.2
              ****         *******      *                         132698.6
              ****         ********    ***                        123852.1
              ****        *********    ***                        115005.5
              *****      **********   ****                        106158.9
              **********************  ****                         97312.3
              *****************************                        88465.8
              *****************************                        79619.2
              *****************************                        70772.6
              *****************************                        61926.0
              ******************************                       53079.5
              ******************************                       44232.9
              *******************************                      35386.3
              ********************************                     26539.7
              *************************************                17693.2
              ****************************************              8846.6
 --------------000000000000000000111111111111111112222222222222222
 8776554432211-00122334456677899001223345566788990112234455677889
 2604826048260428406273951739517395173951739517395173951738406284

 Maximum Y-Value: 2067064.0
 Max Y-Value Displayed: 353863.0

</pre>

== caret_command -volume-information   ==

'''IMPLEMENTED''': USE wb_command -file-information

See  metric-information near top.

<pre>
% caret_command -volume-information Glasser_PilotIII1.nii.gz 
Volume File: Glasser_PilotIII1.nii.gz
   dimensions: 182, 218, 182, 1
   spacing: 1, 1, 1
   origin (center of first voxel): -91, -126, -72
   orientation: Left to Right, Posterior to Anterior, Inferior to Superior
   label: Glasser_PilotIII1.nii.gz
   voxel range: -81.9866, 300.289
</pre>

== caret_command -volume-information-nifti  == 

'''IMPLEMENTED''': USE wb_command -file-information

TSC: also of note is -nifti-information, which can print the header in a fairly raw form

See  metric-information near top.

<pre>
% caret_command -volume-information Glasser_PilotIII1.nii.gz 
Volume File: Glasser_PilotIII1.nii.gz
   dimensions: 182, 218, 182, 1
   spacing: 1, 1, 1
   origin (center of first voxel): -91, -126, -72
   orientation: Left to Right, Posterior to Anterior, Inferior to Superior
   label: Glasser_PilotIII1.nii.gz
   voxel range: -81.9866, 300.289
noodle 60 % caret_command -volume-information-nifti Glasser_PilotIII1.nii.gz
    sizeof_hdr: 348
     data_type: 
       db_name: 
       extents: 0
 session_error: 0
       regular: r
      dim_info: 0
           dim: 3 182 218 182 1 1 1 1 
     intent_p1: 0.000
     intent_p2: 0.000
     intent_p3: 0.000
   intent_code: 0
      datatype: 16
        bitpix: 32
   slice_start: 0
        pixdim: -1.000 1.000 1.000 1.000 1.000 0.000 0.000 0.000 
    vox_offset: 352.000
     scl_slope: 1.000
     scl_inter: 0.000
     slice_end: 0
    slice_code: 0
    xyzt_units: 10
       cal_max: 0.000
       cal_min: 0.000
slice_duration: 0.000
       toffset: 0.000
         glmax: 0
         glmin: 0
   description: FSL4.0
      aux_file: 
    qform_code: 4
    sform_code: 4
     quatern_b: 0.000
     quatern_c: 1.000
     quatern_d: 0.000
     qoffset_x: 90.000
     qoffset_y: -126.000
     qoffset_z: -72.000
        srow_x: -1.000 0.000 0.000 90.000 
        srow_y: 0.000 1.000 0.000 -126.000 
        srow_z: 0.000 0.000 1.000 -72.000 
   intent_name: 
         magic: n+1

Intent Name:      NIFTI_INTENT_NONE
Intent Parameters:None

   First Voxel XYZ (method 1): 0.000, 0.000, 0.000
   Spacing: 1.000, 1.000, 1.000

QFORM: NIFTI_XFORM_MNI_152
         -1.000       0.000       0.000       0.000
          0.000       1.000       0.000       0.000
          0.000       0.000       1.000       0.000
          0.000       0.000       0.000       1.000
   Orientation: Right to Left, Posterior to Anterior, Inferior to Superior
   First Voxel XYZ (Method 2): 90.000, -126.000, -72.000
   Spacing: -1.000, 1.000, -1.000

SFORM: NIFTI_XFORM_MNI_152
         -1.000       0.000       0.000      90.000
          0.000       1.000       0.000    -126.000
          0.000       0.000       1.000     -72.000
          0.000       0.000       0.000       1.000
   Orientation: Right to Left, Posterior to Anterior, Inferior to Superior
   First Voxel XYZ (Method 3): 90.000, -126.000, -72.000
   Spacing: -1.000, 1.000, 1.000

Data Type: NIFTI_TYPE_FLOAT32

Space Units: NIFTI_UNITS_MM
Time Units: NIFTI_UNITS_SEC


</pre>

== caret_command -metric-composite   ==

Use wb_command -metric-merge (similar exist for cifti, volume, and label).

<pre>
% caret_command -metric-composite
   METRIC FILE COMPOSITE ALL COLUMNS
      caret_command -metric-composite  
         <output-metric-file>  
         <input-metric-files...>
         
         Concatenate all columns from the input metric files and place
         them into the output metric file

</pre>

== caret_command -metric-composite-identified-columns  == 

Use wb_command -metric-merge (similar exist for cifti, volume, and label).

<pre>
% caret_command -metric-composite-identified-columns
   METRIC COMPOSITE IDENTIFIED COLUMNS
      caret_command -metric-composite-identified-columns  
         <output-metric-file-name> 
         [input-metric-file-1  file-1-column] 
         ...
         [input-metric-file-N  file-2-column]
         
         Composite the selected columns from the input metric
         files and place them into the output metric file.
         
         "column" is either the number of the column, which
         starts at one, or the name of the column.  If a
         a name contains spaces, it must be enclosed in double
         quotes.  Name has priority over number.

</pre>

== caret_command -metric-math-postfix   ==

Use wb_command -metric-math (similar exist for cifti and volume).

<pre>
% caret_command -metric-math-postfix
   METRIC MATH POSTFIX
      caret_command -metric-math-postfix  
         <input-metric-file-name>
         <output-metric-file-name>
         <output-column-name-number>
         <postfix-expression-within-double-quotes>
         
         Perform mathematical operations on a metric file.  The 
         mathematical expression must be in post-fix (reverse 
         polish notation).  See 
            http://en.wikipedia.org/wiki/Reverse_Polish_notation
         
         The postfix expression must be in double quotes.  Otherwise,
         operators, such as "*" will match all files in the 
         current directory.
         
         A metric column is identified by a sequence of characters
         the are immediately proceeded and immediately followed by
         an at-sign (@).   
         
         These characters are either the name of the metric column or
         the number of the metric column which starts at one.  To use
         a metric column that is in a metric file other than the input
         metric file, start with an at-sign, followed by the name of
         the metric file, followed by a colon (:), 
         followed by the identifier of the metric column, and lastly,
         an at-sign.
         
         Spaces are allowed in file names or column identifiers:
            Example "@test file::subject 2@"
         
         Examples (for the column named "activation" located in:
         the file named "experiment.metric"
            @activation@
            @experiment.metric::activation@
         
         If the output metric column is a name and it does not exist
         it will be created.
         
         Binary operators supported are:
            +     addition
            -     subtraction
            *     multiplication
            /     division
            ^     exponention
            max2   maximum-value
            min2   minimum-value
         
         Unary operations supported are:
            abs    absolute-value
            exp    exponential function
            flipsign  flip the sign
            log    natural log
            log2   base 2 logarithm
            log10  base 10 logarithm
            sqrt   square root
         
         Predefined values from each nodes metric values
            nodeavg  Average value at each node
            nodemax  Maximum value at each node  
            nodemin  Minimum value at each node  
            nodesum  Sum of values at each node  
         
         Example:   "5 1 2 + 4 * + 3 -" 
                   Infix => ((1 + 2) * 4 + 5 - 3)
            evaluates to 14.
         Example:   "2 3 * 2 3 + min2" 
                   Infix => min2(2 * 3, 2 + 3)
            evaluates to 5.
         Example:   "@one@                      @two@ add"  
            adds the columns named "one" and "two".         
</pre>

== caret_command -metric-set-column-name   ==

Use wb_command -set-map-names.

<pre>
% caret_command -metric-set-column-name
   METRIC SET COLUMN NAME
      caret_command -metric-set-column-name  
         <metric-file-name>
         [column  new-name]
         
         Rename columns in a metric file.
         
         "column" is either the number of the column, which
         starts at one, or the name of the column.  If a
         a name contains spaces, it must be enclosed in double
         quotes.  Name has priority over number.
</pre>

== caret_command -metric-set-column-to-scalar   ==

Use wb_command -metric-math (similar exist for cifti and volume).

<pre>
% caret_command -metric-set-column-to-scalar
   METRIC SET COLUMN TO SCALAR
      caret_command -metric-set-column-to-scalar  
         <metric-file-name>
         [column  scalar-value]
         
         Set columns to a scalar value in a metric file.
         
         "column" is either the number of the column, which
         starts at one, or the name of the column.  If a
         a name contains spaces, it must be enclosed in double
         quotes.  Name has priority over number.  If a name is
         used for a column and the column does not exist it will
         be created.</pre>

= Statistics Commands =

Will this be a new command line program "wb_stats" or will the commands be added to "wb_command"?

All statistics command will operate on CIFTI Scalar files containing surface-based data.  Will there be one structure per file or multiple structures (left/right)? Is there ANY POSSIBILITY that these statistic command will need to operate on CIFTI Scalar files containing volume data or volume files?

== Inferential Linear Statistics Commands ==

For the linear statistics commands we could reformat and solve using a General Linear Model [[Caret:Documentation:StatisticsGLM]] .  However, it will be simpler just to use the standard algorithm for each statistical test (and probably best if reviewers of papers ask).  [[Caret:Documentation:Statistics]]

If possible, parallel processing with OpenMP should be used.  Since these commands often operate on 'vectors' of data, GPU processing (OpenCL) may be possible but this decision should be deferred.

All of these commands are in either Caret5 or Caret6 so implementation should be fairly straightforward and the previous implementations can be used to validate operation of the new commands.

=== caret6_stats -inferential-anova-one-way ===

<pre>

]$ caret6_stats -inferential-anova-one-way

ANOVA One-Way
   -inferential-anova-one-way
   <-data-file   group-name   input-file-name>
   <-output-statistic-file output-statistic-file-name>
   [-add-f-statistic-p-value]
   [-add-f-statistic-q-value]
   [-add-f-statistic-numerator-degrees-of-freedom]
   [-add-f-statistic-denominator-degrees-of-freedom]
   [-output-randomized-file  output-randomized-file-name]
   [-randomized-iterations  number-of-iterations]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   [-random-seed  random-seed-value]
   
   Perform a One-Way Analysis of Variance on the means of
   data groups.
   
   There must be at least two groups of data.  The data for
   a group may be in more than one file.  The "group-name"
   associates a data file with a group.
   
   The default name for the column in the output file 
   containing the F-Statistic is F-Statistic
   
   If the "-output-randomized-file" option is specified,  a
   file is written that includes "number-of-iterations" 
   data columns containing F-Statistics for shuffled input 
   data columns.  This file is intended for use with the 
   significance determination algorithm.
   
   P-Value is the significance computed from the F-Statistic
   and the degrees of freedom.  
   
   Q-Value is (1.0 - P) and may be useful for thresholding
   in Caret.
   
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP
   
   The random seed sets the seed of the random number 
   generator which affects the sequence of numbers that 
   are generated.  If a command is run with with 
   identical inputs and the command uses the random number 
   generator, the results will be identical only if the 
   random-seed-value is set using the same value.  The seed 
   used should be a large integer value.
</pre>

=== caret6_stats -inferential-anova-one-way-coordinate-difference ===

<pre>

$ caret6_stats -inferential-anova-one-way-coordinate-difference

ANOVA One-Way Coordinate Difference
   -inferential-anova-one-way-coordinate-difference
   <-data-file   group-name   input-coordinate-file-name>
   <-output-statistic-file output-statistic-file-name>
   [-add-f-statistic-p-value]
   [-add-f-statistic-q-value]
   [-add-f-statistic-numerator-degrees-of-freedom]
   [-add-f-statistic-denominator-degrees-of-freedom]
   [-output-randomized-file  output-randomized-file-name]
   [-randomized-iterations  number-of-iterations]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   [-random-seed  random-seed-value]
   
   Perform a One-Way Analysis of Variance on the Coordinate
   Differences.
   
   There must be at least two groups of data.  
   
   The default name for the column in the output file 
   containing the F-Statistic is F-Statistic
   
   If the "-output-randomized-file" option is specified,  a
   file is written that includes "number-of-iterations" 
   data columns containing F-Statistics for shuffled input 
   coordinate differences.  This file is intended for use 
   with a significance determination algorithm.
   
   P-Value is the significance computed from the F-Statistic
   and the degrees of freedom.  
   
   Q-Value is (1.0 - P) and may be useful for thresholding
   in Caret.
   
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP
   
   The random seed sets the seed of the random number 
   generator which affects the sequence of numbers that 
   are generated.  If a command is run with with 
   identical inputs and the command uses the random number 
   generator, the results will be identical only if the 
   random-seed-value is set using the same value.  The seed 
   used should be a large integer value.
</pre>

=== caret6_stats -inferential-interhemispheric ===

<pre>

$ caret6_stats -inferential-interhemispheric

Interhemispheric
   -inferential-interhemispheric
   <-data-file-left-A   left-group-A-input-file-name>
   <-data-file-left-B   left-group-B-input-file-name>
   <-data-file-right-A  right-group-A-input-file-name>
   <-data-file-right-B  right-group-B-input-file-name>
   <-output-statistic-file output-statistic-file-name>
   <-pooled  |  -unpooled>
   [-add-t-statistic-p-value]
   [-add-t-statistic-q-value]
   [-add-t-statistic-degrees-of-freedom]
   [-output-randomized-file  output-randomized-file-name]
   [-randomized-iterations-within  number-of-iterations]
   [-randomized-iterations-between  number-of-iterations]
   [-variance-smoothing-coordinate-file  coord-file-name]
   [-variance-smoothing-topology-file  topo-file-name]
   [-variance-smoothing-strength  strength]
   [-variance-smoothing-iterations  iterations]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   [-random-seed  random-seed-value]
   
   Perform a test to identify asymmetry between the left
   and right hemispheres.  A T-Test is performed between
   the left hemisphere files and another T-Test is performed
   between the right hemisphere files.  The output file 
   contains the product of these two T-Test files.
   
   The default name for the column in the output file 
   containing the product of the T-Statistics is "T-Statistic-Product".
   
   If the variances of the data in the two groups are the
   same use "-pooled".  If the variances of the data in
   the two groups are different, use "-unpooled".
   
   If the "-output-randomized-file" option is specified, a
   randomized file for significance testing is created.  
   First, a file is created containing columns that are 
   T-Statistics for randomized combinations of columns from 
   the left hemisphere files.  The number of columns is 
   specified by the "-randomized-iterations-within" option.
   Second, a file is created containing columns that are 
   T-statistics for randomized combinations of columns from 
   the right hemisphere files.  The number of columns is 
   specified by the "-randomized-iterations-within" option.
   Third, a file is created that contains the product of 
   a random selection from the left hemisphere file multiplied
   by a random selection from the right hemisphere file.  The
   number of columns is specified by using the 
   "-randomized-iterations-between" option.
   
   P-Value is the significance computed from the T-Statistic
   and the degrees of freedom.  
   
   Q-Value is (1.0 - P) and may be useful for thresholding
   in Caret.
   
   DOF is the degrees of freedom.
   
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP
   
   The random seed sets the seed of the random number 
   generator which affects the sequence of numbers that 
   are generated.  If a command is run with with 
   identical inputs and the command uses the random number 
   generator, the results will be identical only if the 
   random-seed-value is set using the same value.  The seed 
   used should be a large integer value.
</pre>

=== caret6_stats -inferential-t-test-one-sample ===

<pre>

$ caret6_stats -inferential-t-test-one-sample

T-Test One-Sample
   -inferential-t-test-one-sample
   <-data-file  input-file-name>
   <-output-statistic-file output-statistic-file-name>
   <-hypothesis-mean  value>
   [-add-t-statistic-p-value]
   [-add-t-statistic-q-value]
   [-add-t-statistic-degrees-of-freedom]
   [-output-randomized-file  output-randomized-file-name]
   [-randomized-iterations  number-of-iterations]
   [-variance-smoothing-surface-file  surface-file-name]
   [-variance-smoothing-coordinate-file  coord-file-name]
   [-variance-smoothing-topology-file  topo-file-name]
   [-variance-smoothing-strength  strength]
   [-variance-smoothing-iterations  iterations]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   [-random-seed  random-seed-value]
   
   Perform a One-Sample T-Test testing the means against
   the hypothesis mean.
   
   The input data may be in more than one file.  Just use
   multiple instances of "-data-file" for each file.
   
   The default name for the column in the output file 
   containing the T-Values is T-Statistic
   
   If the "-output-randomized-file" option is specified,  a
   file is written that includes "number-of-iterations" 
   data columns containing T-Statistics for shuffled input 
   data columns (random columns have sign flipped.  This 
   file is intended for use with the significance 
   determination algorithm.
   
   P-Value is the significance computed from the T-Statistic
   and the degrees of freedom.  
   
   Q-Value is (1.0 - P) and may be useful for thresholding
   in Caret.
   
   DOF is the degrees of freedom.
   
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP
   
   The random seed sets the seed of the random number 
   generator which affects the sequence of numbers that 
   are generated.  If a command is run with with 
   identical inputs and the command uses the random number 
   generator, the results will be identical only if the 
   random-seed-value is set using the same value.  The seed 
   used should be a large integer value.

</pre>

=== caret6_stats -inferential-t-test-paired ===

<pre>

$ caret6_stats -inferential-t-test-paired

T-Test Paired
   -inferential-t-test-paired
   <-data-file  group-name  input-file-name>
   <-output-statistic-file output-statistic-file-name>
   [-add-t-statistic-p-value]
   [-add-t-statistic-q-value]
   [-add-t-statistic-degrees-of-freedom]
   [-output-randomized-file  output-randomized-file-name]
   [-randomized-iterations  number-of-iterations]
   [-variance-smoothing-surface-file  surface-file-name]
   [-variance-smoothing-coordinate-file  coord-file-name]
   [-variance-smoothing-topology-file  topo-file-name]
   [-variance-smoothing-strength  strength]
   [-variance-smoothing-iterations  iterations]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   [-random-seed  random-seed-value]
   
   Perform a Paired T-Test.
   
   A paired T-Test determines if measurements on participants
   have changed after some event.  Essentially, the second 
   data group's scores are subtracted from the first data
   group's scores and a one-sample T-Test is performed with
   an hypothesis mean of zero.
   
   There must be exactly two data groups.  Each participant
   must be in both data groups and in the same position in
   the two data groups (subject X must be the i'th metric
   column in both of the data groups).
   
   The input data may be in more than one file.  Just use
   multiple instances of "-data-file" for each file.
   
   The default name for the column in the output file 
   containing the T-Values is T-Statistic
   
   If the "-output-randomized-file" option is specified,  a
   file is written that includes "number-of-iterations" 
   data columns containing T-Statistics for shuffled input 
   data columns (random columns have sign flipped.  This 
   file is intended for use with the significance 
   determination algorithm.
   
   P-Value is the significance computed from the T-Statistic
   and the degrees of freedom.  
   
   Q-Value is (1.0 - P) and may be useful for thresholding
   in Caret.
   
   DOF is the degrees of freedom.
   
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP
   
   The random seed sets the seed of the random number 
   generator which affects the sequence of numbers that 
   are generated.  If a command is run with with 
   identical inputs and the command uses the random number 
   generator, the results will be identical only if the 
   random-seed-value is set using the same value.  The seed 
   used should be a large integer value.


</pre>

=== caret6_stats -inferential-t-test-two-sample ===

<pre>

$ caret6_stats -inferential-t-test-two-sample

T-Test Two-Sample
   -inferential-t-test-two-sample
   <-data-file   group-name   input-file-name>
   <-output-statistic-file output-statistic-file-name>
   <-pooled  |  -unpooled>
   [-add-t-statistic-p-value]
   [-add-t-statistic-q-value]
   [-add-t-statistic-degrees-of-freedom]
   [-output-randomized-file  output-randomized-file-name]
   [-randomized-iterations  number-of-iterations]
   [-variance-smoothing-surface-file  surface-file-name]
   [-variance-smoothing-coordinate-file  coord-file-name]
   [-variance-smoothing-topology-file  topo-file-name]
   [-variance-smoothing-strength  strength]
   [-variance-smoothing-iterations  iterations]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   [-random-seed  random-seed-value]
   
   Perform a Two-Sample T-Test on the means of the two
   data groups.
   
   If the variances of the data in the two groups are the
   same use "-pooled".  If the variances of the data in
   the two groups are different, use "-unpooled".
   
   There must be exactly two groups of data.  The data for
   a group may be in more than one file.  The "group-name"
   associates a data file with a group.
   
   The default name for the column in the output file 
   containing the T-Values is T-Statistic
   
   If the "-output-randomized-file" option is specified,  a
   file is written that includes "number-of-iterations" 
   data columns containing T-Statistics for shuffled input 
   data columns.  This file is intended for use with the 
   significance determination algorithm.
   
   P-Value is the significance computed from the T-Statistic
   and the degrees of freedom.  
   
   Q-Value is (1.0 - P) and may be useful for thresholding
   in Caret.
   
   DOF is the degrees of freedom.
   
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP
   
   The random seed sets the seed of the random number 
   generator which affects the sequence of numbers that 
   are generated.  If a command is run with with 
   identical inputs and the command uses the random number 
   generator, the results will be identical only if the 
   random-seed-value is set using the same value.  The seed 
   used should be a large integer value.


</pre>

== Significance Testing Statistics Commands ==

=== caret6_stats -significance-cluster-threshold  MAYBE  ===

<pre>

$ caret6_stats -significance-cluster-threshold

Signficance - Cluster-based Thresholding
   -significance-cluster-threshold
   <-statistic-file   statistic-file-name>  
   <-statistic-file-column  column-name-or-index>
   <-output-statistic-file output-file-name>
   <-random-file randomized-file-name>
   <-coordinate-file  coordinate-file-name>
   <-topology-file  topology-file-name>
   <-significance-level  value>
   <-threshold-negative  value>
   <-threshold-positive  value>
   <-output-label-file   label-file-name>
   <-output-report-file  report-file-name>
   [-distortion-file  distortion-metric-shape-file-name]
   [-distortion-file-column  column-name-or-index]
   [-number-of-threads  number-of-threads-to-run
   [-print-progress-message]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   
   Perform cluster-based thresholding.
      * Using the thresholds, find clusters in the specified
        column of the input data file.
      * Using the thresholds, find the largest cluster in 
        each column of the randomized file.  Sort these 
        clusters using their surface area from largest to 
        smallest. 
      * For each cluster in the input data file, use its 
        surface area to find its ranking in the sorted 
        clusters from the randomized file to determine the
        input data file's cluster's P-Value.  For example, 
        if it falls at the 8th percentile, it receives a 
        P-Value of 0.08.
      * The output file will contain the data column from 
        the input file and one or both of the P-Value and
        One-Minus-P-Value.
   
   The data file column may be specified by either its name
   or by its column index with the first column at index 1.
   
   The surface used during this process is either a surface 
   file specified with the "-surface-file" option or 
   coordinate and topology files specified with the 
   "-coordinate-file" and "-topology-file" options.
   
   One or both of the "add-p-value" and 
   "-add-one-minus-p-value" options must be specified.
   The "-add-one-minus-p-value" option works best for
   thresholding in Caret.  The column names may be empty 
   (two consecutive double quotes) in which case the default
   names are used.
   
   If the number-of-threads-to-run is greater than one, 
   the cluster search of the randomized file is run in 
   parallel using the specified number of threads.
   
   The distortion file is used to correct for surface 
   distortion that may occur in the case of surface 
   averaging.  The distortion file column may be specified
   with either its name or by its column index with the first
   column at index 1.
   
   If the report file name is not specified the report is
   printed to the terminal.
   
   If "-print-progress-message" is specified, a message
   is printed as each randomized file column is searched
   .
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP


</pre>

=== caret6_stats -significance-threshold-free ===

<pre>

$ caret6_stats -significance-threshold-free

Signficance - Threshold Free
   -significance-threshold-free
   <-statistic-file   statistic-file-name>  
   <-statistic-file-column  column-name-or-index>
   <-output-statistic-file output-statistic-file-name>
   <-random-file randomized-file-name>
   [-output-randomized-file  output-random-file-name]
   <-coordinate-file  coordinate-file-name>
   <-topology-file  topology-file-name>
   <-significance-level  value>
   <-output-label-file   label-file-name>
   <-output-report-file  report-file-name>
   [-distortion-file  distortion-metric-shape-file-name]
   [-distortion-file-column  column-name-or-index]
   [-E extent]
   [-H height]
   [-monotonic]
   [-threshold-positive  value]
   [-threshold-negative  value]
   [-output-file-encoding  encoding-type]
   [-randomized-output-file-encoding  encoding-type]
   
   Set the significance levels for nodes using the threshold-
   free cluster enhancement algorithm adapted for surface-
   based data.
      * Transform the specified column in the statistic
        file using the TFCE enhancement function.
      * Transform all columns in the randomized file using 
        the TFCE enhancement function.
      * Find the greatest TFCE-enhanced value in each of the 
        randomized files columns.  Rank these values from 
        largest to smallest, assigning P-Values based upon
        their ranks so that the largest value has a P-Value
        of 0.0 and the smallest values a P-Value of 1.0
      * For each node in the specified column of the 
        statistic file, compare its value to the ranked 
        values and assign the node its P-Value.
   
   Set threshold free significance levels.
      * Find and rank the largest absolute value in each
        column of the randomized file where each column is
        a TFCE transformed statistic generated from.
        permuted data.
      * For each value in the input files TFCE column, find
        its ranking in the ranked, random TFCE data and 
        generate the significance level (p-value).
      * Add the P and/or Q values to the output file.
   
   The statistic file column may be specified by either its 
   name or by its column index with the first column at 
   index 1.
   
   The output randomized file is optional.  Creating the 
   output randomized file may use so much memory that the
   program will fail with an out of memory error.
   
   The thresholds should only be used if "-monotonic"
   (the slot monotonic algorithm) is being used. 
   
   The distortion file is used to correct for surface 
   distortion that may occur in the case of surface 
   averaging.  The distortion file column may be specified
   with either its name or by its column index with the first
   column at index 1.
   
   If "-print-progress-message" is specified, a message
   is printed as each randomized file column is searched.
   Add the "-monotonic" option to run the old TFCE algorithm which is very slow
   
   The default value for "-E" (extent) is 1.0
   The default value for "-H" (height) is 2.0
   
   
   
   The available output file encodings are:
         GIFTI
         GIFTI-BASE64
         GIFTI-GZIP
         GIFTI-EXTERNAL
      "GIFTI" is a XML file with all data in text format.
         Files in this format are the largest and take the 
         longest time to read of the GIFTI formats.
      "GIFTI-BASE64" is an XML file with the binary data  
         encoded as Base64 text.
      "GIFTI-GZIP" is an XML file with the binary data 
         compressed using the the GZIP algorithm with the
         binary data encoded using Base64 text.  Files in this
         format are smaller than the other GIFTI formats and 
         usually take the least time to read.
      "GIFTI-EXTERNAL" is an XML file with the data stored 
         in an separate, external, uncompressed file.
      The default output file encoding is GIFTI-GZIP
      The default output randomized file encoding is GIFTI-GZIP


</pre>