function [pca_samples,params]=cosmo_pca(samples,retain)
% Principal Component Analysis
%
% [pca_samples,params]=cosmo_pca(samples[,retain])
%
% Input:
% samples M x N numeric matrix
% retain (optional) number of components to retain;
% must be less than or equal to N. Default: N
%
% Output:
% pca_samples M x retain samples in Principal Component
% space, after samples have been centered
% params struct with fields:
% .coef M x retain Principal Component coefficients
% .mu M x 1 column-wise average of samples
% It holds that:
% samples=bsxfun(@plus,params.mu,...
% pca_samples*params.coef')
% .explained 1 x N Percentage of explained variance
%
%
% Examples:
% samples=[ 2.0317 -0.8918 -0.8258;...
% 0.5838 1.8439 1.1656;...
% -1.4437 -0.2617 -1.9207;...
% -0.5177 2.3387 0.4412;...
% 1.1908 -0.2040 -0.2088;...
% -1.3265 2.7235 0.1476];
% %
% % apply PCA, keeping two dimensions
% [pca_samples,params]=cosmo_pca(samples,2);
% %
% % show samples in PC space
% cosmo_disp(pca_samples);
% %|| [ -2.64 0.654
% %|| 0.923 1.43
% %|| -0.723 -2.48
% %|| 1.64 0.265
% %|| -1.46 0.569
% %|| 2.27 -0.438 ]
% %
% % show parameters
% cosmo_disp(params);
% %|| .coef
% %|| [ -0.512 0.744
% %|| 0.794 0.219
% %|| 0.328 0.632 ]
% %|| .mu
% %|| [ 0.0864 0.925 -0.2 ]
% %|| .explained
% %|| [ 66
% %|| 33.3
% %|| 0.676 ]
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
