function [winners,classes]=cosmo_winner_indices(pred)
% Given multiple predictions, get indices that were predicted most often.
%
% [winners,classes]=cosmo_winner_indices(pred)
%
% Input:
% pred PxQ prediction values for Q features and P
% predictions per feature. Values of NaN are ignored,
% i.e. can never be a winner.
%
% Output:
% winners Px1 indices of classes that occur most often.
% winners(k)==w means that no value in
% classes(pred(k,:)) occurs more often than classes(w).
% classes The sorted list of unique predicted values, across
% all non-ignored (non-NaN) values in pred.
%
% Examples:
% % a single prediction, with the third one missing
% pred=[4; 4; NaN; 5];
% [p, c]=cosmo_winner_indices(pred);
% p'
% %|| [1 1 NaN 2]
% c'
% %|| [4, 5]
%
% % one prediction per fold (e.g. using cosmo_nfold_partitioner)
% pred=[4 NaN NaN; 6 NaN NaN; NaN 3 NaN; NaN NaN NaN; NaN NaN 3];
% [p, c]=cosmo_winner_indices(pred);
% p'
% %|| [2, 3, 1, NaN, 1]
% c'
% %|| [3 4 6]
%
% % given up to three predictions each for eight samples, compute
% % which predictions occur most often. NaNs are ignored.
% pred=[4 4 4;4 5 6;6 5 4;5 6 4;4 5 6; NaN NaN NaN; 6 0 0;0 0 NaN];
% [p, c]=cosmo_winner_indices(pred);
% p'
% %|| [2, 3, 4, 2, 3, NaN, 1, 1]
% c'
% %|| [0, 4, 5, 6]
%
% Notes:
% - The typical use case is combining results from multiple classification
% predictions, such as in binary support vector machines (SVMs) and
% cosmo_crossvalidate
% - The current implementation selects a winner pseudo-randomly (but
% deterministically) and (presumably) unbiased in case of a tie between
% multiple winners. That is, using the present implementation, repeatedly
% calling this function with identical input yields identical output,
% but unbiased with respect to which class is the 'winner' sample-wise.
% - Samples with no predictions are assigned a value of NaN.
%
% See also: cosmo_classify_matlabsvm, cosmo_crossvalidate
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
