Skip to content

P
ProcMod
Commit c1e99829 by Eric Coissac
Options

Add docs to the package 

patch small typos in manuscripts
outline of the discussion
parent 9e71f8cb
Showing with 162 additions and 110 deletions
NAMESPACE
......@@ -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)
......
R/corls_test.R
......@@ -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(
......
R/covls.R
......@@ -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]
}
man/corls.Rd deleted 100644 → 0
% 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
}
man/corls.partial.Rd deleted 100644 → 0
% 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
}
man/corls.test.Rd
......@@ -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
......
man/getPermuteMatrix.Rd deleted 100644 → 0
% 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.
}
man/print.procmod.corls.Rd
......@@ -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
......
man/print.procmod.varls.Rd
......@@ -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
......
man/varls.Rd
......@@ -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{
{
......
manuscript/main.bbl
......@@ -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}
manuscript/main.pdf
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