function [ds,attr,values]=cosmo_dim_remove(ds,dim_labels)
% remove a dataset dimension
%
% [ds_result,attr,values]=cosmo_dim_remove(ds,dim_labels)
%
% Inputs:
% ds dataset struct
% dim_labels cellstring with label(s) to remove. A single
% string s is interpreted as s{1}
%
% Output:
% ds_result dataset struct with dim_labels removed from
% .a.{fdim,sdim} and .{fa,sa}.
% attr struct based on .{fa,sa} but only with the fields in
% dim_labels
% values Nx1 cell based on .a.{fdim,sdim}.values, but only
% with the fields in dim_labels. If dim_labels is a
% string, then the output is values{1}.
%
% Example:
% % generate tiny fmri dataset
% ds=cosmo_synthetic_dataset();
% cosmo_disp(ds.a.fdim);
% %|| .labels
% %|| { 'i' 'j' 'k' }
% %|| .values
% %|| { [ 1 2 3 ] [ 1 2 ] [ 1 ] }
% cosmo_disp(ds.fa);
% %|| .i
% %|| [ 1 2 3 1 2 3 ]
% %|| .j
% %|| [ 1 1 1 2 2 2 ]
% %|| .k
% %|| [ 1 1 1 1 1 1 ]
% % remove 'j' and 'k' dimension label; only 'i' is left
% [ds_without_jk,attr,values]=cosmo_dim_remove(ds,{'j','k'});
% cosmo_disp(ds_without_jk.a.fdim);
% %|| .labels
% %|| { 'i' }
% %|| .values
% %|| { [ 1 2 3 ] }
% cosmo_disp(ds_without_jk.fa);
% %|| .i
% %|| [ 1 2 3 1 2 3 ]
% cosmo_disp(attr)
% %|| .j
% %|| [ 1 1 1 2 2 2 ]
% %|| .k
% %|| [ 1 1 1 1 1 1 ]
% cosmo_disp(values)
% %|| { [ 1 2 ] [ 1 ] }
%
% See also: cosmo_dim_transpose
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
