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