function is_ok=cosmo_check_partitions(partitions, ds, varargin)
% check whether partitions are balanced and not double-dippy
%
% cosmo_check_partitions(partitions, ds, varargin)
%
% Inputs:
% partitions struct with partitions, e.g. from
% cosmo_{nfold,oddeven,nchoosek}_partitioner
% ds dataset struct with fields .sa.{targets,chunks}
% opt (optional) struct with optional field:
% .unbalanced_partitions_ok if set to true, then unbalanced
% partitions (with a different number of
% targets of each class in a chunk) is ok
% Output:
% is_ok boolean, true if partitions are ok
%
% Throws:
% - an error if partitions are double dippy or (unless specified in opt)
% not balanced
%
% Examples:
% ds=struct();
% ds.samples=zeros(9,2);
% ds.sa.targets=[1 1 2 2 2 3 3 3 3]';
% ds.sa.chunks=[1 2 2 1 1 1 2 2 2]';
% % make unbalanced partitions
% partitions=cosmo_nfold_partitioner(ds);
% cosmo_check_partitions(partitions,ds);
% %|| error('Unbalance in partition 1 [...]')
% %
% % disable unbalanced check
% cosmo_check_partitions(partitions,ds,'unbalanced_partitions_ok',true)
% %|| true
% %
% % balance partitions and check without unbalanced check
% partitions=cosmo_balance_partitions(partitions,ds);
% cosmo_check_partitions(partitions,ds,'unbalanced_partitions_ok',false)
% %|| true
% %
% % make the partitions double dippy
% partitions.train_indices{1}=partitions.test_indices{1};
% cosmo_check_partitions(partitions,ds,'unbalanced_partitions_ok',true)
% %|| error('double dipping in fold 1: chunk 1 is in train and test set')
% %
% % make partitions empty
% partitions.train_indices{1}=[];
% cosmo_check_partitions(partitions,ds);
% %|| error('partition 1: .train_indices are empty')
% %
% % partitions have values outside range
% partitions.train_indices{1}=100;
% cosmo_check_partitions(partitions,ds);
% %|| error('partition 1: .train_indices are outside range 1..9');
% %
% % use non-integers
% partitions.train_indices{1}=1.5;
% cosmo_check_partitions(partitions,ds);
% %|| error('partition 1: .train_indices are not integers');
%
% Notes:
% - the reason to require balancing by default is that chance level is
% 1/nclasses, which is useful for many subsequent analyses.
% - if this function raises an exception for partitions, consider running
% partitions=cosmo_balance_partitions(partitions,...).
%
% See also: cosmo_balance_partitions, cosmo_nfold_partitioner
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
