cosmo flatten hdr

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.           #