Cluster

The tool cluster can be used to form clusters, report information about clusters and/or perform cluster-based inference.

Cluster formation can be done using any type of image as it uses a supplied threshold, even though the default reporting and input options mention z-stats. Optionally, inference (turning cluster sizes into clusterwise p-values) is done using Gaussian Random Field (GRF) theory and requires smoothness estimates from smoothest.

The usage for cluster is:

cluster --in=<filename> --thresh=<value> [options]

Compulsory arguments (You MUST set one or more of):
        -i,--in,-z,--zstat      filename of input volume
        -t,--thresh,--zthresh   threshold for input volume

Optional arguments (You may optionally specify one or more of):
        -o,--oindex     filename for output of cluster index (in size order)
        --othresh       filename for output of thresholded image
        --olmax filename for output of local maxima text file
        --olmaxim       filename for output of local maxima volume
        --osize filename for output of size image
        --omax  filename for output of max image
        --omean filename for output of mean image
        --opvals        filename for image output of log pvals
        -p,--pthresh    p-threshold for clusters
        --peakdist      minimum distance between local maxima/minima, in mm (default 0)
        -c,--cope       filename of input cope volume
        --volume        number of voxels in the mask
        -d,--dlh        smoothness estimate = sqrt(det(Lambda))
        --fractional    interprets the threshold as a fraction of the robust range
        --connectivity  the connectivity of voxels (default 26)
        --mm    use mm, not voxel, coordinates
        --min   find minima instead of maxima
        --no_table      suppresses printing of the table info
        --minclustersize        prints out minimum significant cluster size
        -x,--xfm        filename for Linear: input->standard-space transform. Non-linear: input->highres transform
        --stdvol        filename for standard-space volume
        --scalarname    give name of scalars (e.g. Z) - to be used in printing output tables
        -n,--num        no of local maxima to report
        -v,--verbose    switch on diagnostic messages
        -h,--help       display this message
        --warpvol       filename for warpfield

Outputs

The main output from cluster is the table reporting the different clusters, their size, and information about their location and contents (e.g. maximum/mean values within the cluster). This table is written as plain text and is output to the screen, but can be redirected into a file using the standard unix method of using "> filename" after the command (which puts all the output that would have been written to the screen into the specified file instead) - see examples below.

The standard output table contains the following columns:

Cluster Index   Voxels  MAX     MAX X (vox)     MAX Y (vox)     MAX Z (vox)     COG X (vox)     COG Y (vox)     COG Z (vox)

Cluster Index: a unique number for each cluster from 1 to N (larger clusters have bigger numbers)
Voxels: the number of voxels in the cluster
MAX: the value of the maximum "intensity" within the cluster (e.g. the maximum z-statistic if the input was a z-statistic image)
MAX X/Y/Z (vox/mm): the location of the maximum intensity voxel, given as X/Y/Z coordinate values in either voxel coordinates (vox) or standard space coordinates (mm) - the latter requires either the input image to already be in standard space or a transformation to standard space to be specified via the options -x,--xfm or --warpvol
COG X/Y/Z (vox/mm): the location of the Centre Of Gravity for the cluster (that is, a weighted average of the coordinates by the intensities within the cluster, equivalent to the concept of Centre Of Gravity for a object with distributed mass, where intensity substitutes for mass in this case)

Note that the text formatting of the columns can make it difficult to see which header is attached to which column of numbers, so be careful to count the columns correctly.

If a COPE image is added (-c,--cope) then extra columns are added to the table, reporting the maximum COPE value, the location of this maximum and the mean COPE value over the clusters defined from the input image (i.e., clusters are not defined using the COPE image).

If GRF options are added (-d,--dlh and --volume and -p,--pthresh) then the table also reports the probability (p-value and -log10(p)) associated with each cluster.

Some particularly useful image outputs are:

cluster index (--oindex or -o): this is an image where every cluster is assigned a unique number (from 1 to N) and the intensity of every voxel in a cluster is set to this unique number. For example, every voxel in cluster number 3 will have an intensity of 3. This is very useful for separating/extracting clusters - see the examples below.
size index (--osize): every voxel in a cluster has its intensity set equal to the size of that cluster (where size is the number of voxels). This is useful for thresholding clusters based on size.

Examples

The examples below represent a small set of possibilities, but include the most commonly used scenarios. Note that most of the commands below redirect the text output into a file, but the text output can be displayed directly on the screen by deleting everything from the ">" character and onwards.

Defining Clusters

    cluster -i myinputimage -t 2.5 -o cluster_index --osize=cluster_size > cluster_info.txt

This takes any type of input values (contained in the image file myinputimage) and thresholds them at 2.5 (a totally arbitrary example value here). The output images specified here are two of the most useful outputs, as described above, although other outputs can also be requested.

Extracting a Particular Cluster

Assuming that a cluster index file has been created (e.g., as above) then any particular cluster can be extracted using fslmaths. For example, to extract a mask that contained only cluster number 7 we would do:

    fslmaths -dt int cluster_index -thr 7 -uthr 7 -bin cluster_mask7

Reporting Cluster Information

Z-stat (without GRF statistics):

    cluster -i zstat1 -t 2.3 > cluster_zstat1.txt

Note: the threshold value of 2.3 is an arbitrary example only.

Corrected 1-p values (as output from randomise):

    cluster -i blah_blah_corrp_tstat1 -t 0.95 --scalarname="1-p" > cluster_corrp1.txt

Notes: the threshold is based on the 1-p value (i.e. 0.95 = 1 - 0.05); the use of --scalarname means that all the table headings report "1-p" rather than "Z".

Corrected 1-p values with associated t-statistics (as output from randomise):

    cluster -i blah_blah_corrp_tstat1 -t 0.95 -c blah_blah_tstat1 --scalarname="1-p" > cluster_corrp1.txt

Note: the columns labelled COPE refer to the associated t-statistics within the respective clusters (where the clusters are still defined by the 1-p values in the input image, together with the threshold)

Z-stat with GRF statistics:

    cluster -i zstat1 -t 2.3 -p 0.05 -d 1.65786 --volume=19537 > cluster_zstat1.txt