function ds=cosmo_flatten(arr, dim_labels, dim_values, dim, varargin)
% flattens an arbitrary array to a dataset structure
%
% ds=cosmo_flatten(arr, dim_labels, dim_values, dim[, ...])
%
% Inputs:
% arr S_1 x ... x S_K x Q input array if (dim==1), or
% P x S_1 x ... x S_K input array if (dim==2)
% dim_labels 1xK cell containing labels for each dimension but
% the first one.
% dim_values 1xK cell with S_J values (J in 1:K) corresponding to
% the labels in each of the K dimensions.
% dim dimension along which to flatten, either 1 (samples)
% or 2 (features; default)
% 'matrix_labels',m Allow labels in the cell string m to be matrices
% rather than vectors. Currently the only use case is
% the 'pos' attribute for MEEG source space data.
%
% Output:
% ds dataset structure, with fields:
% .samples PxQ data for P samples and Q features.
% .a.dim.labels Kx1 cell with the values in dim_labels
% .a.dim.values Kx1 cell with the values in dim_values. The i-th
% element has S_i elements along dimension dim
% .fa.(label) for each label in a.dim.labels it contains the
% .samples PxQ data for P samples and Q features, where
% Q=prod(S_*) if dim==1 and P=prod(S_*) if dim==2
% .a.Xdim.labels 1xK cell with the values in dim_labels (X=='s' if
% dim==1, and 'f' if dim==2); the M-th element must
% have S_M values.
% .a.Xdim.values 1xK cell with the values in dim_values; the M-th
% element must have S_M values.
% .Xa.(label) for each label in a.Xdim.labels it contains the
% sub-indices for the K dimensions. It is ensured
% that for every dimension J in 1:K, all values in
% ds.fa.(a.dim.labels{J}) are in the range 1:S_K.
%
% Examples:
% % typical usage: flatten features in 2x3x5 array, 1 sample
% data=reshape(1:30, [1 2,3,5]);
% ds=cosmo_flatten(data,{'i','j','k'},{1:2,1:3,{'a','b','c','d','e'}});
% cosmo_disp(ds)
% %|| .samples
% %|| [ 1 2 3 ... 28 29 30 ]@1x30
% %|| .fa
% %|| .i
% %|| [ 1 2 1 ... 2 1 2 ]@1x30
% %|| .j
% %|| [ 1 1 2 ... 2 3 3 ]@1x30
% %|| .k
% %|| [ 1 1 1 ... 5 5 5 ]@1x30
% %|| .a
% %|| .fdim
% %|| .labels
% %|| { 'i' 'j' 'k' }
% %|| .values
% %|| { [ 1 2 ] [ 1 2 3 ] { 'a' 'b' 'c' 'd' 'e' } }
%
% % flatten samples in 1x1x2x3 array, 5 features
% data=reshape(1:30, [1,1,2,3,5]);
% ds=cosmo_flatten(data,{'i','j','k','m'},{1,'a',(1:2)',(1:3)'},1);
% cosmo_disp(ds);
% %|| .samples
% %|| [ 1 7 13 19 25
% %|| 2 8 14 20 26
% %|| 3 9 15 21 27
% %|| 4 10 16 22 28
% %|| 5 11 17 23 29
% %|| 6 12 18 24 30 ]
% %|| .sa
% %|| .i
% %|| [ 1
% %|| 1
% %|| 1
% %|| 1
% %|| 1
% %|| 1 ]
% %|| .j
% %|| [ 1
% %|| 1
% %|| 1
% %|| 1
% %|| 1
% %|| 1 ]
% %|| .k
% %|| [ 1
% %|| 2
% %|| 1
% %|| 2
% %|| 1
% %|| 2 ]
% %|| .m
% %|| [ 1
% %|| 1
% %|| 2
% %|| 2
% %|| 3
% %|| 3 ]
% %|| .a
% %|| .sdim
% %|| .labels
% %|| { 'i' 'j' 'k' 'm' }
% %|| .values
% %|| { [ 1 ] 'a' [ 1 [ 1
% %|| 2 ] 2
% %|| 3 ] }
%
%
% Notes:
% - Intended use is for flattening fMRI or MEEG datasets
% - This function is the inverse of cosmo_unflatten.
%
% See also: cosmo_unflatten, cosmo_fmri_dataset, cosmo_meeg_dataset
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
