====== obj.ClusterTable ======

===== Motivation =====
As part of the analysis output for a whole-brain search (i.e. next to images of whole-brain statistical maps for instance), people usually include tables of activation peaks into their manuscripts. This method allows to create such tables with the following features:

  * separating all voxels above thresholds (clustering)
  * searching for local maxima (minima) within each cluster (see [[splitclustercoords]] for more info)
  * generating a BrainVoyager QX compatible [[VOI]] object with the clustering information (functional voxels represented uniquely)
  * location of activation peaks (highest statistical values)
  * reporting the size of each cluster as well as the average statistical value
  * extracting the statistical value of other available maps at those coordinates (to compare statistical values)
  * optional conversion of coordinates from MNI into Talairach space (using Matthew Brett's [[mni2tal]] function)
  * looking up the closest Talairach label for each peak coordinate (using a toolbox-builtin local TD database function)

===== Method reference ('obj.Help('ClusterTable')') =====
<file> OBJ::ClusterTable  - generate a table with clusters
 
 FORMAT:       [c, t, v, vo] = obj.ClusterTable(mapno [, thresh [, opts]])
 
 Input fields:
 
       mapno       map number (1 .. NrOfMaps)
       thresh      either p/r values (0 .. 1) or t/F value (1 .. Inf)
                   if not given or 0, uses the LowerThreshold of map
       opts        optional settings
        .altmaps   alternative maps to extract values from (default: [])
        .altstat   either of 'mean' or {'peak'}
        .cclag     flag, interpret the threshold as lag number (false)
        .clconn    cluster connectivity ('face', {'edge'}, 'vertex')
        .icbm2tal  flag, VMP coords are passed to icbm2tal (default: false)
        .localmax  break down larger clusters threshold (default: Inf)
        .localmaxi iterate on sub-clusters (default: false)
        .localmin  minimum size for sub-clusters (default: 2)
        .localmsz  print sub-cluster sizes (default: false)
        .lupcrd    look-up coordinate, either or 'center', 'cog', {'peak'}
        .minsize   minimum cluster size (map resolution, default by map)
        .mni2tal   flag, VMP coords are passed to mni2tal (default: false)
        .showneg   flag, negative values are considered (default: false)
        .showpos   flag, positive values are considered (default: true)
        .sorting   either of 'maxstat', {'maxstats'}, 'size', 'x', 'y', 'z'
        .svc       small-volume correction (either VOI, voxels, or image)
        .svcthresh threshold for SVC (default: 0.05)
        .tdclient  flag, lookup closest talairach label (default false)
 
 Output fields:
 
       c           1xC struct with properties of clusters
       t           text table output
       v           thresholded map (in VMP resolution!)
       vo          if requested, VOI structure with (TAL) coords
 
 TYPES: CMP, HDR, HEAD, MSK, VMP
 
 Note: if only one output is requested, the table is text table is
       returned!!
 
 Note: icbm2tal overrides mni2tal!
 
 Note: svc only valid for VMP (given FWHM estimate in RunTimeVars!)</file>

===== Arguments =====
==== mapno ====
This references the map number within the [[xff - VMP format|VMP object]]. Must be an integer number between 1 and the number of maps.

==== thresh ====
This sets the threshold. If the value is smaller than 0.1, the value is interpreted as a probability value for Null-hypothesis-testing, and the map type (''.Type''), degrees-of-freedom (''.DF1'' and ''.DF2''), and selected-tails (''.ShowPositiveNegativeFlag'') parameters are used to compute the correct threshold value. If left empty, the threshold configured in the map (''.LowerThreshold'') is used.

==== opts ====
If given, this must be a 1x1 struct with the following optional fields:

=== .altmaps ===
Lists the indices of maps to extract statistical values at the coordinates of the peaks in the selected map (''mapno'' argument).

=== .altstat ===
Selects whether the peak or the mean for the additional maps is extracted and shown.

=== .cclag ===
If given and set to ''1x1 logical'' with value ''true'', the given ''thresh'' argument is interpreted as a lag number for a cross-correlation map.

=== .clconn ===
Overrides the default for the setting as how to determine whether two adjacent voxels are connected (belong to the same cluster); whereas '''face''' means that voxels must be direct neighbors (coordinate value may only be different by 1 voxel in one dimension), '''edge''' (which is the default) means that voxels are also considered to be connected when the coordinate values differ by up to 1 in two dimensions, and '''vertex''' finally means that voxels which are only connected by one of their vertices (full spatial diagonal where all dimensions differ by 1 in either direction) are considered to be part of one cluster.

=== .icbm2tal ===
Turns on ICBM2TAL conversion (using the [[icbm2tal]] function) **for the text output (only)** instead of mni2tal.

=== .localmax ===
Sets a threshold (related to cluster size in number of voxels) for which an attempt is made to search for local maxima (or minima for negative values) within the given cluster. The default is ''Inf'' which means that clusters are not being searched for local maxima.

=== .localmaxi ===
Flag to turn on iterating over sub-clusters until no more splitting can be performed.

=== .localmin ===
Sets the minimal size of sub-clusters (useful restriction for maps that have been masked, where the local maxima might be at the very edge of the cluster; please see [[splitclustercoords]] for more information).

=== .localmsz ===
Flag whether or not to print sub-cluster sizes (in text output).

=== .lupcrd ===
Which coordinate to print in the text output (center, i.e. mean, center-of-gravity, i.e. the stats-weighted mean, or peak).

=== .minsize ===
Overrides the ''.ClusterSize'' and ''.EnableClusterCheck'' settings in the map (referenced by the ''mapno'' argument). If given, clusters of smaller size will not be part of the output (but this does not apply to the size estimate of local sub-clusters, as the clustersize is used only as a way to ensure that a given cluster is significant, see [[alphasim]] for more information).

=== .mni2tal ===
If this is set to a ''1x1 logical'' with value ''true'', coordinates reported in a table will (and potentially passed to the Talairach Daemon database lookup function, [[tdclient]]) will first be passed through the [[mni2tal]] function to account for the fact that the MNI Space (in which, for instance, all typical SPM results will be in) does not lign up perfectly with the space as defined as "Talairach Space" (see [[mni2tal]] for more background).

=== .showneg ===
Flag to override the ''.ShowPositiveNegativeFlag'' in the map of the VMP. If set to a ''1x1 logical'' with value ''true'' the negative tail of the distribution is taken into account (which also applies to the conversion of p-thresholds given by the ''thresh'' argument!). If set to ''false'', the negative tail will be suppressed.

=== .showpos ===
Flag to override the ''.ShowPositiveNegativeFlag'' in the map of the VMP. If set to a ''1x1 logical'' with value ''true'' the positive tail of the distribution is taken into account (which also applies to the conversion of p-thresholds given by the ''thresh'' argument!). If set to ''false'', the positive tail will be suppressed.

=== .sorting ===
Alters the way in which clusters are sorted for both table and [[xff - VOI format|VOI]] outputs. The default value, '''maxstat''' means that clusters with a higher (absolute) statistical value will appear before clusters with a lower statistical value in the output. The value '''size''' sorts from larger to smaller clusters, and the values '''x''', '''y''', and '''z''' will sort clusters by their coordinate (in the given dimension).

=== .svc ===
If a small-volume is provided in this field (either a VOI object, an image object, or a list of coordinates), perform SVC on the selected map (only works for VMP maps, and creates a new map in the object).

=== .svcthresh ===
Corrected threshold for SVC.

=== .tdclient ===
If set to a ''1x1 logical'' with value ''true'', coordinates (potentially passed through [[mni2tal]] first) will be passed on to [[tdclient]], a local implementation of the Talairach Daemon database with the options to lookup the nearest gray matter label within a preset search radius of 7 millimeters (which approximates the most commonly used smoothing kernels of 6 and 8mm). This only affects the text output!

===== Output(s) =====
==== c ====
This is a ''1xC'' struct with the properties of the found clusters, which contains the following fields:
  * ''.coords'' - ''Cx3'' list of coordinates (unique functional locations), given in the internal resolution and space, so that they can be immediately used to access data in the map
  * ''.localmax'' - ''1x1 char'' value, either set to the space character (not a local maximum) or '''L''' (local maximum), useful for function that create user-defined tables
  * ''.max'' - maximum value within cluster; for clusters with negative values, this reflects the minimum value (absolute maximum with correct sign)
  * ''.mean'' - average value within cluster
  * ''.peak'' - peak coordinate given in the internal resolution and space (is identical to the first coordinate in the cluster)
  * ''.peakalt'' - if alternative maps are given in the ''opts.altmaps'' option, this contains the list of values extracted from those maps at peak location
  * ''.rwcoords'' - ''Cx3'' list of coordinates, a transformation has been applied to represent BrainVoyager's TAL axes notation (X = left/right with 0 being the center, and so on)
  * ''.rwpeak'' - peak coordinate in real-world coordinates (identical to the first coordinate in ''.rwcoords'')
  * ''.rwsize'' - estimated size of the cluster in real-world space (by using the functional resolution, e.g. for a 3mm-resolution map, the number of coordinates is multiplied with 27)
  * ''.size'' - number of functional voxels (equals ''size(c(C).coords, 1)'')
  * ''.talcoords'' - if the ''opts.mni2tal'' flag is set to ''true'', this will contain the coordinates after passing ''.rwcoords'' through [[mni2tal]]
  * ''.talout'' - this is then set to the output of the [[tdclient]] function for the peak (first) coordinate in the cluster's ''.rwcoords''
  * ''.talpeak'' - peak location in Talairach space (only set if ''opts.mni2tal'' is set to ''true'')
  * ''.values'' - extracted values for the current map (useful for scripts that need each value)

==== t ====
Text table output. Here is an example generated with the following code:

<code matlab vmp_ClusterTable_example.m>% create new VMP
vmp = xff('new:vmp');

% generate random data
vmp.Map.VMPData = single(15.*smoothdata3(randn(size(vmp.Map.VMPData)), [2,2,2]));

% mask with Colin's brain (we don't want stuff that couldn't be good)
cb = neuroelf_file('c', 'colin_brain.vmr');
vmp.MaskWithVMR(cb, 11);

% produce cluster table outputs
[c,t,v,vo] = vmp.ClusterTable(1, -sdist('tinv', 1e-6, vmp.Map.DF1), struct( ...
    'minsize', 40, 'mni2tal', true, 'tdclient', true));</code>

Which produced (will differ, given that it is random data!):

<file>   Clustertable of map:   "New Map"
           Type of map:   t-Map
    Degrees of freedom:   249
   Cluster k-threshold:   1080 mm^3 (40 voxel)
 Applied map threshold:   4.86840 (p < 0.00000)

   x    y    z  |     k  |    max    |    mean    | tal out
-----------------------------------------------------------
  68  -10   -1  |   114  | 13.611333 |  6.891288  |RH Middle Temporal Gyrus (Brodmann area 21) ( 68; -11; -2) [d=1.4mm])
 -30  -12   71  |    41  | -11.695634 | -6.247030  |LH Precentral Gyrus (Brodmann area 6) (-30; -12; 67) [d=4.0mm])
 -56   20    5  |    84  | 10.922107 |  6.315453  |LH Inferior Frontal Gyrus (Brodmann area 45)
 -27  -18   65  |    59  | 10.363769 |  6.237379  |LH Precentral Gyrus (Brodmann area 6) (-28; -17; 62) [d=3.3mm])
   9  -32  -33  |    58  | 10.271681 |  6.644166  |
  39  -36    3  |   141  | -9.934493 | -6.074017  |RH Caudate (Caudate Tail) ( 35; -35;  2) [d=4.2mm])
  12   -2   29  |    53  | -9.922318 | -6.117676  |RH Cingulate Gyrus (Brodmann area 24) (  7;  -2; 30) [d=5.1mm])
 -65  -31   33  |   101  | -9.520975 | -6.539583  |LH Inferior Parietal Lobule (Brodmann area 40)
 -15  -16  -11  |    48  |  9.516015 |  6.776953  |LH Parahippocampal Gyrus (Brodmann area 28) (-17; -14;-11) [d=2.8mm])
 -56   34   -1  |    52  |  9.491652 |  6.201726  |LH Inferior Frontal Gyrus (Brodmann area 47)
 -12    5   70  |    66  | -9.457577 | -6.388255  |LH Superior Frontal Gyrus (Brodmann area 6) (-10;   8; 67) [d=4.7mm])
  15    9   25  |    68  |  9.455211 |  6.238290  |RH Caudate (Caudate Body) ( 15;   8; 21) [d=4.1mm])
 -33  -31  -15  |    58  | -9.024246 | -5.839670  |LH Parahippocampal Gyrus (Brodmann area 36)
 -30  -89  -20  |    46  |  8.971775 |  6.387179  |LH Declive (-30; -88;-20) [d=1.0mm])
  -6  -33    8  |    44  |  8.942706 |  6.349526  |LH Thalamus ( -9; -31;  8) [d=3.6mm])
 -45  -43   25  |    45  |  8.869677 |  6.180710  |LH Superior Temporal Gyrus (Brodmann area 13) (-45; -43; 21) [d=4.0mm])
   6  -86  -18  |    49  |  8.615259 |  5.918599  |RH Declive (  7; -85;-18) [d=1.4mm])
   9  -63  -24  |    56  | -8.613391 | -6.012746  |RH Nodule
 -21  -58   29  |    54  | -8.550800 | -6.070900  |LH Precuneus (Brodmann area 7) (-20; -62; 30) [d=4.2mm])
 -42   11   -2  |    53  |  8.523092 |  5.915134  |LH Insula (Brodmann area 13)
 -12  -25   35  |    43  | -8.373242 | -6.004561  |LH Cingulate Gyrus (Brodmann area 31) (-12; -25; 38) [d=3.0mm])
   6  -53   62  |    47  | -8.299561 | -5.859161  |RH Precuneus (Brodmann area 7) (  5; -53; 62) [d=1.0mm])
  50   37   -6  |    53  | -7.895029 | -6.229494  |RH Middle Frontal Gyrus (Brodmann area 47)</file>

**NOTE: if only one output is requested (e.g. if called without outputs and without semicolon), then only the text table is returned, which then replaces the ''c'' output!**

==== v ====
This is the numeric map (as in ''vmp.Map(mapno).VMPData'') after thresholding (in double precision). Potentially useful for display and further processing.

==== vo ====
This is a 1x1 [[xff - VOI format|xff object of sub-type VOI]] which contains the clusters and their coordinates as in ''.rwcoords'' of the cluster structure (and a copy of the values in ''vo.VOI(V).VoxelValues''; while this field is not supported by the [[xff - VOI format|VOI format]], this information does not //harm// the object in any way, and it is used by the [[neuroelf_gui|GUI]] of NeuroElf).