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. #
defaults.matrix_labels=cell(0);
opt=cosmo_structjoin(defaults,varargin{:});
if nargin<4, dim=2; end
switch dim
case 1
do_transpose=true;
attr_name='sa';
dim_name='sdim';
case 2
do_transpose=false;
attr_name='fa';
dim_name='fdim';
otherwise
error('illegal dim: must be 1 or 2');
end
if do_transpose
% switch samples and features
ndim=numel(dim_labels);
nfeatures=size(arr,ndim+1);
if nfeatures==1
arr=reshape(arr,[1 size(arr)]);
else
arr=shiftdim(arr,ndim);
end
dim_values=cellfun(@transpose,dim_values,'UniformOutput',false);
end
[samples,dim_values,attr]=flatten_features(arr, dim_labels, ...
dim_values, opt);
if do_transpose
samples=samples';
attr=transpose_attr(attr);
dim_values=cellfun(@transpose,dim_values,'UniformOutput',false);
end
ds=struct();
ds.samples=samples;
ds.(attr_name)=attr;
ds.a.(dim_name).labels=dim_labels;
ds.a.(dim_name).values=dim_values;
function attr=transpose_attr(attr)
keys=fieldnames(attr);
for k=1:numel(keys)
key=keys{k};
value=attr.(key);
attr.(key)=value';
end
function [samples,dim_values,attr]=flatten_features(arr, dim_labels, ...
dim_values, opt)
% helper function to flatten features
ndim=numel(dim_labels);
if ndim ~= numel(dim_values)
error('expected %d dimensions, found %d',ndim,numel(dim_values));
elseif numel(size(arr))>(ndim+1)
error('Array has %d dimensions, expected <= %d',...
numel(size(arr)),ndim+1);
end
% allocate space for output
attr=struct();
% number of values in remaining dimensions
% (supports the case that arr is of size [...,1]
[dim_sizes,dim_values]=get_dim_sizes(arr,dim_labels,dim_values,opt);
for dim=1:ndim
% set values for dim-th dimension
dim_label=dim_labels{dim};
dim_value=dim_values{dim};
nvalues=size(dim_value,2);
% set the indices
indices=1:nvalues;
% make an array lin_values that has size 1 in every dimension
% except for the 'dim'-th one, where it has size 'nvalues'.
singleton_size=ones(1,ndim);
singleton_size(dim)=nvalues;
if ndim==1
% reshape only works with >=2 dimensions
lin_values=indices;
else
lin_values=reshape(indices,singleton_size);
end
% now the lin_values have to be tiled (using repmat). The number of
% repeats is 'dim_sizes'('k') for all 'k' except for 'dim',
% where it is 1 (as it has 'nvalues' in that dimension already).
rep_size=dim_sizes;
rep_size(dim)=1;
rep_values=repmat(lin_values, rep_size(:)');
% store indices as a row vector.
attr.(dim_label)=reshape(rep_values, 1, []);
end
% get array and sample sizes
nsamples=size(arr,1);
nfeatures=prod(dim_sizes);
samples=reshape(arr, nsamples, nfeatures);
function [dim_sizes, dim_values]=get_dim_sizes(arr,dim_labels,dim_values,opt)
ndim=numel(dim_values);
dim_sizes=zeros(1,ndim);
for dim=1:ndim
dim_label=dim_labels{dim};
dim_value=dim_values{dim};
if cosmo_match({dim_label},opt.matrix_labels)
dim_size=size(dim_value,2);
else
if ~isvector(dim_value)
error(['Label ''%s'' (dimension %d) must be a vector, '...
'because it was not specified as a matrix '...
'dimension in the ''matrix_fields'' option'],...
dim_label, dim);
end
dim_size=numel(dim_value);
dim_values{dim}=dim_value(:)'; % make it a row vector
end
if dim_size ~= size(arr,dim+1)
error(['Label ''%s'' (dimension %d) has %d values, ',...
'expected %d based on the array input'],...
dim_label, dim, dim_size, size(arr,dim+1));
end
dim_sizes(dim)=dim_size;
end
