====== Processing stream - Cluster tables ======

===== Motivation =====
Many articles concerned with neuroimaging data exhibit one or several tables that represent each contiguous area (cluster) in the statistical map for which the values surpass the applied threshold (alpha level) and, if so configured, the size (cluster level). The following information is commonly shown:
  * the peak location (real-space mm coordinate relative to the atlas/template space, such as Talairach or MNI, given by either the peak voxel's or vertex' corresponding position in space)
  * the size of the contiguous volume or surface for which the voxel/vertex values surpass the currently selected threshold
  * the statistical value and the corresponding alpha threshold (which would be surpassed)
  * optionally also the mean statistical value throughout the contiguous cluster
  * possibly the most likely "label" from any given atlas (such as the popular Talairach and Tournoux atlas from their 1988 publication)
  * and, if useful for the reader, the value of other statistical tests of the location of the peak (for comparison reasons)

===== Requirements =====
**Currently NeuroElf only supports BrainVoyager QX's [[BrainVoyager QX - VMP format|VMP]] format for the creating voxel-based cluster tables and the [[BrainVoyager QX - SMP format|SMP]] format for surface-based cluster tables.** However, maps from other formats (SPM, AFNI) can easily be converted into the VMP format!

===== Instructions =====
  * the VMP must be loaded (either through the [[NeuroElf GUI]] or via the command prompt, see below)
  * the requested thresholds must be either set in the Map sub-structure of the VMP or be given at the command prompt
  * the following code will produce cluster tables on the Matlab prompt using the pre-specified thresholds in the file, with TDclient lookup of peaks that are prior passed through [[mni2tal]]:<code matlab>% load a vmp
vmp = xff('*.vmp', 'Please select the VMP to create cluster tables from...');

% call the ClusterTable method on all maps
for mc = 1:numel(vmp.Map)
    vmp.ClusterTable(mc, [], struct('mni2tal', true, 'tdclient', true));
end</code>If the VMP contains only one Map, the output could look like this:<file>   Clustertable of map:   "Instruction"
           Type of map:   t-Map
    Degrees of freedom:   24
   Cluster k-threshold:   756 mm^3 (28 voxel)
 Applied map threshold:   2.79694 (p < 0.01000)

   x    y    z  |     k  |    max    |    mean    | tal out
-----------------------------------------------------------
 -62  -29    1  |  4343  | 12.599762 |  4.495444  |LH Middle Temporal Gyrus (Brodmann area 21)
  56  -17    1  |  2621  | 12.212478 |  4.706610  |RH Superior Temporal Gyrus
  42  -69   23  |  6089  | -11.466230 | -3.958989  |RH Middle Temporal Gyrus (Brodmann area 39) ( 42; -72; 26) [d=4.2mm])
 -24  -44   52  |  3725  | -7.463678 | -3.759875  |LH Sub-Gyral (Brodmann area 40) (-24; -44; 53) [d=1.0mm])
  18  -77  -26  |   644  |  6.166085 |  3.614730  |RH Uvula
  53    5   41  |   490  |  6.045987 |  3.543852  |RH Middle Frontal Gyrus (Brodmann area 6)
 -24  -86  -29  |   531  |  5.537820 |  3.550749  |LH Tuber
   3   22  -19  |   170  | -5.158958 | -3.368761  |RH Rectal Gyrus (Brodmann area 11)
  -3    9   58  |   307  |  4.858146 |  3.318970  |LH Superior Frontal Gyrus (Brodmann area 6)
 -18   48  -40  |    74  |  4.584736 |  3.240567  |
  24   47  -43  |    32  |  4.447770 |  3.328945  |
 -39  -48  -35  |    60  |  4.394799 |  3.284489  |LH Cerebellar Tonsil
 -12   60  -18  |    48  | -4.369187 | -3.219919  |LH Medial Frontal Gyrus (Brodmann area 11)
 -18   68   21  |    44  | -4.363572 | -3.224104  |LH Superior Frontal Gyrus (Brodmann area 10) (-18;  66; 18) [d=3.6mm])
   0   -2  -35  |    35  |  4.268754 |  3.283021  |
  24   -6   56  |    28  | -4.124228 | -3.364937  |RH Sub-Gyral (Brodmann area 6) ( 24;  -4; 56) [d=2.0mm])
   6   55   -3  |    31  | -4.077537 | -3.178503  |RH Anterior Cingulate (Brodmann area 10) (  6;  54; -2) [d=1.4mm])
  12   -8  -40  |    46  |  4.059139 |  3.254556  |
 -12  -28  -29  |    52  | -3.793806 | -3.005253  |LH Culmen (-12; -32;-22) [d=8.1mm])
   0  -20    9  |   125  |  3.537359 |  3.055317  |LH Thalamus ( -3; -20;  9) [d=3.0mm])
  12   -5   11  |    36  |  3.310278 |  3.004088  |RH Thalamus (Ventral Anterior Nucleus)</file>

===== Additional information =====
Further instructions on the syntax can be found on the [[vmp.ClusterTable|ClusterTable method reference]] page.