varls.Rd 3.83 KB
Newer Older
Eric Coissac committed
1
% Generated by roxygen2: do not edit by hand
2
% Please edit documentation in R/covls.R
3 4
\name{varls}
\alias{varls}
Eric Coissac committed
5 6 7
\alias{corls}
\alias{corls.partial}
\title{Procrustean Correlation, and Variance / Covariance Matrices.}
Eric Coissac committed
8
\usage{
9
varls(..., nrand = 100, p.adjust.method = "holm")
Eric Coissac committed
10 11 12 13

corls(..., nrand = 100, p.adjust.method = "holm")

corls.partial(..., nrand = 100)
Eric Coissac committed
14 15
}
\arguments{
16
\item{...}{the set of matrices or a \code{\link[ProcMod]{procmod_frame}}
17
object.}
18

19
\item{nrand}{number of randomisation used to estimate the mean
20 21 22 23
covariance observed between two random matrix.
If rand is \code{NULL} or equal to \code{0}, no correction
is estimated and the raw procrustean covariances are
estimated.}
24 25

\item{p.adjust.method}{the multiple test correction method used
26
to adjust p values. \code{p.adjust.method}
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
belongsone of the folowing values: \code{"holm"},
\code{"hochberg"}, \code{"hommel"}, \code{"bonferroni"},
\code{"BH"}, \code{"BY"}, \code{"fdr"},  \code{"none"}.
The default is,set to \code{"holm"}.}
}
\value{
a \code{procmod.varls} object which corresponds to a numeric
             matrix annotated by several attributes.

             The following attribute is always added:

             - \code{nrand} an integer value indicating the number of
               randomisations used to estimate the mean of the random
               covariance.

             When \code{nrand} is greater than 0 a couple of attributes
             is added:

             - \code{rcovls} a numeric matrix containing the estimation
               of the mean of the random covariance.

             - \code{p.value} a numeric matrix containing the estimations
               of the p.values of tests checking that the observed
               covariance is larger than the mean of the random covariance.
               p.values are corrected for multiple tests according to the
               method specified by the \code{p.adjust.method} parameter.
Eric Coissac committed
53 54
}
\description{
Eric Coissac committed
55 56 57
\code{varls}, \code{corls}, \code{corls.partial} compute the procrustean
variance / covariance, correlation, or partial correlation matrices
between a set of real matrices and \code{\link[stats]{dist}} objects.
Eric Coissac committed
58
}
59
\details{
Eric Coissac committed
60 61 62 63 64 65
Procrustean covariance between two matrices X and Y, is defined as the sum
of the singular values of the X'Y matrix \insertCite{Gower:71:00,Lingoes:74:00}{ProcMod}.
Both the X and Y matrices must have the same number of rows.

The variances and covariances and correlations are corrected
to avoid over fitting \insertCite{Coissac-Eric:19:00}{ProcMod}.
66

Eric Coissac committed
67 68 69 70 71
Partial correlation coefficients are computed by inverting the correlation followed
by a normalisation by the diagonal of the inverted matrix.

The inputs must be numeric matrices or \code{\link[stats]{dist}} object.
The set of input matrices can be aggregated un a
72
\code{\link[ProcMod]{procmod_frame}}.
Eric Coissac committed
73 74

Before computing the coefficients, matrices are projected into an
75
orthogonal space using the \code{\link[ProcMod]{ortho}} function.
Eric Coissac committed
76 77 78 79 80 81 82 83 84

The denominator n - 1 is used which gives an unbiased estimator of the
(co)variance for i.i.d. observations.

Scaling a covariance matrix into a correlation one can be achieved in many ways,
mathematically most appealing by multiplication with a diagonal matrix from left
and right, or more efficiently by using sweep(.., FUN = "/") twice.
The \code{\link[stats]{cov2cor}} function is even a bit more efficient,
and provided mostly for didactical reasons.
85
}
Eric Coissac committed
86
\examples{
87 88 89 90 91
# Build Three matrices of 3 rows.
A <- matrix(1:9, nrow = 3)
B <- matrix(10:15, nrow = 3)
C <- matrix(20:31, nrow = 3)
# compute the variance covariance matrix
92 93
varls(A, B, C)
varls(A = A, B = B, C = C)
94
data = procmod_frame(A = A, B = B, C = C)
95
varls(data)
Eric Coissac committed
96

97 98 99 100 101 102 103 104 105
}
\references{
{
 \insertRef{Gower:71:00}{ProcMod}

 \insertRef{Lingoes:74:00}{ProcMod}

 \insertRef{Coissac-Eric:19:00}{ProcMod}
}
Eric Coissac committed
106
}
107 108 109
\seealso{
\code{\link[stats]{p.adjust}}
}
Eric Coissac committed
110
\author{
111 112 113
Eric Coissac

Christelle Gonindard-Melodelima
Eric Coissac committed
114
}