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)
S3method(as.procmod.frame,pm)
S3method(as.procmod.frame,procmod.frame)
S3method(dim,procmod.frame)
S3method(names,procmod.corls)
S3method(names,procmod.varls)
S3method(ortho,data.frame)
S3method(ortho,dist)
......
......@@ -6,40 +6,66 @@ NULL
#' Generate permutation matrix according to a schema.
#'
#' @param perm xxx
#' @param n zzz
#' @param strata eeee
#' @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 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 implementation of this function is inspired
#' from the VEGAN package and reproduced here to avoid an extra
#' dependency on an hidden vegan function.
#'
getPermuteMatrix = function(perm, n, strata = NULL)
.getPermuteMatrix = function(permutations, n, strata = NULL)
{
if (length(perm) == 1) {
perm <- permute::how(nperm = perm)
if (length(permutations) == 1) {
permutations <- permute::how(nperm = permutations)
}
if (!missing(strata) && !is.null(strata)) {
if (inherits(perm, "how") && is.null(permute::getBlocks(perm)))
permute::setBlocks(perm) <- strata
if (inherits(permutations, "how") && is.null(permute::getBlocks(permutations)))
permute::setBlocks(permutations) <- strata
}
if (inherits(perm, "how"))
perm <- permute::shuffleSet(n, control = perm)
if (inherits(permutations, "how"))
permutations <- permute::shuffleSet(n, control = permutations)
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()")
}
if (is.null(attr(perm, "control")))
attr(perm, "control") <- structure(list(within = list(type = "supplied matrix"),
nperm = nrow(perm)), class = "how")
perm
if (is.null(attr(permutations, "control")))
attr(permutations, "control") <- structure(list(within = list(type = "supplied matrix"),
nperm = nrow(permutations)), class = "how")
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 Christelle Gonindard-Melodelima
......@@ -73,7 +99,7 @@ corls.test <- function(...,
n <- nrow(xs)
nx <- length(xs)
pmatrix <- getPermuteMatrix(permutations, n)
pmatrix <- .getPermuteMatrix(permutations, n)
if (ncol(pmatrix) != n) {
stop(gettextf(
......
......@@ -37,20 +37,38 @@ registerDoParallel(1)
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
#' of the singular values of the X'Y matrix
#' \insertCite{Gower:71:00,Lingoes:74:00}{Rdpack}. Both the matrices must have
#' the same number of rows.
#' 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}.
#'
#' 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
#' following the above definition. The variances and covariances are corrected
#' to avoid over fitting \insertCite{Coissac-Eric:19:00}{Rdpack}. .
#' 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 covariances, matrices are projected into an
#' Before computing the coefficients, matrices are projected into an
#' 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{
#' \insertRef{Gower:71:00}{ProcMod}
#'
......@@ -104,8 +122,15 @@ registerDoParallel(1)
#' varls(A = A, B = B, C = C)
#' data = procmod.frame(A = A, B = B, C = C)
#' varls(data)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#'
#' @rdname varls
#' @name varls
#' @aliases varls
#' @aliases corls
#' @aliases corls.partial
#' @export
varls <- function(...,
nrand = 100,
......@@ -182,6 +207,8 @@ varls <- function(...,
# 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),
.combine = cbind) %dopar% {
s1_cov_xxs <- matrix(0, nrow = nx, ncol = nx)
......@@ -249,10 +276,7 @@ varls <- function(...,
}
#' Compute the person correlation matrix of K coordinate matrices
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @rdname varls
#' @export
corls <- function(..., nrand = 100,
p.adjust.method = "holm") {
......@@ -263,20 +287,17 @@ corls <- function(..., nrand = 100,
s <- sqrt(diag(cov))
vv <- s %o% s
rls <- cov / vv
class(rls) <- "matrix"
if (!is.null(attr(cov, "rcovls"))) {
attr(rls, "nrand") <- attr(cov, "nrand")
attr(rls, "rcorls") <- attr(cov, "rcovls") / vv
}
make_subS3Class(rls, "procmod.corls")
}
#' Compute the person partial correlation matrix of K coordinate matrices
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @rdname varls
#' @export
corls.partial <- function(..., nrand = 100) {
rls <- corls(..., nrand = nrand)
......@@ -291,7 +312,7 @@ corls.partial <- function(..., nrand = 100) {
make_subS3Class(rp, "procmod.corls")
}
#' Compute the person partial correlation matrix of K coordinate matrices
#' Print procrustean variance / covariance matrix.
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
......@@ -315,12 +336,14 @@ print.procmod.varls <- function(x, ...) {
#' @author Christelle Gonindard-Melodelima
#' @export
names.procmod.varls <- function(x) {
names(attributes(x))
n <- names(attributes(x))
bn <- grep(pattern = "^(dim|class)",
x = n)
n[-bn]
}
#' Compute the person partial correlation matrix of K coordinate matrices
#' Print procrustean correlation matrix.
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
......@@ -341,3 +364,15 @@ print.procmod.corls <- function(x, ...) {
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 @@
% Please edit documentation in R/corls_test.R
\name{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{
corls.test(..., permutations = permute::how(nperm = 999),
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{
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{
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 @@
% Please edit documentation in R/covls.R
\name{print.procmod.corls}
\alias{print.procmod.corls}
\title{Compute the person partial correlation matrix of K coordinate matrices}
\title{Print procrustean correlation matrix.}
\usage{
\method{print}{procmod.corls}(x, ...)
}
\description{
Compute the person partial correlation matrix of K coordinate matrices
Print procrustean correlation matrix.
}
\author{
Eric Coissac
......
......@@ -2,12 +2,12 @@
% Please edit documentation in R/covls.R
\name{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{
\method{print}{procmod.varls}(x, ...)
}
\description{
Compute the person partial correlation matrix of K coordinate matrices
Print procrustean variance / covariance matrix.
}
\author{
Eric Coissac
......
......@@ -2,9 +2,15 @@
% Please edit documentation in R/covls.R
\name{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{
varls(..., nrand = 100, p.adjust.method = "holm")
corls(..., nrand = 100, p.adjust.method = "holm")
corls.partial(..., nrand = 100)
}
\arguments{
\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
method specified by the \code{p.adjust.method} parameter.
}
\description{
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}{Rdpack}. Both the matrices must have
the same number of rows.
\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.
}
\details{
\code{varls} computes the variance covariance matrix of a set of matrices
following the above definition. The variances and covariances are corrected
to avoid over fitting \insertCite{Coissac-Eric:19:00}{Rdpack}. .
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}.
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.
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{
# Build Three matrices of 3 rows.
......@@ -69,6 +93,7 @@ varls(A, B, C)
varls(A = A, B = B, C = C)
data = procmod.frame(A = A, B = B, C = C)
varls(data)
}
\references{
{
......
......@@ -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
Russchen]{Theil:58:00}
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.
\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