function [arr, dim_labels, dim_values]=cosmo_unflatten(ds, dim, varargin)
% unflattens a dataset from 2 to (1+K) dimensions.
%
% [arr, dim_labels, dim_values]=cosmo_unflatten(ds, [dim, ][,...])
%
% Inputs:
% ds dataset structure, with fields:
% .samples PxQ for P samples and Q features.
% .a.Xdim.labels 1xK cell with string labels for each dimension,
% with X='s' for samples (dim=1) or X='f' for features
% (dim=2).
% .a.Xdim.values 1xK cell, with S_J values (J in 1:K) corresponding
% to the labels in each of the K dimensions.
% .Xa.(label) for each label in a.Xdim.labels it contains the
% sub-indices for the K dimensions. It is required
% that for every dimension J in 1:K, all values in
% ds.fa.(a.fdim.labels{J}) are in the range 1:S_K, and
% that every combination across labels is unique.
% dim dimension to be unflattened, either 1 (for samples)
% or 2 (for features; default)
% 'set_missing_to',s value to set missing values to (default: 0)
% '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.
%
% Returns:
% arr S_1 x ... x S_K x Q array if (dim==1), or
% P x S_1 x ... x S_K array if (dim==2), where
% Q=prod(S_*) if dim==1 and P=prod(S_*) if dim==2
% dim_labels the value of .a.Xdim.labels
% dim_values the value of .a.Xdim.values
%
% Example:
% % ds is an FMRI dataset with 6 samples, volumes are 3 x 2 x 5 voxels
% ds=cosmo_synthetic_dataset('size','normal','type','fmri');
% size(ds.samples)
% %|| [ 6 30 ]
% cosmo_disp(ds.a.fdim)
% %|| .labels
% %|| { 'i' 'j' 'k' }
% %|| .values
% %|| { [ 1 2 3 ] [ 1 2 ] [ 1 2 3 4 5 ] }
% %
% % flatten the dataset
% [unfl,labels,values]=cosmo_unflatten(ds);
% %
% % the unflattened dataset is of size 6 x 3 x 2 x 5
% size(unfl)
% %|| [ 6 3 2 5 ]
% cosmo_disp(labels)
% %|| { 'i' 'j' 'k' }
% cosmo_disp(values)
% %|| { [ 1 2 3 ] [ 1 2 ] [ 1 2 3 4 5 ] }
%
% % ds is a small dataset with 2 classes
% ds=cosmo_synthetic_dataset();
% %
% % compute all (2x2) split-half correlation values
% res=cosmo_correlation_measure(ds,'output','raw',...
% 'post_corr_func',[]);
% cosmo_disp(res)
% %|| .samples
% %|| [ 0.363
% %|| -0.404
% %|| -0.447
% %|| 0.606 ]
% %|| .sa
% %|| .half1
% %|| [ 1
% %|| 2
% %|| 1
% %|| 2 ]
% %|| .half2
% %|| [ 1
% %|| 1
% %|| 2
% %|| 2 ]
% %|| .a
% %|| .sdim
% %|| .labels
% %|| { 'half1' 'half2' }
% %|| .values
% %|| { [ 1 [ 1
% %|| 2 ] 2 ] }
% %
% % reshape the correlations into a square matrix
% [unfl,labels,values]=cosmo_unflatten(res,1);
% %
% % yields a 2x2x1 matrix (matlab omits the last, singleton dimension)
% cosmo_disp(unfl)
% %|| [ 0.363 -0.447
% %|| -0.404 0.606 ]
% %
% cosmo_disp(labels)
% %|| { 'half1' 'half2' }
% %
% cosmo_disp(values)
% %|| { [ 1 [ 1
% %|| 2 ] 2 ] }
%
%
% Notes:
% - A typical use case is mapping an fMRI or MEEG dataset struct
% back to a 3D or 4D array.
% - This function is the inverse of cosmo_flatten.
%
% See also: cosmo_flatten, cosmo_map2fmri, cosmo_map2meeg
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
if nargin<2 || isempty(dim), dim=2; end
if ~(isnumeric(dim) && isscalar(dim))
error('second argument must be numeric');
end
cosmo_check_dataset(ds);
defaults=struct();
defaults.set_missing_to=0;
defaults.matrix_labels=cell(0);
opt=cosmo_structjoin(defaults,varargin);
switch dim
case 1
cosmo_isfield(ds,{'a.sdim','samples','sa'},true);
do_transpose=true;
a_dim=ds.a.sdim;
attr=ds.sa;
case 2
cosmo_isfield(ds,{'a.fdim','samples','fa'},true);
do_transpose=false;
a_dim=ds.a.fdim;
attr=ds.fa;
otherwise
error('dim must be 1 or 2');
end
samples=ds.samples;
if do_transpose
samples=samples';
a_dim.values=cellfun(@transpose,a_dim.values,...
'UniformOutput',false);
end
[arr, dim_labels,dim_values]=unflatten_features(samples, ...
a_dim, attr, opt);
if do_transpose
arr=shiftdim(arr,1);
dim_values=cellfun(@transpose,dim_values,'UniformOutput',false);
end
function [arr, dim_labels, dim_values]=unflatten_features(samples, ...
a_dim, attr, opt)
nsamples=size(samples,1);
dim_labels=a_dim.labels;
dim_values=a_dim.values;
% number of feature dimensions
ndim=numel(dim_labels);
% get sub indices for each feature dimension
sub_indices=cellfun(@(x)attr.(x), dim_labels, 'UniformOutput', false);
% get dimension values
[dim_sizes, dim_values]=get_dim_sizes(dim_values, dim_labels, opt);
max_indices=cellfun(@max,sub_indices);
too_small_dim=find(max_indices(:)>dim_sizes(:),1);
if ~isempty(too_small_dim)
error(['dimension with label %s has %d dimension labels,'...
'but attribute indexes up to %d'],...
dim_labels{too_small_dim}, dim_sizes(too_small_dim),...
max_indices(too_small_dim));
end
% allocate space for output - one cell per sample
arr_cell=cell(1,nsamples);
% convert sub indices to linear indices
if ndim==1
lin_indices=sub_indices{1};
else
lin_indices=sub2ind(dim_sizes,sub_indices{:});
end
unq_lin_indices=unique(lin_indices);
if numel(lin_indices)~=numel(unq_lin_indices)
h=histc(lin_indices,unq_lin_indices);
duplicate=unq_lin_indices(find(h>1,1));
two_duplicate_pos=find(lin_indices==duplicate,2);
error('Duplicate features at #%d and #%d', ...
two_duplicate_pos(1), two_duplicate_pos(2));
end
% allocate space in 'ndim'-space for each sample,
% but with a first singleton dimension as that one
% is used for the samples
arr_dim=zeros([1, dim_sizes]);
% process each sample
for k=1:nsamples
% make empty
arr_dim(:)=opt.set_missing_to;
% assign to proper location
arr_dim(lin_indices)=samples(k, :);
% store result for this sample
arr_cell{k}=arr_dim;
end
% combine all samples
arr=cat(1, arr_cell{:});
function [dim_sizes, dim_values]=get_dim_sizes(dim_values, dim_labels, opt)
ndim=numel(dim_labels);
if numel(dim_values)~=ndim
error(['size mismatch between number of dimension values (%d)'...
'and dimension labels (%d)'],...
numel(dim_values), ndim);
end
% number of elements in each dimension
dim_sizes=zeros(1,ndim);
% go over dimensions
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_labels'' option'],...
dim_label, dim);
end
dim_size=numel(dim_value);
dim_values{dim}=dim_value(:)'; % make it a row vector
end
dim_sizes(dim)=dim_size;
end
