'''Index'''
<<TableOfContents>>

= Name =
mri_segstats

= Description =
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.

= Synopsis =
mri_segstats --seg <segvol> --annot <subject hemi parc> --slabel <subject hemi label> --sum <file>

= Arguments =

== Required Flagged Arguments ==
|| --seg segvol || input segmentation volume ||
|| --annot subject hemi parc || create a segmentation from hemi.parc.annot ||
|| --slabel subject hemi label  || create a segmentation from a given surface label. The points in the label are given a value of 1; 0  for outside ||
|| --sum file || ASCII file in which summary statistics are saved ||

== Optional Flagged Arguments ==
|| --pv pvvol || Use pvvol to compenstate 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. Not with --annot||
|| --i 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.||
|| --seg-erode Nerodes || Erode segmentation boundaries by Nerodes||
|| --frame frame || Report statistics of the input volume at the 0-based frame number. Frame is 0 by default. ||
|| --robust percent || Compute statistics after excluding percent from high and low values (volume reported is still full volume) ||
|| --sqr || Compute the square of the input prior to computing statistics ||
|| --sqrt || Compute the square root of the input prior to computing statistics ||
|| --mul val || Multiply input by value ||
|| --div val || Divide input by value ||
|| --snr || Save mean/std as extra column in output table ||
|| --abs || Compute absolute value of input before spatial average ||
|| --accumulate || Save mean*nvoxels instead of the mean ||
|| --ctab ctabfile || Freesurfer color table file. Thi s the file used by !FreeSurfer to specify how each segmentation index is mapped to a segmentation name and color. The ctab can be used to specify the segmentation to report on or simply to supply human-readable names to segmentations chosen with --id. ||
|| --ctab-default || Same as --ctab ||
|| --ctab-gca gcafile || Get color table from the given GCA file. Eg, $FREESURFER_HOME/average/RB_all_YYYY-MM-DD.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 segid <segid2 .... || Specify numeric segmentation ids. Multiple IDs can be specified with multiple IDs after a single --id or with multiple --id invocations. ||
|| --excludeid segid || Exclude the given segmentation id(s) from report. This can be convenient for removing id=0. ||
|| --excl-ctxgmwm || Exclude cortical gray and white matter. These are assumed to be IDs 2, 3, 41, and 42. The volume structures are most accurately measured using surface-based methods. ||
|| --surf-ctx-vol || Compute cortical volumes from surf ||
|| --no-global-stats || Turns off computation of global stats (eg, wmvol, ctx vol, supratent, totalgray, ect) ||
|| --empty || Report on segmentations listed in the color table even if they are not found in the segmentation volume. ||
|| --ctab-out ctaboutput || Create an output color table with just the segmentations reported in the output. ||
|| --replace ID1 ID2 || Replace ID1 with ID2 ||
|| --replace-file file || Replace segmentations based pairs in file ||
|| --gtm-default-seg-merge || Replace segmentations based on GTM default ||
|| --gtm-default-seg-merge-choroid || Replace segmentations based on GTM default excluding choroid. ||
|| --qa-stats subject statsfile || Computes stats that may be useful for quality control. Only these two arguments are needed. Output has 17 items: (1) subjectname, (2) number of control points, (3) number of WM voxels erased, (4) number of WM voxels filled, (5) number of brainmask.mgz voxels erased (relative to brainmask.auto.mgz), (6) number of brainmask.mgz voxels cloned, (7) number of aseg.mgz voxels changed, (8) number of holes in lh.orig.nofix, (9) number of holes in rh.orig.nofix, (10) total number of holes, (11) ratio of number of voxels in brainmask.mgz to the eTIV, (12) mean norm.mgz in WM voxels, (13) spatial std of WM,(14) min WM, (15) max WM, (16) range WM, (17) WM SNR (mean/std). The WM statistics are computed from a WM mask in aparc+aseg.mgz eroded by 3 voxels. The statistics are "robust" meaning that the top and bottom 2% are excluded before computing the stats. ||

== Optional Masking Flagged Arguments ==
|| -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 || Exclude voxels that are below thresh (for pos sign), above thresh (for neg sign), or between 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. ||
|| --maskerode nerode || Erode mask ||
|| --sd SUBJECTS_DIR || Set SUBJECTS_DIR env var ||
|| --help || Print out information on how to use this program ||
|| --version || Print out version and exit ||

== Optional Brain Volume Flagged Arguments ==
|| --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. ||
|| --subcortgray || Compute volume of subcortical gray matter ||
|| --totalgray || Compute volume of total gray matter ||
|| --etiv || Compute intercranial volume from subject/mri/transforms/talairach.xfm ||
|| --etiv-only || Compute intercranial volume from subject/mri/transforms/talairach.xfm and exit ||
|| --old-etiv-only || Compute intercranial volume from subject/mri/transforms/talairach_with_skull.lta and exit ||
|| --talxfm fname || Specify path to talaraich.xfm for etiv ||
|| --euler || Write out number of defect holes in orig.nofix based on the euler number. This is the orig file prior to topology fixing. ||

== Optional Average Waveform Options ==
|| --avgwf textfile || For each segmentation, computes the 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. The order of segmentations is the same order as in the summary file. ||
|| --sumwf textfile || Same as --avgwf but computes the sum instead of the average ||
|| --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. The order of segmentations is the same order as in the summary file. ||
|| --avgwf-remove-mean || Remove temporal mean from avgwf and avgwfvol ||
|| --sfavg textfile || Save mean across space and frame ||
|| --vox C R S || Replace seg with all 0s except at CRS ||

= Notes =
== 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 reporint 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 and	--excludeid.

== Measures of Brain Volume ==
There will be three measures of brain volume in the output summary file:
 1. !BrainSegNotVent - sum of the volume of the structures identified in the aseg.mgz volume this will include cerebellum but not ventricles, CSF and dura. Includes partial volume compensation with --pv. This is probably the number you want to report.
 2. !BrainMask - total volume of non-zero voxels in brainmask.mgz. This will include cerebellum, ventricles, and possibly dura. This is probably not what you want to report.
 3. !BrainSeg - sum of the volume of the structures identified in the aseg.mgz volume. This will  include cerebellum and ventricles but should exclude dura. This does not include partial volume compensation, so this number might be different than the sum of the segmentation volumes.
 4. !IntraCranialVol (ICV) - estimate of the intracranial volume based on the talairach transform. See surfer.nmr.mgh.harvard.edu/fswiki/eTIV for more details. This is the same measure as Estimated Total Intracranial Volume (eTIV).

== 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 =
== Example 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.

== Example 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.
== Example 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.

== Example 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.
== Example 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.

== Example 6 ==
{{{
mri_segstats --annot bert lh aparc --i lh.thickness --sum lh.thickness.sum
}}}

Produce a summary of the thickness in each parcellation of aparc. This will give the same mean thicknesses as that created by mris_anatomical_stats and found in stats/lh.aparc.stats.

= See Also =
  mri_label2vol, tkregister2, mri_vol2roi.

= Reporting Bugs =
Report bugs to freesurfer@nmr.mgh.harvard.edu