function f_ds=cosmo_fx(ds, f, split_by, dim, check)
% apply a function to unique combinations of .sa or .fa values
%
% f_ds=cosmo_fx(ds, f, split_by, dim)
%
% Inputs:
% ds dataset struct
% f function handle
% split_by string or cell of strings of labels of sample or feature
% attributes (default: [])
% dim dimension on which split is done (1=samples (default),
% 2=features)
% check boolean indicating whether the input ds is checked as being
% a proper dataset (default: true)
%
% Returns:
% f_ds dataset struct where the samples are the result of applying
% f to the samples of each unique combiniation of attributes
% in split_by
%
% Example:
% % ds is a dataset with several repeats of each target. Compute the
% % average sample value for each unique target:
% ds=cosmo_synthetic_dataset();
% f_ds=cosmo_fx(ds, @(x)mean(x,1), 'targets');
% cosmo_disp(f_ds.samples)
% %|| [ 0.593 -0.452 -0.985 2 -0.39 0.312
% %|| -0.42 2.3 0.585 0.503 2.46 -0.199 ]
% cosmo_disp(f_ds.sa)
% %|| .chunks
% %|| [ 1
% %|| 1 ]
% %|| .targets
% %|| [ 1
% %|| 2 ]
%
% % Compute the average sample value for each unique combination
% % of targets and chunks:
% ds=cosmo_synthetic_dataset('nreps',4);
% size(ds.samples)
% %|| 24 6
% f_ds=cosmo_fx(ds, @(x)mean(x,1), {'targets','chunks'});
% size(f_ds.samples)
% %|| 6 6
%
% % Downsample MEEG data by a factor of two
% ds=cosmo_synthetic_dataset('type','meeg','size','small');
% size(ds.samples)
% %|| 6 6
% downsampling_factor=2;
% ds.fa.time_downsamp=ceil(ds.fa.time/downsampling_factor);
% %
% % compute average for each unique combination of channel and
% % time_downsamp
% ds_downsamp=cosmo_fx(ds, @(x) mean(x,2), {'chan','time_downsamp'}, 2);
% ds_downsamp=cosmo_dim_prune(ds_downsamp); % update dim attributes
% size(ds_downsamp.samples)
% %|| 6 3
%
% See also: cosmo_split, cosmo_stack
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
