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);

