function ds=cosmo_dim_prune(ds, varargin)
% prune dataset dimension values that are not used after slicing
%
% ds=cosmo_dim_prune(ds, labels, dims)
%
% Inputs:
% ds dataset struct
% 'labels; l labels of dimensions to be pruned. If not provided
% all labels are pruned.
% 'dim',d dimension(s) along which pruning takes place,
% 1=sample dimension, 2=feature dimension.
% Default: [1 2]
% 'matrix_labels',m Names of feature dimensions that store dimension
% information in matrix form. (Currently the only use
% case is m={'pos'} for MEEG source datasets.)
%
% Output:
% ds dataset struct with pruned dimension values.
%
% Examples:
% % For an MEEG dataset, get a selection of some channels
% ds=cosmo_synthetic_dataset('type','meeg','size','huge');
% cosmo_disp(ds.a.fdim.values{1},'edgeitems',2);
% %|| { 'MEG0111' 'MEG0112' ... 'MEG2642' 'MEG2643' }@1x306
% cosmo_disp(ds.fa.chan)
% %|| [ 1 2 3 ... 304 305 306 ]@1x5202
% %
% % select channels
% msk=cosmo_dim_match(ds,'chan',{'MEG1843','MEG2441'});
% ds_sel=cosmo_slice(ds,msk,2);
% %
% % apply pruning, so that the .fa.chan goes from 1:nf, with nf the
% % number of channels that were selected
% ds_pruned=cosmo_dim_prune(ds_sel);
% %
% % show result
% cosmo_disp(ds_pruned.a.fdim.values{1}); % 'chan' is first dimension
% %|| { 'MEG1843'
% %|| 'MEG2441' }
% cosmo_disp(ds_pruned.fa.chan)
% %|| [ 1 2 1 ... 2 1 2 ]@1x34
% %
% % For the same MEEG dataset, get a selection of time points between 0
% % and .3 seconds. A function handle is used to select the timepoints
% selector=@(x) 0<=x & x<=.3; % use element-wise logical-and
% msk=cosmo_dim_match(ds,'time',selector);
% ds_sel=cosmo_slice(ds,msk,2);
% ds_pruned=cosmo_dim_prune(ds_sel);
% %
% % show result
% cosmo_disp(ds_pruned.a.fdim.values{2}); % 'time' is second dimension
% %|| [ 0 0.05 0.1 ... 0.2 0.25 0.3 ]@1x7
% cosmo_disp(ds_pruned.fa.time)
% %|| [ 1 1 1 ... 7 7 7 ]@1x2142
% %
% % For the same MEEG dataset, compute a conjunction mask of the
% % channels and time points selected above
% msk=cosmo_dim_match(ds,'chan',{'MEG1843','MEG2441'},'time',selector);
% ds_sel=cosmo_slice(ds,msk,2);
% ds_pruned=cosmo_dim_prune(ds_sel);
% %
% % show result
% cosmo_disp(ds_pruned.a.fdim);
% %||.labels
% %|| { 'chan'
% %|| 'time' }
% %||.values
% %|| { { 'MEG1843' 'MEG2441' }
% %|| [ 0 0.05 0.1 ... 0.2 0.25 0.3 ]@1x7 }
% cosmo_disp(ds_pruned.fa.chan)
% %|| [ 1 2 1 ... 2 1 2 ]@1x14
% cosmo_disp(ds_pruned.fa.time)
% %|| [ 1 1 2 ... 6 7 7 ]@1x14
% Notes:
% - Using this function makes sense for MEEG data, but not at all
% for fMRI or surface data.
% - When using this function for MEEG data after slicing (using
% cosmo_dim_match and cosmo_slice), applying this function ensures that
% removed values in a dimension are not mapped back to the original
% input size when using cosmo_map2meeg.
% - When using this function with MEEG source data that has a 'pos' field,
% use
% cosmo_dim_prune(ds,'matrix_labels',{'pos'})
%
% to prune the 'pos' feature dimension (if it needs pruning)
%
% See also: cosmo_dim_match
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
opt=process_opt(varargin{:});
cosmo_check_dataset(ds);
dim=opt.dim;
ndim=numel(dim);
opt=rmfield(opt,'dim');
for k=1:ndim
ds=prune_single_dim(ds, dim(k), opt);
end
function ds=prune_single_dim(ds, dim, opt)
labels=opt.labels;
infixes='sf';
infix=infixes(dim);
attr_name=[infix 'a'];
dim_name=[infix 'dim'];
if cosmo_isfield(ds, ['a.' dim_name '.labels'])
use_dim_labels=isempty(labels);
if use_dim_labels
labels=ds.a.(dim_name).labels;
end
if ~iscellstr(labels)
error('expected cell with labels, or single string');
end
% helper to ensure that slicing output has proper size
nvalues=size(ds.samples,dim);
shape_arg={[],[]};
shape_arg{dim}=nvalues;
in_shape=@(x) reshape(x, shape_arg{:});
nlabels=numel(labels);
for k=1:nlabels
label=labels{k};
[dim_, index]=cosmo_dim_find(ds,label,true);
if use_dim_labels
assert(dim_==dim);
elseif dim~=dim_
continue;
end
values=ds.a.(dim_name).values{index};
attr=ds.(attr_name).(label);
[unq_idxs,unused,map_idxs]=unique(attr);
values=get_unique(label, dim, values, unq_idxs, opt);
ds.a.(dim_name).values{index}=values;
ds.(attr_name).(label)=in_shape(map_idxs);
end
end
function values=get_unique(label, dim, values, unq_idxs, opt)
if sum(size(values)>1)>1
if cosmo_match({label},opt.matrix_labels)
if dim==1
values=values(unq_idxs,:);
else
values=values(:,unq_idxs);
end
else
msg=sprintf(['Values for dimension ''%s'' is a matrix, but '...
'''%s'' was not specified as a an element '...
'of the ''matrix_labels'' option.'],...
label,label);
if strcmp(label,'pos')
msg=sprintf(['%s\nIf this is an MEEG source dataset, '...
'consider using %s(...,'...
'''matrix_labels'',{''pos''})'],...
msg,mfilename());
end
error(msg);
end
else
values=values(unq_idxs);
values=values(:);
if dim==2
values=values';
end
end
function [opt]=process_opt(varargin)
default=struct();
default.labels={};
default.dim=[1 2];
default.matrix_labels={};
opt=cosmo_structjoin(default,varargin{:});
if any(~cosmo_match(opt.dim,[1 2]))
error('''dims'' must be 1 or 2');
end
if ~iscellstr(opt.matrix_labels)
error('''matrix_labels'' option must be a cellstring');
end
