Commit c1e99829 by Eric Coissac

Add docs to the package

patch small typos in manuscripts
outline of the discussion
parent 9e71f8cb
...@@ -13,6 +13,7 @@ S3method(as.procmod.frame,matrix) ...@@ -13,6 +13,7 @@ S3method(as.procmod.frame,matrix)
S3method(as.procmod.frame,pm) S3method(as.procmod.frame,pm)
S3method(as.procmod.frame,procmod.frame) S3method(as.procmod.frame,procmod.frame)
S3method(dim,procmod.frame) S3method(dim,procmod.frame)
S3method(names,procmod.corls)
S3method(names,procmod.varls) S3method(names,procmod.varls)
S3method(ortho,data.frame) S3method(ortho,data.frame)
S3method(ortho,dist) S3method(ortho,dist)
......
...@@ -6,40 +6,66 @@ NULL ...@@ -6,40 +6,66 @@ NULL
#' Generate permutation matrix according to a schema. #' Generate permutation matrix according to a schema.
#' #'
#' @param perm xxx #' @param permutations a list of control values for the permutations as returned
#' @param n zzz #' by the function \code{\link[permute]{how}}, or the number of
#' @param strata eeee #' permutations required.
#' @param n numeric; the number of observations in the sample set.
#' May also be any object that nobs knows about;
#' see \code{\link[permute]{nobs}} methods.
#' @param strata A factor, or an object that can be coerced to a
#' factor via as.factor, specifying the strata for permutation.
#' #'
#' @note Internal function do not use.
#' #'
#' @rdname internal.getPermuteMatrix
#' The permutation schema is defined using the `how` function. #' The permutation schema is defined using the `how` function.
#' The implementation of this function is inspired #' The implementation of this function is inspired
#' from the VEGAN package and reproduced here to avoid an extra #' from the VEGAN package and reproduced here to avoid an extra
#' dependency on an hidden vegan function. #' dependency on an hidden vegan function.
#' #'
getPermuteMatrix = function(perm, n, strata = NULL) .getPermuteMatrix = function(permutations, n, strata = NULL)
{ {
if (length(perm) == 1) { if (length(permutations) == 1) {
perm <- permute::how(nperm = perm) permutations <- permute::how(nperm = permutations)
} }
if (!missing(strata) && !is.null(strata)) { if (!missing(strata) && !is.null(strata)) {
if (inherits(perm, "how") && is.null(permute::getBlocks(perm))) if (inherits(permutations, "how") && is.null(permute::getBlocks(permutations)))
permute::setBlocks(perm) <- strata permute::setBlocks(permutations) <- strata
} }
if (inherits(perm, "how")) if (inherits(permutations, "how"))
perm <- permute::shuffleSet(n, control = perm) permutations <- permute::shuffleSet(n, control = permutations)
else { else {
if (!is.integer(perm) && !all(perm == round(perm))) if (!is.integer(permutations) && !all(permutations == round(permutations)))
stop("permutation matrix must be strictly integers: use round()") stop("permutation matrix must be strictly integers: use round()")
} }
if (is.null(attr(perm, "control"))) if (is.null(attr(permutations, "control")))
attr(perm, "control") <- structure(list(within = list(type = "supplied matrix"), attr(permutations, "control") <- structure(list(within = list(type = "supplied matrix"),
nperm = nrow(perm)), class = "how") nperm = nrow(permutations)), class = "how")
perm permutations
} }
#' Compute the person correlation matrix of K coordinate matrices #' Monte-Carlo Test on the sum of the singular values of a procustean rotation.
#'
#' performs a Monte-Carlo Test on the sum of the singular values of a
#' procustean rotation (see \code{\link[ade4]{procuste.rtest}}).
#'
#' @param ... the set of matrices or a \code{\link[ProcMod]{procmod.frame}}
#' object.
#' @param permutations a list of control values for the permutations as returned
#' by the function \code{\link[permute]{how}}, or the number of
#' permutations required.
#' @param p.adjust.method the multiple test correction method used
#' to adjust p values. \code{\link[stats]{p.adjust.method}}
#' 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"}.
#'
#' @references {
#' \insertRef{Jackson:95:00}{ProcMod}
#' }
#' #'
#' @author Eric Coissac #' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima #' @author Christelle Gonindard-Melodelima
...@@ -73,7 +99,7 @@ corls.test <- function(..., ...@@ -73,7 +99,7 @@ corls.test <- function(...,
n <- nrow(xs) n <- nrow(xs)
nx <- length(xs) nx <- length(xs)
pmatrix <- getPermuteMatrix(permutations, n) pmatrix <- .getPermuteMatrix(permutations, n)
if (ncol(pmatrix) != n) { if (ncol(pmatrix) != n) {
stop(gettextf( stop(gettextf(
......
...@@ -37,20 +37,38 @@ registerDoParallel(1) ...@@ -37,20 +37,38 @@ registerDoParallel(1)
c / vv c / vv
} }
#' Compute the procrustean variance, covariance matrix of K matrices. #' Procrustean Correlation, and Variance / Covariance Matrices.
#'
#' \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.
#' #'
#' Procrustean covariance between two matrices X and Y, is defined as the sum #' Procrustean covariance between two matrices X and Y, is defined as the sum
#' of the singular values of the X'Y matrix #' of the singular values of the X'Y matrix \insertCite{Gower:71:00,Lingoes:74:00}{ProcMod}.
#' \insertCite{Gower:71:00,Lingoes:74:00}{Rdpack}. Both the matrices must have #' Both the X and Y matrices must have the same number of rows.
#' the same number of rows. #'
#' The variances and covariances and correlations are corrected
#' to avoid over fitting \insertCite{Coissac-Eric:19:00}{ProcMod}.
#'
#' Partial correlation coefficients are computed by inverting the correlation followed
#' by a normalisation by the diagonal of the inverted matrix.
#' #'
#' \code{varls} computes the variance covariance matrix of a set of matrices #' The inputs must be numeric matrices or \code{\link[stats]{dist}} object.
#' following the above definition. The variances and covariances are corrected #' The set of input matrices can be aggregated un a
#' to avoid over fitting \insertCite{Coissac-Eric:19:00}{Rdpack}. . #' \code{\link[ProcMod]{procmod.frame}}.
#' #'
#' Before computing the covariances, matrices are projected into an #' Before computing the coefficients, matrices are projected into an
#' orthogonal space using the \code{\link[ProcMod]{ortho}} function. #' orthogonal space using the \code{\link[ProcMod]{ortho}} function.
#' #'
#' 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.
#'
#' @references{ #' @references{
#' \insertRef{Gower:71:00}{ProcMod} #' \insertRef{Gower:71:00}{ProcMod}
#' #'
...@@ -104,8 +122,15 @@ registerDoParallel(1) ...@@ -104,8 +122,15 @@ registerDoParallel(1)
#' varls(A = A, B = B, C = C) #' varls(A = A, B = B, C = C)
#' data = procmod.frame(A = A, B = B, C = C) #' data = procmod.frame(A = A, B = B, C = C)
#' varls(data) #' varls(data)
#'
#' @author Eric Coissac #' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima #' @author Christelle Gonindard-Melodelima
#'
#' @rdname varls
#' @name varls
#' @aliases varls
#' @aliases corls
#' @aliases corls.partial
#' @export #' @export
varls <- function(..., varls <- function(...,
nrand = 100, nrand = 100,
...@@ -182,6 +207,8 @@ varls <- function(..., ...@@ -182,6 +207,8 @@ varls <- function(...,
# s_cov_xxs[i, j, k] <- sum(svd(crossprod(r_xs[[i]],r_ys[[j]]))$d) # s_cov_xxs[i, j, k] <- sum(svd(crossprod(r_xs[[i]],r_ys[[j]]))$d)
# } # }
if (! getDoParRegistered()) registerDoParallel(1)
s_cov_xxs <- foreach(k = seq_len(nrand), s_cov_xxs <- foreach(k = seq_len(nrand),
.combine = cbind) %dopar% { .combine = cbind) %dopar% {
s1_cov_xxs <- matrix(0, nrow = nx, ncol = nx) s1_cov_xxs <- matrix(0, nrow = nx, ncol = nx)
...@@ -249,10 +276,7 @@ varls <- function(..., ...@@ -249,10 +276,7 @@ varls <- function(...,
} }
#' Compute the person correlation matrix of K coordinate matrices #' @rdname varls
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export #' @export
corls <- function(..., nrand = 100, corls <- function(..., nrand = 100,
p.adjust.method = "holm") { p.adjust.method = "holm") {
...@@ -263,20 +287,17 @@ corls <- function(..., nrand = 100, ...@@ -263,20 +287,17 @@ corls <- function(..., nrand = 100,
s <- sqrt(diag(cov)) s <- sqrt(diag(cov))
vv <- s %o% s vv <- s %o% s
rls <- cov / vv rls <- cov / vv
class(rls) <- "matrix"
if (!is.null(attr(cov, "rcovls"))) { if (!is.null(attr(cov, "rcovls"))) {
attr(rls, "nrand") <- attr(cov, "nrand") attr(rls, "nrand") <- attr(cov, "nrand")
attr(rls, "rcorls") <- attr(cov, "rcovls") / vv
} }
make_subS3Class(rls, "procmod.corls") make_subS3Class(rls, "procmod.corls")
} }
#' Compute the person partial correlation matrix of K coordinate matrices #' @rdname varls
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export #' @export
corls.partial <- function(..., nrand = 100) { corls.partial <- function(..., nrand = 100) {
rls <- corls(..., nrand = nrand) rls <- corls(..., nrand = nrand)
...@@ -291,7 +312,7 @@ corls.partial <- function(..., nrand = 100) { ...@@ -291,7 +312,7 @@ corls.partial <- function(..., nrand = 100) {
make_subS3Class(rp, "procmod.corls") make_subS3Class(rp, "procmod.corls")
} }
#' Compute the person partial correlation matrix of K coordinate matrices #' Print procrustean variance / covariance matrix.
#' #'
#' @author Eric Coissac #' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima #' @author Christelle Gonindard-Melodelima
...@@ -315,12 +336,14 @@ print.procmod.varls <- function(x, ...) { ...@@ -315,12 +336,14 @@ print.procmod.varls <- function(x, ...) {
#' @author Christelle Gonindard-Melodelima #' @author Christelle Gonindard-Melodelima
#' @export #' @export
names.procmod.varls <- function(x) { names.procmod.varls <- function(x) {
names(attributes(x)) n <- names(attributes(x))
bn <- grep(pattern = "^(dim|class)",
x = n)
n[-bn]
} }
#' Print procrustean correlation matrix.
#' Compute the person partial correlation matrix of K coordinate matrices
#' #'
#' @author Eric Coissac #' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima #' @author Christelle Gonindard-Melodelima
...@@ -341,3 +364,15 @@ print.procmod.corls <- function(x, ...) { ...@@ -341,3 +364,15 @@ print.procmod.corls <- function(x, ...) {
attr(x,name) attr(x,name)
} }
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
names.procmod.corls <- function(x) {
n <- names(attributes(x))
bn <- grep(pattern = "^(dim|class)",
x = n)
n[-bn]
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/covls.R
\name{corls}
\alias{corls}
\title{Compute the person correlation matrix of K coordinate matrices}
\usage{
corls(..., nrand = 100, p.adjust.method = "holm")
}
\description{
Compute the person correlation matrix of K coordinate matrices
}
\author{
Eric Coissac
Christelle Gonindard-Melodelima
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/covls.R
\name{corls.partial}
\alias{corls.partial}
\title{Compute the person partial correlation matrix of K coordinate matrices}
\usage{
corls.partial(..., nrand = 100)
}
\description{
Compute the person partial correlation matrix of K coordinate matrices
}
\author{
Eric Coissac
Christelle Gonindard-Melodelima
}
...@@ -2,13 +2,34 @@ ...@@ -2,13 +2,34 @@
% Please edit documentation in R/corls_test.R % Please edit documentation in R/corls_test.R
\name{corls.test} \name{corls.test}
\alias{corls.test} \alias{corls.test}
\title{Compute the person correlation matrix of K coordinate matrices} \title{Monte-Carlo Test on the sum of the singular values of a procustean rotation.}
\usage{ \usage{
corls.test(..., permutations = permute::how(nperm = 999), corls.test(..., permutations = permute::how(nperm = 999),
p.adjust.method = "holm") p.adjust.method = "holm")
} }
\arguments{
\item{...}{the set of matrices or a \code{\link[ProcMod]{procmod.frame}}
object.}
\item{permutations}{a list of control values for the permutations as returned
by the function \code{\link[permute]{how}}, or the number of
permutations required.}
\item{p.adjust.method}{the multiple test correction method used
to adjust p values. \code{\link[stats]{p.adjust.method}}
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"}.}
}
\description{ \description{
Compute the person correlation matrix of K coordinate matrices performs a Monte-Carlo Test on the sum of the singular values of a
procustean rotation (see \code{\link[ade4]{procuste.rtest}}).
}
\references{
{
\insertRef{Jackson:95:00}{ProcMod}
}
} }
\author{ \author{
Eric Coissac Eric Coissac
......
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/corls_test.R
\name{getPermuteMatrix}
\alias{getPermuteMatrix}
\title{Generate permutation matrix according to a schema.}
\usage{
getPermuteMatrix(perm, n, strata = NULL)
}
\arguments{
\item{perm}{xxx}
\item{n}{zzz}
\item{strata}{eeee
The permutation schema is defined using the `how` function.
The implementation of this function is inspired
from the VEGAN package and reproduced here to avoid an extra
dependency on an hidden vegan function.}
}
\description{
Generate permutation matrix according to a schema.
}
...@@ -2,12 +2,12 @@ ...@@ -2,12 +2,12 @@
% Please edit documentation in R/covls.R % Please edit documentation in R/covls.R
\name{print.procmod.corls} \name{print.procmod.corls}
\alias{print.procmod.corls} \alias{print.procmod.corls}
\title{Compute the person partial correlation matrix of K coordinate matrices} \title{Print procrustean correlation matrix.}
\usage{ \usage{
\method{print}{procmod.corls}(x, ...) \method{print}{procmod.corls}(x, ...)
} }
\description{ \description{
Compute the person partial correlation matrix of K coordinate matrices Print procrustean correlation matrix.
} }
\author{ \author{
Eric Coissac Eric Coissac
......
...@@ -2,12 +2,12 @@ ...@@ -2,12 +2,12 @@
% Please edit documentation in R/covls.R % Please edit documentation in R/covls.R
\name{print.procmod.varls} \name{print.procmod.varls}
\alias{print.procmod.varls} \alias{print.procmod.varls}
\title{Compute the person partial correlation matrix of K coordinate matrices} \title{Print procrustean variance / covariance matrix.}
\usage{ \usage{
\method{print}{procmod.varls}(x, ...) \method{print}{procmod.varls}(x, ...)
} }
\description{ \description{
Compute the person partial correlation matrix of K coordinate matrices Print procrustean variance / covariance matrix.
} }
\author{ \author{
Eric Coissac Eric Coissac
......
...@@ -2,9 +2,15 @@ ...@@ -2,9 +2,15 @@
% Please edit documentation in R/covls.R % Please edit documentation in R/covls.R
\name{varls} \name{varls}
\alias{varls} \alias{varls}
\title{Compute the procrustean variance, covariance matrix of K matrices.} \alias{corls}
\alias{corls.partial}
\title{Procrustean Correlation, and Variance / Covariance Matrices.}
\usage{ \usage{
varls(..., nrand = 100, p.adjust.method = "holm") varls(..., nrand = 100, p.adjust.method = "holm")
corls(..., nrand = 100, p.adjust.method = "holm")
corls.partial(..., nrand = 100)
} }
\arguments{ \arguments{
\item{...}{the set of matrices or a \code{\link[ProcMod]{procmod.frame}} \item{...}{the set of matrices or a \code{\link[ProcMod]{procmod.frame}}
...@@ -46,18 +52,36 @@ a \code{procmod.varls} object which corresponds to a numeric ...@@ -46,18 +52,36 @@ a \code{procmod.varls} object which corresponds to a numeric
method specified by the \code{p.adjust.method} parameter. method specified by the \code{p.adjust.method} parameter.
} }
\description{ \description{
Procrustean covariance between two matrices X and Y, is defined as the sum \code{varls}, \code{corls}, \code{corls.partial} compute the procrustean
of the singular values of the X'Y matrix variance / covariance, correlation, or partial correlation matrices
\insertCite{Gower:71:00,Lingoes:74:00}{Rdpack}. Both the matrices must have between a set of real matrices and \code{\link[stats]{dist}} objects.
the same number of rows.
} }
\details{ \details{
\code{varls} computes the variance covariance matrix of a set of matrices Procrustean covariance between two matrices X and Y, is defined as the sum
following the above definition. The variances and covariances are corrected of the singular values of the X'Y matrix \insertCite{Gower:71:00,Lingoes:74:00}{ProcMod}.
to avoid over fitting \insertCite{Coissac-Eric:19:00}{Rdpack}. . 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}.
Before computing the covariances, matrices are projected into an 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
\code{\link[ProcMod]{procmod.frame}}.
Before computing the coefficients, matrices are projected into an
orthogonal space using the \code{\link[ProcMod]{ortho}} function. orthogonal space using the \code{\link[ProcMod]{ortho}} function.
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.
} }
\examples{ \examples{
# Build Three matrices of 3 rows. # Build Three matrices of 3 rows.
...@@ -69,6 +93,7 @@ varls(A, B, C) ...@@ -69,6 +93,7 @@ varls(A, B, C)
varls(A = A, B = B, C = C) varls(A = A, B = B, C = C)
data = procmod.frame(A = A, B = B, C = C) data = procmod.frame(A = A, B = B, C = C)
varls(data) varls(data)
} }
\references{ \references{
{ {
......
...@@ -99,7 +99,7 @@ Sz{\'e}kely, G.~J., Rizzo, M.~L., and Bakirov, N.~K. (2007). ...@@ -99,7 +99,7 @@ Sz{\'e}kely, G.~J., Rizzo, M.~L., and Bakirov, N.~K. (2007).
\bibitem[Theil {\em et~al.}(1958)Theil, Cramer, Moerman, and \bibitem[Theil {\em et~al.}(1958)Theil, Cramer, Moerman, and
Russchen]{Theil:58:00} Russchen]{Theil:58:00}
Theil, H., Cramer, J.~S., Moerman, H., and Russchen, A. (1958). Theil, H., Cramer, J.~S., Moerman, H., and Russchen, A. (1958).
\newblock {\em Economic forecasts and policy\/}, page 213. \newblock {\em Economic forecasts and policy\/}.
\newblock North-Holland Publishing Company, Amsterdam. \newblock North-Holland Publishing Company, Amsterdam.
\end{thebibliography} \end{thebibliography}
No preview for this file type
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment