Index
Contents
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
Links
Methods Description
description description
References
Reporting Bugs
Report bugs to <analysis-bugs@nmr.mgh.harvard.edu>