Differences between revisions 1 and 2
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
This program will comute statistics on segmented volumes. In its simplist invocation, it will report on the number of voxels and volume in each segmentation. However, it can also compute statistics on the segmentation based on the values from another volume. This includes computing waveforms averaged inside each segmentation. This program will compute statistics on segmented volumes. In its simplest invocation, it will report on the number of voxels and volume in each segmentation. However, it can also compute statistics on the segmentation based on the values from another volume. This includes computing waveforms averaged inside each segmentation.

mri_segstats

This program will compute statistics on segmented volumes. In its simplest invocation, it will report on the number of voxels and volume in each segmentation. However, it can also compute statistics on the segmentation based on the values from another volume. This includes computing waveforms averaged inside each segmentation.

USAGE:

 mri_segstats
   --seg segvol : segmentation volume path
   --annot subject hemi annot : not fully tested yet
   --sum file   : stats summary table file

Other Options

   --pv pvvol : use pvvol to compensate for partial voluming
   --in invol : report more stats on the input volume
   --frame frame : report stats on nth frame of input volume

   --ctab ctabfile : color table file with seg id names
   --ctab-default: use $FREESURFER_HOME/FreeSurferColorLUT.txt
   --ctab-gca gcafile: get color table from GCA (CMA)
   --id segid <--id segid> : manually specify seg ids
   --excludeid segid : exclude seg id from report
   --excl-ctxgmwm : exclude cortical gray and white matter
   --surf-ctxgmwm : compute coritcal gray and white volumes from surf
   --nonempty : only report non-empty segmentations

Masking options

   --mask maskvol : must be same size as seg
   --maskthresh thresh : binarize mask with this threshold <0.5>
   --masksign sign : <abs>,pos,neg
   --maskframe frame : 0-based frame number <0>
   --maskinvert : invert mask

Brain volume options

   --brain-vol-from-seg : get brain volume from brain segmentations
   --brainmask brainmask: compute volume from non-zero vox in brain mask
   --etiv : compute intracranial volume from subject/mri/transfomrs/talairach_with_skull.lta

Average waveform options

   --avgwf textfile  : save into an ascii file
   --avgwfvol mrivol : save as a binary mri 'volume'
   --sfavg textfile  : save mean across space and frame

   --help      print out information on how to use this program
   --version   print out version and exit

COMMAND-LINE ARGUMENTS

--seg segvol

Input segmentation volume. A segmentation is a volume whose voxel values indicate a segmentation or class. This can be as complicaated as a FreeSurfer automatic cortical or subcortial segmentation or as simple as a binary mask. The format of segvol can be anything that mri_convert accepts as input (eg, analyze, nifti, mgh, bhdr, bshort, bfloat).

--sum summaryfile

ASCII file in which summary statistics are saved. See SUMMARY FILE below for more information.

--pv pvvol

Use pvvol to compensate for partial voluming. This should result in more accurate volumes. Usually, this is only done when computing anatomical statistics. Usually, the mri/norm.mgz volume is used.

--in invol

Input volume from which to compute more statistics, including min, max, range, average, and standard deviation as measured spatially across each segmentation. The input volume must be the same size and dimension as the segmentation volume.

--frame frame

Report statistics of the input volume at the 0-based frame number. frame is 0 be default.

--ctab ctabfile

FreeSurfer color table file. This is a file used by FreeSurfer to specify how each segmentation index is mapped to a segmentation name and color. See $FREESURFER_HOME/FreeSurferColorLUT.txt for example. The ctab can be used to specify the segmentations to report on or simply to supply human-readable names to segmentations chosen with --id. See SPECIFYING SEGMENTATION IDS below.

--ctab-default

Same as --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt

--ctab-gca gcafile

Get color table from the given GCA file. Eg, $FREESURFER_HOME/average/RB_all_2006-02-15.gca This can be convenient when the seg file is that produced by mri_ca_label (ie, aseg.mgz) as it will only report on those segmentations that were actually considered during mri_ca_label. Note that there can still be some labels do not have any voxels in the report.

--id segid1 <--id segid2>

Specify numeric segmentation ids. Multiple ids can be specified with multiple --id invocations. SPECIFYING SEGMENTATION IDS.

--excludeid segid

Exclude the given segmentation id from report. This can be convenient for removing id=0. Only one segid can be targeted for exclusion.

--excl-ctxgmwm

Exclude cortical gray and white matter. These are assumed to be IDs 2, 3, 41, and 42. The volume structures are more accurately measured using surface-based methods (see mris_volume).

--surf-ctxgmwm

Compute cortical gray and white matter volumes based on the white and pial surfaces. This is more accurate than from the aseg. The aseg values for these are still reported in the table, but there will be the following lines in the table:

  # surface-based-volume mm3 lh-cerebral-white-matter 266579.428518
  # surface-based-volume mm3 lh-cerebral-cortex       230267.243704
  # surface-based-volume mm3 rh-cerebral-white-matter 265945.120671
  # surface-based-volume mm3 rh-cerebral-cortex       236389.131763

--nonempty

Only report on segmentations that have actual representations in the segmentation volume.

--mask maskvol

