cosmo dim insert hdrΒΆ

function ds=cosmo_dim_insert(ds,dim,index,labels,values,attr,varargin)
% insert a dataset dimension
%
% ds_result=cosmo_dim_insert(ds,dim,index,labels,values,attr,...)
%
% Inputs:
%   ds                  dataset struct
%   dim                 dimension along which dimensions must be inserted,
%                       1=samples, 2=features
%   index               position at which dimension must be inserted,
%                       in .a.sdim (if dim==1) or .a.fdim (if dim==2)
%   labels              dimension labels
%   values              dimension values
%   attr                cell with values for .sa or .fa, or a struct with
%                       the fields that are in labels
%   'matrix_labels',m   (optional) any label for which the corresponding
%                       value is a matrix must be an element of the
%                       cellstring m. Currently this applies to the 'pos'
%                       field in MEEG source data
%
% Output:
%   ds_result           dataset struct with dim_labels removed from
%                       .a.{fdim,sdim} and .{fa,sa}.
%
% Example:
%     % generate tiny fmri dataset
%     ds=cosmo_synthetic_dataset();
%     %
%     % remove first two feature dimensions ('i' and 'j')
%     dim_labels=ds.a.fdim.labels(1:2);
%     dim_values=ds.a.fdim.values(1:2);
%     dsr=cosmo_dim_remove(ds,dim_labels);
%     %
%     % add them back in
%     ds_humpty=cosmo_dim_insert(dsr,2,1,dim_labels,dim_values,...
%                                             {ds.fa.i,ds.fa.j});
%     %
%     % the output is the same as the original dataset
%     isequal(ds,ds_humpty)
%
% Notes:
%   - this is a utility function, mostly intended for use by other
%     functions
%   - this function does not check for duplicate dimensions
%
% #   For CoSMoMVPA's copyright information and license terms,   #
% #   see the COPYING file distributed with CoSMoMVPA.           #