varls.Rd 3.83 KB
 Eric Coissac committed Jul 06, 2018 1 % Generated by roxygen2: do not edit by hand  Eric Coissac committed Apr 16, 2019 2 % Please edit documentation in R/covls.R  Eric Coissac committed Jan 24, 2019 3 4 \name{varls} \alias{varls}  Eric Coissac committed Aug 23, 2019 5 6 7 \alias{corls} \alias{corls.partial} \title{Procrustean Correlation, and Variance / Covariance Matrices.}  Eric Coissac committed Jul 06, 2018 8 \usage{  Eric Coissac committed May 27, 2019 9 varls(..., nrand = 100, p.adjust.method = "holm")  Eric Coissac committed Aug 23, 2019 10 11 12 13  corls(..., nrand = 100, p.adjust.method = "holm") corls.partial(..., nrand = 100)  Eric Coissac committed Jul 06, 2018 14 15 } \arguments{  Eric Coissac committed Oct 01, 2019 16 \item{...}{the set of matrices or a \code{\link[ProcMod]{procmod_frame}}  Eric Coissac committed Aug 21, 2019 17 object.}  Eric Coissac committed Apr 16, 2019 18   Eric Coissac committed May 27, 2019 19 \item{nrand}{number of randomisation used to estimate the mean  Eric Coissac committed Aug 21, 2019 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.}  Eric Coissac committed May 27, 2019 24 25  \item{p.adjust.method}{the multiple test correction method used  Eric Coissac committed Oct 01, 2019 26 to adjust p values. \code{p.adjust.method}  Eric Coissac committed Aug 21, 2019 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 Jul 06, 2018 53 54 } \description{  Eric Coissac committed Aug 23, 2019 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 Jul 06, 2018 58 }  Eric Coissac committed Aug 21, 2019 59 \details{  Eric Coissac committed Aug 23, 2019 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}.  Eric Coissac committed Aug 21, 2019 66   Eric Coissac committed Aug 23, 2019 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  Eric Coissac committed Oct 01, 2019 72 \code{\link[ProcMod]{procmod_frame}}.  Eric Coissac committed Aug 23, 2019 73 74  Before computing the coefficients, matrices are projected into an  Eric Coissac committed Aug 21, 2019 75 orthogonal space using the \code{\link[ProcMod]{ortho}} function.  Eric Coissac committed Aug 23, 2019 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.  Eric Coissac committed Aug 21, 2019 85 }  Eric Coissac committed Jul 06, 2018 86 \examples{  Eric Coissac committed Apr 30, 2019 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  Eric Coissac committed May 27, 2019 92 93 varls(A, B, C) varls(A = A, B = B, C = C)  Eric Coissac committed Oct 01, 2019 94 data = procmod_frame(A = A, B = B, C = C)  Eric Coissac committed Aug 21, 2019 95 varls(data)  Eric Coissac committed Aug 23, 2019 96   Eric Coissac committed Aug 21, 2019 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 Jul 06, 2018 106 }  Eric Coissac committed Oct 01, 2019 107 108 109 \seealso{ \code{\link[stats]{p.adjust}} }  Eric Coissac committed Jul 06, 2018 110 \author{  Eric Coissac committed Jan 24, 2019 111 112 113 Eric Coissac Christelle Gonindard-Melodelima  Eric Coissac committed Jul 06, 2018 114 }