From Van Essen Lab

Revision as of 18:43, 3 September 2013 by John (Talk | contribs)
Jump to: navigation, search



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

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).

 % caret_command -metric-information
      caret_command -metric-information  
         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

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

caret_command -show-scene

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

 % caret_command -show-scene
      caret_command -show-scene  
         [-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

 % wb_command -show-scene


      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:
      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)

caret_command -surface-border-projection

A projection algorithm is in Workbench and can be used here.

% caret_command -surface-border-projection
      caret_command -surface-border-projection  
         Project the borders using the specified surface.
         Run "caret_command -help-global-options"
            for parameters available to all commands.

caret_command -surface-border-unprojection

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

% caret_command -surface-border-unprojection
      caret_command -surface-border-unprojection  
         Unproject the borders using the specified surface.
         Run "caret_command -help-global-options"
            for parameters available to all commands.

caret_command -surface-border-draw-around-roi

Probably can incorporate the algorithm from Caret5.

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. wb_command only imports foci projection but could be updated for foci. Alternative is to convert foci to foci projection in Caret5.

Foci projection is in Workbench.

% caret_command -surface-foci-projection
      caret_command -surface-foci-projection  
         [-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.

caret_command -surface-foci-unprojection

Foci unprojection is in Workbench.

% caret_command -surface-foci-unprojection
      caret_command -surface-foci-unprojection  
         Unproject the foci projections to the surface and save
         the foci file.

caret_command -surface-folding-measures

Probably can copy from Caret5 but will need some updating.

% caret_command -surface-folding-measures
      caret_command -surface-folding-measures  
         [-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

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

% caret_command -surface-identify-sulci   SURFACE IDENTIFY SULCI
      caret_command -surface-identify-sulci  
         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: 
                NIFTI_GZIP (RECOMMENDED!!!!) 

caret_command -surface-region-of-interest-selection

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

% caret_command -surface-region-of-interest-selection
      caret_command -surface-region-of-interest-selection  
         [-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]
         [-latlon file-name column min-lat max-lat min-lon max-lon SEL_TYPE]
         [-paint  paint-file-name  column  paint-name SEL-TYPE]
         [-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.
         "-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:
         "-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.
             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.

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

% caret_command -surface-to-segmentation-volume
      caret_command -surface-to-segmentation-volume  
         Intersect a surface with a volume and create a segmentation
         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"
         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".

caret_command -surface-topology-disconnect-nodes

Probably can copy from Caret5 but will need some updating.

caret_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.

% caret_command -volume-create
      caret_command -volume-create  
         Create a volume using the specified dimensions.

% caret_command -volume-create-in-stereotaxic-space
      caret_command -volume-create-in-stereotaxic-space  
         Create a volume in the specified stereotaxic space.
         Valid spaces are:

caret_command -volume-set-origin

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

% caret_command -volume-set-origin
      caret_command -volume-set-origin  
         Set the origin for the volume file.

caret_command -volume-set-spacing

See above.

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

% caret_command -volume-set-spacing
      caret_command -volume-set-spacing  
         Set the spacing for the volume file.

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?).

% 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
Maximum Y-Value: 2067064.0
Max Y-Value Displayed: 353863.0

caret_command -volume-information

See metric-information near top.

% 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

caret_command -volume-information-nifti

See metric-information near top.

TSC: redundant, all volumes are nifti.

caret_command -metric-composite

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

caret_command -metric-composite-identified-columns

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

caret_command -metric-math-postfix

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

caret_command -metric-set-column-name

Use wb_command -set-map-names.

caret_command -metric-set-column-to-scalar

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

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

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

caret6_stats -inferential-interhemispheric

caret6_stats -inferential-t-test-one-sample

caret6_stats -inferential-t-test-paired

caret6_stats -inferential-t-test-two-sample

Significance Testing Statistics Commands

caret6_stats -significance-cluster-threshold MAYBE

caret6_stats -significance-threshold-free

Personal tools
Sums Database