function cval=cosmo_measure_clusters(sample,nbrhood_mat,cluster_stat,varargin)
% General cluster measure
%
% cval=cosmo_measure_clusters(sample,nbrhood_mat,method,['dh',dh|'threshold',t],...)
%
% Inputs:
% sample 1xP data array for k features
% nbrhood_mat MxP neighborhood matrix, if each feature has at
% most M neighbors. nbrhood_mx(:,k) should contain
% the feature ids of the neighbors of feature k
% (values of zero indicate no neighbors)
% cluster_stat 'tfce', 'max', 'maxsize', or 'maxsum'.
% 'dh',dh when method is 'tfce', the integral step size
% 'threshold',t if method is anything but 'tfce', the threshold
% level
% 'E', E (optional) when method is 'tfce': the extent
% exponent, default E=0.5
% 'H', E (optional) when method is 'tfce': the height
% exponent, default H=2
% 'feature_sizes', s (optional) 1xP element size of each feature;
% default is a vector with all elements equal to 1.
%
% Output:
% cval 1xP data array with cluster values.
% Define:
% cl_k(thr) Feature ids that are connected
% with feature k when sample is
% thresholded at thr.
% (with cl_k(thr)=[] if sample(k)<thr).
% e_k(thr) The extent of the cluster for feature
% k when thresholded at thr, i.e.
% e_k=sum[i=cl_k(thr)] s(i)
% max0[x=xs]v(x) the maximum value that v takes for
% any value in xs, or zero if xs is
% empty.
% The output for a feature k depends on cluster_stat:
% - 'tfce':
% cval(k)=sum[h=dh:dh:max(sample)] e_k(h)^E *h^H * dh
% i.e. a weighted sum of the extent and height of
% the cluster at different thresholds
% - 'max':
% cval(k)=max0[i=cl_k(thr)] samples(i))
% i.e. the maximum value in the cluster that contains k
% - 'maxsize'
% cval(k)=e_k(thr)
% i.e. the size of the cluster that contains k
% - 'maxsum'
% cval(k)=sum[i=cl_k(thr)] samples(i)
% i.e. the sum of the values in the cluster that
% contains k
%
% Examples:
% % very simple one-dimensional 'line' example
% samples= [1 2 1 1 0 2 2];
% nbrhood_mat= [1 1 2 3 4 5 6;...
% 2 2 3 4 5 6 7;...
% 0 3 4 5 6 7 0];
% % illustrate TFCE cluster stat. Note that the results vary little
% % as a function of dh, and that both features in clusters with a
% % larger extent but less extreme value and features in clusters with
% % smaller extent but more extreme values have larger values
% s=cosmo_measure_clusters(samples,nbrhood_mat,'tfce','dh',.1);
% cosmo_disp(s,'threshold',inf)
% %|| [ 0.77 2.86 0.77 0.77 0 3.49 3.49 ]
% %
% s=cosmo_measure_clusters(samples,nbrhood_mat,'tfce','dh',.05);
% cosmo_disp(s,'threshold',inf)
% %|| [ 0.618 2.88 0.618 0.618 0 3.63 3.63 ]
% %
% % illustrate other cluster stats. Note that the results varies more
% % as a function of the chosen threshold
% cosmo_measure_clusters(samples,nbrhood_mat,'max','threshold',1)
% %|| 2 2 2 2 0 2 2
% %
% cosmo_measure_clusters(samples,nbrhood_mat,'max','threshold',2)
% %|| 0 2 0 0 0 2 2
% %
% cosmo_measure_clusters(samples,nbrhood_mat,'maxsize','threshold',1)
% %|| 4 4 4 4 0 2 2
% %
% cosmo_measure_clusters(samples,nbrhood_mat,'maxsize','threshold',2)
% %|| 0 1 0 0 0 2 2
% %
% cosmo_measure_clusters(samples,nbrhood_mat,'maxsum','threshold',1)
% %|| 5 5 5 5 0 4 4
% %
% cosmo_measure_clusters(samples,nbrhood_mat,'maxsum','threshold',2)
% %|| 0 2 0 0 0 4 4
%
% Notes:
% - the 'method' argument is similar to FieldTrip's clusterstat method,
% but does support 'tfce' and does not support 'wcm'
% - unlike FieldTrip's clusterstat, a value is returned for each feature
% (rather than each cluster).
% - TFCE is advised in the general case, because it finds a compromise
% between magnitude of values and extent of clusters.
% - this function is used by cosmo_montecarlo_cluster_stat for
% non-parametric cluster-based correction for multiple comparisons.
%
% References:
% - Stephen M. Smith, Thomas E. Nichols (2009), Threshold-free
% cluster enhancement: Addressing problems of smoothing, threshold
% dependence and localisation in cluster inference, NeuroImage, Volume
% 44, 83-98.
% - Maris, E., Oostenveld, R. Nonparametric statistical testing of EEG-
% and MEG-data. Journal of Neuroscience Methods (2007).
%
% See also: cosmo_convert_neighborhood, cosmo_montecarlo_cluster_stat
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
