function samples=cosmo_sample_unique(k,n,count,varargin)
% sample without replacement from subsets of integers in balanced manner
%
% function samples=cosmo_sample_unique(k,n[,count,varargin])
%
% Inputs:
% k number of elements to return in each subset
% n size of integer range from which to sample
% count number of subsets to select (default: 1)
% 'seed', s Use seed s for pseudo-random sampling (optional). If this
% option is omitted, then different calls to this function
% may (usually: will) return different results
%
%
% Output:
% samples k x count indices, all in the range 1:n, with the following
% properties:
% - each value is randomly sampled from the range 1:n
% - each column forms a subset of 1:n (without repeats)
% - across the entire matrix, each value in the range 1:n
% occurs approximately equally often
%
% Example:
% % get 4 random subsets of 3 elements in range 1:7
% % (in this example a seed is used to get the same result upon every
% % function call)
% cosmo_sample_unique(3,6,4,'seed',3)
% %|| 1 2 1 2
% %|| 3 5 3 4
% %|| 4 6 5 6
%
% Notes:
% - this is a utility function; it does not work on dataset structures.
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
