<!doctype s-function-doc system "s-function-doc.dtd" [
<!entity % S-OLD "INCLUDE">
]
>
<s-function-doc>

<s-topics>
<s-topic> princompRob </s-topic>
</s-topics>

<s-title>
Robust Principal Component Analysis
</s-title>

<s-description>
Returns an object of class <s-expression>princompRob</s-expression>
containing the standard deviations of the principal components, the
loadings, and, optionally, the scores.  The principal components are
calculated from a robust estimate of the covariance matrix.
</s-description>

<s-usage>
<s-old-style-usage>
princompRob(x, data = NULL, covlist = NULL, scores = T, corr = F,
na.action, subset, estim = "auto", control = covRob.control(estim, ...),
...)
</s-old-style-usage>
</s-usage>

<s-args-required>
at least one of <s-expression>x</s-expression>,
<s-expression>data</s-expression>, or <s-expression>covlist</s-expression>
must be given.
</s-args-required>

<s-args-optional>
<s-arg name="x">
a matrix, data frame or formula.  If a matrix, the columns should
correspond to variables and the rows to observations.  If a formula, no
variables may appear on the left (response) side.
</s-arg>

<s-arg name="data">
a data frame or matrix.  This is usually used only when
<s-expression>x</s-expression> is a formula, though it may be used instead
of <s-expression>x</s-expression>.
</s-arg>

<s-arg name="covlist">
a list of the form returned by <s-expression>cov.wt</s-expression> or
<s-expression>cov.mve</s-expression>.  Components must include
<s-expression>center</s-expression> and <s-expression>cov</s-expression>.
A <s-expression>cor</s-expression> component will not be used, however, an
<s-expression>n.obs</s-expression> will be used it present.  WARNING: if
the <s-expression>covlist</s-expression> does not contain a robust estimate
of the covariance matrix then the principal component analysis will not be
robust.
</s-arg>

<s-arg name="scores">
logical value or integer. If <s-expression>scores=T</s-expression> then a
matrix of the scores for all of the components is returned.  If
<s-expression>scores</s-expression> is numeric, then scores and loadings
for the first scores components are returned.  If
<s-expression>scores=F</s-expression>, then no scores are computed.
</s-arg>

<s-arg name="corr">
logical flag: if <s-expression>TRUE</s-expression>, then the principal
components are based on the correlation matrix rather than the covariance
matrix. That is, the variables are scaled to have unit variance.
</s-arg>

<s-arg name="na.action">
function to handle missing values. The default is to create an error if
missing values are found.
</s-arg>

<s-arg name="subset">
the subset of the observations to use.
</s-arg>

<s-arg name="estim">
the robust estimator used by covRob. The choices are: "mcd" for the Fast
MCD algorithm of Rousseeuw and Van Driessen, "donostah" for the
Donoho-Stahel projection based estimator, "M" for the constrained M
estimator provided by Rocke, "pairwiseQC" for the quadrant correlation
based pairwise estimator, and "pairwiseGK" for the Gnanadesikan-Kettenring
pairwise estimator. The default "auto" selects from "donostah", "mcd", and
"pairwiseQC" with the goal of producing a good estimate in a resonable
amount of time.
</s-arg>

<s-arg name="control">
a list of control parameters to be used in the numerical algorithms. See
<s-function name="covRob.control.sgm">covRob.control</s-function> for the
possible control parameters and their default settings.
</s-arg>

<s-arg name="...">
optionally, control parameters for the robust covariance estimation
algorithms may be included in the call to
<s-expression>princompRob</s-expression>. 
</s-arg>
</s-args-optional>

<s-value>
an object of class <s-expression>princompRob</s-expression> with components:
<s-return-component name=sdev>
vector of standard deviations of the principal components.
</s-return-component>

<s-return-component name=loadings>
orthogonal matrix of class <s-expression>loadings</s-expression> giving
the loadings. The first column is the linear combination of columns of
<s-expression>x</s-expression> defining the first principal component,
etc. If argument <s-expression>scores</s-expression> was numeric, then this
contains that number of columns.
</s-return-component>

<s-return-component name=n.obs>
the number of observations on which the estimates are based. This may not
be present if covlist was used.
</s-return-component>

<s-return-component name=scores>
the scores of some or all of the principal components for the observations.
</s-return-component>

<s-return-component name=center>
vector of centers for the variables.
</s-return-component>

<s-return-component name=scale>
vector of numbers by which the variables are scaled.  These are all 1 if 
<s-expression>corr</s-expression> is <s-expression>FALSE</s-expression>. If
<s-expression>corr</s-expression> is <s-expression>TRUE</s-expression>,
then scales will be the square roots of the diagonal of the
<s-expression>cov</s-expression> component of
<s-expression>covlist</s-expression>, if present, and otherwise it is the
standard deviations of the input data variables.
</s-return-component>

<s-return-component name=terms>
the terms object of the formula. This is not present if a formula was not
used.
</s-return-component>

<s-return-component name=call>
an image of the call to <s-expression>princompRob</s-expression>.
</s-return-component>
</s-value>

<s-details>
The argument <s-expression>covlist</s-expression> is provided only so that
<s-expression>princompRob</s-expression> is consistent with <s-function
name="princomp.sgm">princomp</s-function>. If
<s-expression>covlist</s-expression> is given, the covariance estimate must
be robust for the principal components to be robust.
</s-details>

<s-see>
<s-function name = "princomp.sgm">princomp</s-function>,
<s-function name = "covRob.sgm">covRob</s-function>,
<s-function name = "covRob.control.sgm">covRob.control</s-function>.
</s-see>

<s-examples>
<s-example>
stack.rpc <- princompRob(stack.dat)
</s-example>
</s-examples>

<s-keywords>
<s-keyword>robust</s-keyword>
<s-keyword>multivariate</s-keyword>
<s-keyword>librobust</s-keyword>
</s-keywords>

<s-docclass>
function
</s-docclass>

</s-function-doc>
