function ds = cosmo_dim_transpose(ds, dim_labels, target_dim, target_pos)
% move a dataset dimension from samples to features or vice versa
%
% ds_tr=cosmo_dim_transpose(ds, dim_labels[, target_dim, target_pos])
%
% Inputs:
% ds dataset struct
% dim_labels a single dimension label, or a cell with dimension
% labels. If target_dim is 1 [or 2], then all labels in
% dim_labels must be present in ds.a.fdim[sdim].values,
% and all labels in dim_labels must be a fieldname of
% ds.fa[sa].
% target_dim (optional) indicates that the dimensions in dim_labels
% must be moved from features to samples (if
% target_dim==1) or from samples to features (if
% target_dim==2). If omitted, it is deduced from
% dim_labels.
% target_pos (optional) the position which the first label in
% dim_labels must occupied after the transpose.
%
% Output:
% ds_tr dataset struct where all labels in dim_labels are
% in ds_tr.a.sdim[fdim] (if target_dim is 1 [or 2]), and
% where the fieldnames of ds_tr.sa[fa] is a superset of
% dim_labels.
% A field .fa.transpose_ids [.sa.transpose_ids] is added
% indicating the original feature [sample] id (column
% [row]) that the samples belonged too.
%
% Examples:
% ds=cosmo_synthetic_dataset('type','timefreq');
% % dataset attribute dimensions are
% % (<empty> [samples]) x (chan x freq x time [features])
% cosmo_disp(ds.a.fdim)
% %|| .labels
% %|| { 'chan'
% %|| 'freq'
% %|| 'time' }
% %|| .values
% %|| { { 'MEG0111' 'MEG0112' 'MEG0113' }
% %|| [ 2 4 ]
% %|| [ -0.2 ] }
% % transpose 'time' from features to samples
% ds_tr_time=cosmo_dim_transpose(ds,'time');
% % dataset attribute dimensions are (time) x (chan x freq)
% cosmo_disp({ds_tr_time.a.sdim,ds_tr_time.a.fdim})
% %|| { .labels .labels
% %|| { 'time' } { 'chan'
% %|| .values 'freq' }
% %|| { [ -0.2 ] } .values
% %|| { { 'MEG0111' 'MEG0112' 'MEG0113' }
% %|| [ 2 4 ] } }
% % using the defaults, chan is moved from features to samples, and
% % added at the end of .a.sdim.labels
% ds_tr_time_chan=cosmo_dim_transpose(ds_tr_time,'chan');
% % dataset attribute dimensions are (time x chan) x (freq)
% cosmo_disp({ds_tr_time_chan.a.sdim,ds_tr_time_chan.a.fdim})
% %|| { .labels .labels
% %|| { 'time' 'chan' } { 'freq' }
% %|| .values .values
% %|| { [ -0.2 ] { 'MEG0111' { [ 2 4 ] }
% %|| 'MEG0112'
% %|| 'MEG0113' } } }
% % when setting the position explicitly, chan is moved from features to
% % samples, and inserted to the first position in .a.sdim.labels
% ds_tr_chan_time=cosmo_dim_transpose(ds_tr_time,'chan',1,1);
% % dataset attribute dimensions are (chan x time) x (freq)
% cosmo_disp({ds_tr_chan_time.a.sdim,ds_tr_chan_time.a.fdim})
% %|| { .labels .labels
% %|| { 'chan' 'time' } { 'freq' }
% %|| .values .values
% %|| { { 'MEG0111' [ -0.2 ] { [ 2 4 ] }
% %|| 'MEG0112'
% %|| 'MEG0113' } } }
% %
% % this moves the time dimension back to the feature dimension.
% ds_orig=cosmo_dim_transpose(ds_tr_time,'time');
% cosmo_disp(ds_orig.a.fdim)
% %|| .labels
% %|| { 'chan'
% %|| 'freq'
% %|| 'time' }
% %|| .values
% %|| { { 'MEG0111' 'MEG0112' 'MEG0113' }
% %|| [ 2 4 ]
% %|| [ -0.2 ] }
%
%
% Notes:
% - This function is aimed at MEEG datasets (and for fMRI datasets with a
% time dimension), so that time can be made a sample dimension
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
if ischar(dim_labels)
dim_labels = {dim_labels};
elseif ~iscellstr(dim_labels)
error('input must be string or cell of strings');
end
if nargin < 4
target_pos = 0;
end
if nargin < 3
target_dim = find_target_dim(ds, dim_labels);
end
attr_name = dim2attr_name(target_dim);
% split dataset by dim_labels
source_dim = 3 - target_dim;
sp = cosmo_split(ds, dim_labels, source_dim);
% move attribute for each split
n = numel(sp);
for k = 1:n
sp{k} = copy_attr(sp{k}, dim_labels, target_dim);
end
% join splits
ds = cosmo_stack(sp, target_dim, 'unique');
% remove dimension from source_dim
[ds, unused, values] = cosmo_dim_remove(ds, dim_labels);
cell_transpose = @(c)cellfun(@(x)x', c, 'UniformOutput', false)';
values_tr = cell_transpose(values);
attr_tr = ds.(attr_name);
% insert dimension in target_dim
ds = cosmo_dim_insert(ds, target_dim, target_pos, ...
dim_labels, values_tr, attr_tr);
% ensure all kosher
cosmo_check_dataset(ds);
function target_dim = find_target_dim(ds, dim_labels)
for j = 1:numel(dim_labels)
source_dim_j = cosmo_dim_find(ds, dim_labels{j});
if j == 1
source_dim = source_dim_j;
elseif source_dim_j ~= source_dim
error('labels %s and %s do not share the same dimension', ...
dim_labels{1}, dim_labels{j});
end
end
target_dim = 3 - source_dim;
function prefix = dim2prefix(dim)
prefixes = 'sf';
prefix = prefixes(dim);
function attr_name = dim2attr_name(dim)
% returns 'sa' or 'fa'
attr_name = [dim2prefix(dim) 'a'];
function ds = copy_attr(ds, dim_labels, target_dim)
% copy between .fa and .sa
source_dim = 3 - target_dim;
src_name = dim2attr_name(source_dim);
trg_name = dim2attr_name(target_dim);
trg_size = [1 1];
trg_size(target_dim) = size(ds.samples, target_dim);
for k = 1:numel(dim_labels)
dim_label = dim_labels{k};
v = ds.(src_name).(dim_label);
% must all have the same value (otherwise cosmo_split is broken)
assert(~isempty(v));
unq = v(1);
assert(all(unq == v(:)));
ds.(trg_name).(dim_label) = repmat(unq, trg_size);
end
ds.(src_name) = rmfield(ds.(src_name), dim_labels);
% add transpose_ids, so that the input can be reconstructed
% even after permutations of rows or columns
attr_label = 'transpose_ids';
src_size = [1 1];
src_size(source_dim) = size(ds.samples, source_dim);
ds.(src_name).(attr_label) = reshape(1:max(src_size), src_size);