Exlude voxels that are not in the mask. Voxels to be excluded are assigned a segid of 0. The mask volume may be binary or continuous. The masking criteria is set by the mask threshold, sign, frame, and invert parameters (see below). The mask volume must be the same size and dimension as the segmentation volume. If no voxels meet the masking criteria, then mri_segstats exits with an error.

--maskthresh thresh

Exlude voxels that are below thresh (for pos sign), above -thresh (for neg sign), or between -thresh and +thresh (for abs sign). Default is 0.5.

--masksign sign

Specify sign for masking threshold. Choices are abs, pos, and neg. Default is abs.

--maskframe frame

Derive the mask volume from the 0-based frameth frame.

--maskinvert

After applying all the masking criteria, invert the mask.

--brain-vol-from-seg

Get volume of brain as the sum of the volumes of the segmentations that are in the brain. Based on CMA/FreeSurferColorLUT.txt. The number of voxels and brain volume are stored as values in the header of the summary file with tags nbrainsegvoxels and brainsegvolume.

--brainmask brainmask

Load brain mask and compute the volume of the brain as the non-zero voxels in this volume. The number of voxels and brain volume are stored as values in the header of the summary file with tags nbrainmaskvoxels and brainmaskvolume.

--avgwf textfile

For each segmentation, compute an average waveform across all the voxels in the segmentation (excluding voxels masked out). The results are saved in an ascii text file with number of rows equal to the number of frames and number of columns equal to the number of segmentations reported plus 2. The first two columns are: (1) 0-based frame number and (2) 0-based frame number times TR.

--avgwfvol mrivol

Same as --avgwf except that the resulting waveforms are stored in a binary mri volume format (eg, analyze, nifti, mgh, etc) with number of columns equal to the number segmentations, number of rows = slices = 1, and the number of frames equal that of the input volume. This may be more convenient than saving as an ascii text file.

--help

Don't get me started ...

SPECIFYING SEGMENTATION IDS

There are three ways that the list of segmentations to report on can be specified:

  1. User specfies with --id.
  2. User supplies a color table but does not specify --id. All the segmentations in the color table are then reported on. If the user specficies a color table and --id, then the segids from --id are used and the color table is only used to determine the name of the segmentation for reporting purposes.
  3. If the user does not specify either --id or a color table, then all the ids from the segmentation volume are used. This list can be further reduced by specifying masks, --nonempty, and --excludeid.

SUMMARY FILE FORMAT

The summary file is an ascii file in which the segmentation statistics are reported. This file will have some 'header' information. Each header line begins with a '#'. There will be a row for each segmentation reported. The number and meaning of the columns depends somewhat how the program was run. The indentity of each column is given in the header. The first col is the row number. The second col is the segmentation id. The third col is the number of voxels in the segmentation. The fourth col is the volume of the segmentation in mm. If a color table was specified, then the next column will be the segmentation name. If an input volume was specified, then the next five columns will be intensity min, max, range, average, and standard deviation measured across the voxels in the segmentation.

EXAMPLES

1. {{{mri_segstats --seg $SUBJECTS_DIR/bert/mri/aseg

  • --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt --nonempty --excludeid 0 --sum bert.aseg.sum}}}

This will compute the segmentation statistics from the automatic FreeSurfer subcortical segmentation for non-empty segmentations and excluding segmentation 0 (UNKNOWN). The results are stored in bert.aseg.sum.

2. {{{mri_segstats --seg $SUBJECTS_DIR/bert/mri/aseg

  • --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt --nonempty --excludeid 0 --sum bert.aseg.sum --in $SUBJECTS_DIR/bert/mri/orig}}}

Same as above but intensity statistics from the orig volume will also be reported for each segmentation.

3. {{{mri_segstats --seg aseg-in-func.img

  • --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt --nonempty --excludeid 0 --in func.img --mask spmT.img --maskthresh 2.3 --sum bert.aseg-in-func.sum --avgwf bert.avgwf.dat --avgwfvol bert.avgwf.img}}}

This will compute the segmentation statistics from the automatic FreeSurfer subcortical segmentation resampled into the functional space (see below and mri_label2vol --help). It will report intensity statistics from the 4D analyze volume func.img (same dimension as aseg-in-func.img). The segmentation is masked by thresholding the spmT.img map at 2.3. The average functional waveform of each segmentation is reported in the ascii file bert.avgwf.dat and in the 4D analyze 'volume' bert.avgwf.img. This is not a real volume but just another way to save the data that may be more convenient than ascii.

4. {{{mri_label2vol --seg $SUBJECTS_DIR/bert/mri/aseg

  • --temp func.img --reg register.dat --fillthresh 0.5 --o aseg-in-func.img}}}

This uses mri_label2vol to resample the automatic subcortical segmentation to the functional space. For more information see mri_label2vol --help.

5. {{{mri_label2vol --annot $SUBJECTS_DIR/bert/label/lh.aparc.annot

  • --temp func.img --reg register.dat --fillthresh 0.5 --hemi lh --subject bert --proj frac 0 .1 1 --o lh.aparc-in-func.img}}}

This uses mri_label2vol to resample the automatic cortical segmentation to the functional space. For more information see mri_label2vol --help.

SEE ALSO:

  • mri_label2vol, tkregister2, mri_vol2roi.

mri_segstats (last edited 2017-11-22 17:57:27 by MorganFogarty)