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