function [pca_ds, pca_params]=cosmo_map_pca(ds, varargin)
% normalize dataset either by estimating or applying estimated parameters
%
% [pca_ds, pca_params]=cosmo_map_pca(ds[, ...])
%
% Inputs
% ds a dataset struct with field .samples of
% numeric array of size PxQ, or a
% numeric array of that size
% 'pca_params',p previously estimated pca parameters using
% the 'pca_params' output result from a
% previous call to this function
% 'pca_explained_count',c retain only the first components
% 'pca_explained_ratio',r retain the first components that explain
% (r * 100)% of the
% variance (value between 0 and 1, where 1
% retains all components)
% 'max_feature_count',mx Raise an error if Q>mx (default: mx=1000).
% This protects against possible comutations
% that require much memory and/or time when
% computing singular value decompositions
%
% Output
% pca_ds a dataset struct similar to ds, but
% with .samples data transformed using pca.
% If the input was a numeric array, then
% pca_ds is numeric as well
% params estimated parameters for pca. These can be
% re-used for a second pca step of an
% independent dataset. For example,
% parameters can be estimated from a
% training dataset and then applied to a
% testing dataset
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
