Index

Name

mri_volcluster - find clusters in volume

Synopsis

mri_volcluster --in inputstem --minsize minclustervolume --thmin minthresh --reg register.dat

Arguments

Required Flagged Arguments

--in inputstem

input stem for volume to be clustered

--minsize minclustervolume

minimum volume of cluster in mm 3

minimum volume (in mm 3) of contiguous voxels that meet the threshold criteria needed to become a cluster. See also --minsizevox

--thmin minthresh

minimum voxel intensity for cluster voxels

voxel values must exceed this amount to be considered as a candidate for a cluster

--reg register.dat

registration file

registration file created by either tkregister or tkmedit. Note: the subject listed in the registration file must have an entry under $SUBJECTS_DIR

Optional Flagged Arguments

--in_type fileformatname

file format name

name of the file format type of the input volume

--frame n

perform cluster analysis on nth frame

the first frame corresponds to n=0

--thmax maxthresh

maximum voxel intensity for cluster

voxel values must exceed this amount to be considered as a candidate for a cluster Default: infinity

--sign signname

Legal values: <abs>, neg, pos

the value of a voxel must be this sign to be considered as a candidate for a cluster. pos = positive, neg = negative, abs = absolute (ie, ignore sign). Default is abs. When neg is used, the interpretation of minthreshold and maxthreshold are reversed

--minsizevox number

minimum volume (voxels)

minimum number of contiguous voxels that meet the threshold criteria needed to become a cluster. See also --minsize

--mindistance distance

distance threshold

minimum distance (in mm) that the peaks of two clusters must be separated in order for them to be considered two distinct clusters. If two clusters are closer than this amount, the cluster with the lower peak is eliminated.

--allowdiag

define contiguity to include diagonal

allow two voxels that share a corner to be considered contiguous

--mask maskstem

mask stem

filestem for mask volume used to restrict the region over which clusters will be searched. For example, this could be used to restrict the search space to only the brain (ie, exclude eyeballs). The mask must have the same dimension as the input volume.

--mask_type typename

file format for mask

--maskframe frameno

frameno to use from mask volume

use the nth frame of the mask volume as the mask, where n = 0 indicates the first frame. Default is 0.

--maskthresh maskthresh

upper threshold for mask

use only those voxels in the mask whose value exceeds the given threshold (see also --masksign and --maskinvert).

--masksign signname

sign for mask threshold

threshold the mask based on the sign of the value at each mask voxel: pos = positive, neg = negative, abs = absolute (ie, ignore sign). Default is abs. When neg is used, the a mask voxel value must be less than -maskthresh. <abs>, neg, pos

--maskinvert

invert mask

after determining which voxels are in the mask based on the threshold and sign, take only voxels that are outside of the mask

--outmask outmaskstem

stem for final binary mask

filename for the final binary mask after considering thresholding, sign, and inversion. This is mainly useful for debugging

--outmask_type fileformat

fileformat for binary mask output

--sumfile sumfilename

filename for text summary

See Description

--out outfile

filename for output volume

--out_type fileformat

fileformat for output volume

--ocn ocnfilename

output cluster number filename

filename of the output volume after clustering where the value at each voxel is the cluster number (as found in the summary file). Voxels that did not belong to a cluster have their values set to zero.

--ocn_type fileformat

fileformat for ocnfile

--label labelfile

save the nth cluster

save nth cluster (see -nlabelcluster) as a label file in the subject's anatomical space. Note: make sure that the label file includes a forward slash (/) or the label will be saved into the subjects anatomical direcotry. For example: ./mylabel.label. Requires --nlabelcluster.

--nlabelcluster n

save nth cluster in label

--labelbase base

save all clusters

save all clusters under base-NNNN.label save each cluster in its own label file. The name of the file will be base-NNNN.label, where NNNN is the four digit, zero-padded cluster number. All clusters found will be saved.

--synth synthfunc

Legal values: uniform,loguniform,gaussian

--help

how to use this program

Outputs

??

description

??

description

Description

mri_volcluster will find clusters in a volume. A cluster is a set of contiguous voxels which meet a threshold criteria. The set may also have to reach a certain minimum number of voxels to be considered a cluster. The results can be saved in four ways: (1) a text summary file, (2) a new volume which is same as the input volume but with all the voxels that do not belong to a cluster set to zero, (3) a volume with each voxel's value equal to the cluster number in the summary file to which the voxel belongs, and (4) one cluster can be saved as a label file. The search space within the volume can be restricted to be within a mask. Two voxels are considered contiguous if they share a common row, column, or slice (except for --allowdiag).

SUMMARY FILE

The summary file produced by --sumfile is in ASCII text. The summary file will have a short header indicating the conditions underwhich the clustering was performed followed by rows of data with 7 columns. Each row reprsents a different cluster. Each column has the following interpretation: (1) cluster number, (2) number of voxels in the cluster, (3) cluster volume in mm^3, (4-6) Talairach X, Y, and Z (mm), (7) maximum value inside the cluster. The Talairach coordinates are the 'true' coordinates (not MNI). Part of a summary file is shown below as an example:

-----------------------------------------------------------------------
Cluster Growing Summary (mri_volcluster)
Input Volume:      grp-subj-p1p2vlor/bold/sxa-h20/tal-ffx-rfx/novvfix/sig
Frame Number:      0
Minimum Threshold: 2
Maximum Threshold: inifinity
Threshold Sign:    abs
Distance Threshold: 10 (mm)
Size Threshold:    640 mm^3
Size Threshold:    10 voxels
Voxel Size:        64 mm^3
Registration:      grp-subj-p1p2vlor/bold/sxa-h20/tal-ffx-rfx/register.dat
Mask Vol:          talbrain/mask
Mask Thresh:       0.500000
Mask Sign:         pos
Mask Invert:       0
AllowDiag:         1
NClusters          26

Cluster Size(n) Size(mm^3)  TalX   TalY    TalZ     Max
  1      348      22272.0   59.40 -66.72  -13.48   5.66192
  2       45       2880.0  -39.60  26.79   -8.07   5.45487
  3       27       1728.0   55.44  16.60   21.28   4.95684
-----------------------------------------------------------------------

Examples

Example 1

mri_volcluster ??

Description

Example 2

mri_volcluster ??

Description

Bugs

When specifying a label file, make sure that the label file includes a forward slash (/) or the label will be saved into the subjects anatomical direcotry. For example: ./mylabel.label

See Also

othercommand1, othercommand2

Links

FreeSurfer, FsFast

Methods Description

description
description

References

References/Lastname###

Reporting Bugs

Report bugs to <analysis-bugs@nmr.mgh.harvard.edu>

Author/s

DougGreve

mri_volcluster (last edited 2008-04-29 11:46:03 by localhost)