function res=cosmo_distatis(ds, varargin)
% apply DISTATIS measure to each feature
%
% res=cosmo_statis_measure(ds, opt)
%
% Inputs:
% ds dataset struct with dissimilarity values; usually
% the output from @cosmo_dissimilarity_matrix_measure
% applied to each subject followed by cosmo_stack. It
% can also be a cell with datasets (one per subject).
% 'return', d d can be 'distance' (default) or 'crossproduct'.
% 'distance' returns a distance matrix, whereas
% 'crossproduct' returns a crossproduct matrix
% 'split_by', s sample attribute that discriminates chunks
% (participants) (default: 'chunks')
% 'shape', sh shape of output if it were unflattened using
% cosmo_unflatten, either 'square' (default) or
% 'triangle' (which gives the lower diagonal of the
% distance matrix)
%
% Returns:
% res result dataset struct with feature-wise optimal
% compromise distance matrix across subjects
% .samples
%
%
% Example:
% % (This example cannot be documentation tested using Octave,
% % since Octave does not allow for-loops with evalc)
% cosmo_skip_test_if_no_external('matlab');
% %
% ds=cosmo_synthetic_dataset('nsubjects',5,'nchunks',1,'ntargets',4);
% %
% % define neighborhood (here a searchlight with radius of 1 voxel)
% nbrhood=cosmo_spherical_neighborhood(ds,'radius',1,'progress',false);
% %
% % define measure
% measure=@cosmo_dissimilarity_matrix_measure;
% % each subject is a chunk
% ds.sa.chunks=ds.sa.subject;
% % compute DSM for each subject
% sp=cosmo_split(ds,'chunks');
% for k=1:numel(sp)
% sp{k}=cosmo_searchlight(sp{k},nbrhood,measure,'progress',false);
% sp{k}.sa.chunks=ones(6,1)*k;
% end
% % merge results
% dsms=cosmo_stack(sp);
% %
% r=cosmo_distatis(dsms,'return','distance','progress',false);
% cosmo_disp(r);
% %|| .samples
% %|| [ 0 0 0 0 0 0
% %|| 0.818 1.09 0.77 0.653 1.03 0.421
% %|| 0.869 1.3 1.06 1.04 0.932 1.07
% %|| : : : : : :
% %|| 1.16 0.889 0.99 0.631 1.48 0.621
% %|| 0.268 0.952 0.965 0.462 0.943 1.04
% %|| 0 0 0 0 0 0 ]@16x6
% %|| .fa
% %|| .center_ids
% %|| [ 1 2 3 4 5 6 ]
% %|| .i
% %|| [ 1 2 3 1 2 3 ]
% %|| .j
% %|| [ 1 1 1 2 2 2 ]
% %|| .k
% %|| [ 1 1 1 1 1 1 ]
% %|| .nvoxels
% %|| [ 3 4 3 3 4 3 ]
% %|| .radius
% %|| [ 1 1 1 1 1 1 ]
% %|| .quality
% %|| [ 0.685 0.742 0.617 0.648 0.757 0.591 ]
% %|| .nchunks
% %|| [ 5 5 5 5 5 5 ]
% %|| .a
% %|| .fdim
% %|| .labels
% %|| { 'i' 'j' 'k' }
% %|| .values
% %|| { [ 1 2 3 ] [ 1 2 ] [ 1 ] }
% %|| .sdim
% %|| .labels
% %|| { 'targets1' 'targets2' }
% %|| .values
% %|| { [ 1 [ 1
% %|| 2 2
% %|| 3 3
% %|| 4 ] 4 ] }
% %|| .vol
% %|| .mat
% %|| [ 2 0 0 -3
% %|| 0 2 0 -3
% %|| 0 0 2 -3
% %|| 0 0 0 1 ]
% %|| .dim
% %|| [ 3 2 1 ]
% %|| .xform
% %|| 'scanner_anat'
% %|| .sa
% %|| .targets1
% %|| [ 1
% %|| 2
% %|| 3
% %|| :
% %|| 2
% %|| 3
% %|| 4 ]@16x1
% %|| .targets2
% %|| [ 1
% %|| 1
% %|| 1
% %|| :
% %|| 4
% %|| 4
% %|| 4 ]@16x1
%
% Reference:
% - Abdi, H., Valentin, D., O?Toole, A. J., & Edelman, B. (2005).
% DISTATIS: The analysis of multiple distance matrices. In
% Proceedings of the IEEE Computer Society: International conference
% on computer vision and pattern recognition, San Diego, CA, USA
% (pp. 42?47).
%
% Notes:
% - DISTATIS tries to find an optimal compromise distance matrix across
% the different samples (participants)
% - Output can be reshape to matrix or array form using
% cosmo_unflatten(res,1)
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
