function [balanced_ds,idxs,classes]=cosmo_balance_dataset(ds,varargin)
% sub-sample a dataset to have an equal number of samples for each target
%
% [balanced_ds,idxs,classes]=cosmo_balance_dataset(ds)
%
% Inputs:
% ds dataset struct with fields .samples,
% .sa.targets and .sa.chunks. All values in
% .sa.chunks must be different from each other.
% 'sample_balancer', f (optional)
% function handle with signature
% [idxs,classes]=f(targets,seed)
% where idxs is a SxC vector with indices for C
% classes and S targets per class. If omitted a
% builtin function is used.
% 'seed', s (optional, default=1)
% Seed to use for pseudo-random number generation
%
% Output:
% balanced_ds dataset with a subset of the samples from ds
% so that each target occurs equally often.
% Selection is (by default) done in a
% pseudo-determistic manner.
% idxs SxC vector indicating which
% classes Cx1 vector containing unique class labels
%
% Notes:
% - this function is to be used with MEEG datasets. it is not intended
% for fMRI data.
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
