Commit 4976bcea by Eric Coissac

Update of the documentation and switch to version 1.0.2

parent 083f7cb3
Package: ProcMod
Type: Package
Title: Informative Procrustean Matrix Correlation
Version: 1.0.1
Version: 1.0.2
Author: Eric Coissac, Christelle Gonindard-Melodelima
Maintainer: Eric Coissac <eric.coissac@metabarcoding.org>
Description: Estimates corrected Procrustean correlation between matrices for removing overfitting effect.
......
......@@ -67,6 +67,18 @@ NULL
#' \insertRef{Jackson:95:00}{ProcMod}
#' }
#'
#' @examples
#' A <- simulate_matrix(10,3)
#' B <- simulate_matrix(10,5)
#' C <- simulate_correlation(B,10,r2=0.6)
#'
#' # Computes the correlation matrix
#' data <- procmod_frame(A = A, B = B, C = C)
#'
#' corls_test(A, B, permutations = 100)
#' corls_test(B, C, permutations = 100)
#' corls_test(data, permutations = 100)
#'
#' @seealso \code{\link[stats]{p.adjust}}
#'
#' @author Eric Coissac
......@@ -95,7 +107,7 @@ corls_test <- function(...,
xs <- ortho(xs)
cov <- varls(xs, nperm = 0)
cov <- varls(xs, nrand = 0)
lcov <- cov - eps
ngreater <- array(0,dim = dim(cov))
......@@ -123,7 +135,7 @@ corls_test <- function(...,
function(j) xs[[j]][pmatrix[ps[j], ], ]
)
),
nperm = 0
nrand = 0
)
ngreater <- ngreater + (
rcov >= lcov)
......
......@@ -124,15 +124,24 @@ if (.has_doParallel) require(doParallel)
#'
#' @examples
#' # 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
#' A <- simulate_matrix(10,3)
#' B <- simulate_matrix(10,5)
#' C <- simulate_correlation(B,10,r2=0.6)
#'
#' # Computes the variance covariance matrix
#' varls(A, B, C)
#' varls(A = A, B = B, C = C)
#'
#' data = procmod_frame(A = A, B = B, C = C)
#' varls(data)
#'
#' # Computes the correlation matrix
#' corls(data, nrand = 500)
#'
#' # Computes the partial correlation matrix
#' corls_partial(data)
#' corls_partial(data, nrand = 0)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#'
......@@ -301,12 +310,24 @@ corls_partial <- function(..., nrand = 100) {
make_subS3Class(rp, "procmod_corls")
}
#' Print procrustean variance / covariance matrix.
#' Print procrustean Variance / Covariance Matrix.
#'
#' @param x a \code{procmod_varls}
#' object
#' @param ... other parameters passed to other functions
#'
#' @examples
#' # Build Three matrices of 3 rows.
#' A <- simulate_matrix(10,3)
#' B <- simulate_matrix(10,5)
#' C <- simulate_correlation(B,10,r2=0.6)
#'
#' # Computes the variance covariance matrix
#' data <- procmod_frame(A = A, B = B, C = C)
#' v <- varls(data, nrand = 1000)
#'
#' print(v)
#'
#' @seealso \code{\link[ProcMod]{varls}}
#'
#' @author Eric Coissac
......@@ -327,6 +348,27 @@ print.procmod_varls <- function(x, ...) {
attr(x,name)
}
#' The Names of the elements of a Variance / Covariance Matrix.
#'
#' Returns the names of the elements associated to a \code{procmod_varls}
#' object.
#'
#' @param x a \code{procmod_varls} object
#'
#' @examples
#' # Build Three matrices of 3 rows.
#' A <- simulate_matrix(10,3)
#' B <- simulate_matrix(10,5)
#' C <- simulate_correlation(B,10,r2=0.6)
#'
#' # Computes the variance covariance matrix
#' data <- procmod_frame(A = A, B = B, C = C)
#' v <- varls(data, nrand = 1000)
#'
#' names(v)
#'
#' @seealso \code{\link[ProcMod]{varls}}
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -338,12 +380,24 @@ names.procmod_varls <- function(x) {
}
#' Print procrustean correlation matrix.
#' Print a procrustean Correlation Matrix.
#'
#' @param x a \code{procmod_corls}
#' object
#' @param ... other parameters passed to other functions
#'
#' @examples
#' # Build Three matrices of 3 rows.
#' A <- simulate_matrix(10,3)
#' B <- simulate_matrix(10,5)
#' C <- simulate_correlation(B,10,r2=0.6)
#'
#' # Computes the correlation matrix
#' data <- procmod_frame(A = A, B = B, C = C)
#' cls <- corls(data, nrand = 1000)
#'
#' print(cls)
#'
#' @seealso \code{\link[ProcMod]{corls}}
#'
#' @author Eric Coissac
......@@ -366,6 +420,27 @@ print.procmod_corls <- function(x, ...) {
}
#' The Names of the elements of a Correlation Matrix
#'
#' Returns the names of the elements associated to a \code{procmod_corls}
#' object.
#'
#' @param x a \code{procmod_corls} object
#'
#' @examples
#' # Build Three matrices of 3 rows.
#' A <- simulate_matrix(10,3)
#' B <- simulate_matrix(10,5)
#' C <- simulate_correlation(B,10,r2=0.6)
#'
#' # Computes the correlation matrix
#' data <- procmod_frame(A = A, B = B, C = C)
#' cls <- corls(data, nrand = 1000)
#'
#' names(cls)
#'
#' @seealso \code{\link[ProcMod]{corls}}
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......
......@@ -22,6 +22,16 @@ NULL
#' \code{\link[base]{matrix}} method.
#' @param ... additional arguments to be passed to or from methods.
#'
#' @examples
#' data(bacteria)
#' bacteria_rel_freq <- sweep(bacteria,
#' 1,
#' rowSums(bacteria),
#' "/")
#' bacteria_hellinger <- sqrt(bacteria_rel_freq)
#' bacteria_dist <- dist(bacteria_hellinger)
#' bdf <- as.data.frame(bacteria_dist)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -62,6 +72,17 @@ as.data.frame.dist <- function(x, row.names = NULL, optional = FALSE, ...) {
#' \code{n} the number pf observations. This matrix defines the
#' coordinates of each point in the orthogonal space.
#'
#' @examples
#' data(bacteria)
#' bacteria_rel_freq <- sweep(bacteria,
#' 1,
#' rowSums(bacteria),
#' "/")
#' bacteria_hellinger <- sqrt(bacteria_rel_freq)
#' bacteria_dist <- dist(bacteria_hellinger)
#'
#' project <- nmds(bacteria_dist)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -117,6 +138,17 @@ nmds <- function(distances,
#' \code{n} the number pf observations. This matrix defines the
#' coordinates of each point in the orthogonal space.
#'
#' @examples
#' data(bacteria)
#' bacteria_rel_freq <- sweep(bacteria,
#' 1,
#' rowSums(bacteria),
#' "/")
#' bacteria_hellinger <- sqrt(bacteria_rel_freq)
#' bacteria_dist <- dist(bacteria_hellinger)
#'
#' project <- pcoa(bacteria_dist)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -154,6 +186,16 @@ pcoa <- function(distances) {
#' \code{n} the number pf observations. This matrix defines the
#' coordinates of each point in the orthogonal space.
#'
#' @examples
#' data(bacteria)
#' bacteria_rel_freq <- sweep(bacteria,
#' 1,
#' rowSums(bacteria),
#' "/")
#' bacteria_hellinger <- sqrt(bacteria_rel_freq)
#'
#' project <- pca(bacteria_hellinger)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -184,6 +226,12 @@ pca <- function(data, scale = FALSE) {
#' @return a \code{numeric} matrix centred by rows
#' and columns
#'
#' @examples
#' data(bacteria)
#' bact_bc <- bicenter(bacteria)
#' sum(rowSums(bact_bc))
#' sum(colSums(bact_bc))
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -208,6 +256,21 @@ bicenter <- function(m) {
#' considered positive if it is larger than
#' -tol*lambda1 where lambda1 is the largest eigenvalue.
#'
#' @examples
#' library(vegan)
#' data(bacteria)
#'
#' bacteria_rel_freq <- sweep(bacteria,
#' 1,
#' rowSums(bacteria),
#' "/")
#'
#' bacteria_bray <- vegdist(bacteria_rel_freq,method = "bray")
#' is_euclid(bacteria_bray)
#'
#' bacteria_chao <- vegdist(floor(bacteria*10000),method = "chao")
#' is_euclid(bacteria_chao)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -258,6 +321,33 @@ is_orthogonal <- function(x) {
#' \code{n} the number pf observations. This matrix defines the
#' coordinates of each point in the orthogonal space.
#'
#' @examples
#' library(vegan)
#' data(bacteria)
#' data(eukaryotes)
#' data(soil)
#'
#' dataset <- procmod_frame(euk = vegdist(decostand(eukaryotes,
#' method = "hellinger"),
#' method = "euclidean"),
#' bac = vegdist(decostand(bacteria,
#' method = "hellinger"),
#' method = "euclidean"),
#' soil = scale(soil,
#' center = TRUE,
#' scale = TRUE))
#'
#' dp <- ortho(dataset)
#'
#' bacteria_rel_freq <- sweep(bacteria,
#' 1,
#' rowSums(bacteria),
#' "/")
#' bacteria_hellinger <- sqrt(bacteria_rel_freq)
#' bacteria_dist <- dist(bacteria_hellinger)
#'
#' project <- ortho(bacteria_dist)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......
#' @title Informative Procrustean Matrix Correlation
#' @name procmod
#' @description Estimates corrected Procrustean correlation between
#' matrices for removing overfitting effect.
#' @details
#' The functions in the ProcMod package aims to estimate and to test correlation
#' between matrices, correcting for the spurious correlations because of the
#' over-fitting effect.
#'
#' The ProcMod package is developed on the metabarcoding.org gitlab
#' (https://git.metabarcoding.org/lecasofts/ProcMod).
#' The gitlab of metabarcoding.org provides up-to-date information and
#' forums for bug reports.
#'
#' @author Christelle Gonindard-Melodelima
#' @author Eric Coissac
#'
#' @docType package
#' @importFrom Rdpack reprompt
NULL
......@@ -8,7 +25,8 @@ NULL
#' is a simplified version of a full data set
#' describing biodiversity changes along a South-North
#' gradient on the Australian East Coast, from Sidney to
#' North Cap. The gradient is constituted of 21 locations.
#' North Cap using a DNA metabarcoding approach.
#' The gradient is constituted of 21 locations.
#'
#' \describe{
#' \item{bacteria}{is a 21 x 2150 \code{data.frame} describing bacterial
......
......@@ -309,6 +309,18 @@ procmod_frame <- function(...,
#' \code{TRUE} if \code{x} is a \code{procmod_frame},
#' \code{FALSE} otherwise.
#'
#' @examples
#' # Builds a procmod_frame with two random matrices
#' m1 <- simulate_matrix(10,20)
#' m2 <- simulate_matrix(10,30)
#' pmf <- procmod_frame(m1 = m1, m2 = m2)
#'
#' # Returns TRUE
#' is_procmod_frame(pmf)
#'
#' # Returns FALSE
#' is_procmod_frame(3)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -327,6 +339,28 @@ is_procmod_frame <- function(x) {
#' implementation of that method
#' @return a \code{procmod_frame} object
#'
#' @examples
#' # Builds a list containing two random matrices
#' m1 <- simulate_matrix(10,20)
#' m2 <- simulate_matrix(10,30)
#' l <- list(m1 = m1, m2 = m2)
#'
#' # Converts the list to a procmod_frame
#' pmf1 <- as_procmod_frame(l)
#'
#' # Builds a procmod_frame from a matrix
#' m3 <- matrix(1:12,nrow=3)
#' pmf2 <- as_procmod_frame(matrix(1:12,nrow=3))
#' # Returns 4, the column count of the input matrix
#' length(pmf2)
#'
#' # Builds a 3D array
#' a <- array(1:24,dim = c(3,4,2))
#'
#' # The conversion to a procmod_frame makes
#' # an procmod element from each third dimension
#' as_procmod_frame(a)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -390,9 +424,20 @@ as_procmod_frame.matrix <- function(data, ...) {
#' Dimensions of a ProcMod Frame.
#'
#' Dimension 1 is the number of rows (individus)
#' shared by the aggregated matrices. Dimension 2
#' is the number of aggregated matrices
#'
#' @param x a \code{\link[ProcMod]{procmod_frame}}
#' object
#'
#' @examples
#' # Builds a procmod_frame with two random matrices
#' m1 <- simulate_matrix(10,20)
#' m2 <- simulate_matrix(10,30)
#' pmf <- procmod_frame(m1 = m1, m2 = m2)
#' dim(pmf)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......@@ -504,6 +549,58 @@ dim.procmod_frame <- function(x)
y
}
#' Subsetting Procmod Frames
#'
#' This is the implementation of the \code{\link[base]{subset}} generic function for
#' \code{procmod_frame}.
#'
#' The subset argument works on rows. Note that subset will be evaluated in the
#' \code{procmod_frame}, so columns can be referred to (by name) as variables
#' in the expression (see the examples).
#'
#' The select argument if provided indicates with matrices
#' have to be conserved. It works by first replacing column names in the selection
#' expression with the corresponding column numbers in the \code{procmod_frame} and then using
#' the resulting integer vector to index the columns. This allows the use of the
#' standard indexing conventions so that for example ranges of columns can
#' be specified easily, or single columns can be dropped (see the examples). Remember
#' that each column of a \code{procmod_frame} is actually a matrix.
#'
#' The drop argument is passed on to the \code{procmod_frame} indexing method.
#' The default value is \code{FALSE}.
#'
#' @param x object to be subsetted.
#' @param subset logical expression indicating elements or
#' rows to keep: missing values are taken as false.
#' @param select expression, indicating columns to select from a data frame.
#' @param drop passed on to [ indexing operator.
#' @param ... further arguments to be passed to or from other methods.
#'
#' @return A \code{procmod_frame} containing just the selected rows and columns.
#'
#' @examples
#' library(vegan)
#' data(bacteria)
#' data(eukaryotes)
#' data(soil)
#'
#' dataset <- procmod_frame(euk = vegdist(decostand(eukaryotes,
#' method = "hellinger"),
#' method = "euclidean"),
#' bac = vegdist(decostand(bacteria,
#' method = "hellinger"),
#' method = "euclidean"),
#' soil = scale(soil,
#' center = TRUE,
#' scale = TRUE))
#' dim(dataset)
#'
#' higher_ph = subset(dataset,soil[,"pH"] > 0)
#' dim(higher_ph)
#'
#' without_bacteria = subset(dataset,soil[,"pH"] > 0, -bac)
#' dim(without_bacteria)
#'
#' @author Eric Coissac
#' @author Christelle Gonindard-Melodelima
#' @export
......
#' @include internals.R
#'
#' @title ProcMod
#' @name procmod
#' @description blabla
#' @author Christelle Gonindard-Melodelima
#' @author Eric Coissac
#'
NULL
#' Rotate the \code{src} matrix to fit into the space of the \code{dest} matrix.
......@@ -20,9 +14,11 @@ NULL
#' @return a numeric matrix
#'
#' @examples
#' # Renerate a random matrix of size 10 x 15
#' # Generates two random matrices of size 10 x 15
#' m1 <- simulate_matrix(10, 15)
#' m2 <- simulate_matrix(10, 20)
#'
#' # Rotates matrix m1 on m2
#' mr <- protate(m1, m2)
#'
#' @author Christelle Gonindard-Melodelima
......
......@@ -29,6 +29,17 @@ See also the make.names argument of the
The created \code{data.frame} has a attribute \code{is.dist} set to
the logical value \code{TRUE}.
}
\examples{
data(bacteria)
bacteria_rel_freq <- sweep(bacteria,
1,
rowSums(bacteria),
"/")
bacteria_hellinger <- sqrt(bacteria_rel_freq)
bacteria_dist <- dist(bacteria_hellinger)
bdf <- as.data.frame(bacteria_dist)
}
\author{
Eric Coissac
......
......@@ -31,6 +31,29 @@ a \code{procmod_frame} object
Conversion methods are proposed for \code{list},
\code{matrix} and \code{array}.
}
\examples{
# Builds a list containing two random matrices
m1 <- simulate_matrix(10,20)
m2 <- simulate_matrix(10,30)
l <- list(m1 = m1, m2 = m2)
# Converts the list to a procmod_frame
pmf1 <- as_procmod_frame(l)
# Builds a procmod_frame from a matrix
m3 <- matrix(1:12,nrow=3)
pmf2 <- as_procmod_frame(matrix(1:12,nrow=3))
# Returns 4, the column count of the input matrix
length(pmf2)
# Builds a 3D array
a <- array(1:24,dim = c(3,4,2))
# The conversion to a procmod_frame makes
# an procmod element from each third dimension
as_procmod_frame(a)
}
\author{
Eric Coissac
......
......@@ -25,7 +25,8 @@ This data set of five \code{data.frame}
is a simplified version of a full data set
describing biodiversity changes along a South-North
gradient on the Australian East Coast, from Sidney to
North Cap. The gradient is constituted of 21 locations.
North Cap using a DNA metabarcoding approach.
The gradient is constituted of 21 locations.
}
\details{
\describe{
......
......@@ -20,6 +20,13 @@ colSums and rowSums of the returned matrix are all equal to zero.
Inspired from the algorithm described in stackoverflow
\url{https://stackoverflow.com/questions/43639063/double-centering-in-r}
}
\examples{
data(bacteria)
bact_bc <- bicenter(bacteria)
sum(rowSums(bact_bc))
sum(colSums(bact_bc))
}
\author{
Eric Coissac
......
......@@ -26,6 +26,19 @@ The default is,set to \code{"holm"}.}
performs a Monte-Carlo Test on the sum of the singular values of a
procustean rotation (see \code{\link[ade4]{procuste.rtest}}).
}
\examples{
A <- simulate_matrix(10,3)
B <- simulate_matrix(10,5)
C <- simulate_correlation(B,10,r2=0.6)
# Computes the correlation matrix
data <- procmod_frame(A = A, B = B, C = C)
corls_test(A, B, permutations = 100)
corls_test(B, C, permutations = 100)
corls_test(data, permutations = 100)
}
\references{
{
\insertRef{Jackson:95:00}{ProcMod}
......
......@@ -11,7 +11,17 @@
object}
}
\description{
Dimensions of a ProcMod Frame.
Dimension 1 is the number of rows (individus)
shared by the aggregated matrices. Dimension 2
is the number of aggregated matrices
}
\examples{
# Builds a procmod_frame with two random matrices
m1 <- simulate_matrix(10,20)
m2 <- simulate_matrix(10,30)
pmf <- procmod_frame(m1 = m1, m2 = m2)
dim(pmf)
}
\author{
Eric Coissac
......
......@@ -17,6 +17,22 @@ considered positive if it is larger than
Actually a simplified version of the ADE4 implementation
(\code{\link[ade4]{is.euclid}}).
}
\examples{
library(vegan)
data(bacteria)
bacteria_rel_freq <- sweep(bacteria,
1,
rowSums(bacteria),
"/")
bacteria_bray <- vegdist(bacteria_rel_freq,method = "bray")
is_euclid(bacteria_bray)
bacteria_chao <- vegdist(floor(bacteria*10000),method = "chao")
is_euclid(bacteria_chao)
}
\author{
Eric Coissac
......
......@@ -17,6 +17,19 @@ a \code{logical} value equals to
\description{
Check if an object is a ProcMod Frame.
}
\examples{
# Builds a procmod_frame with two random matrices
m1 <- simulate_matrix(10,20)
m2 <- simulate_matrix(10,30)
pmf <- procmod_frame(m1 = m1, m2 = m2)
# Returns TRUE
is_procmod_frame(pmf)
# Returns FALSE
is_procmod_frame(3)
}
\author{
Eric Coissac
......
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/covls.R
\name{names.procmod_corls}
\alias{names.procmod_corls}
\title{The Names of the elements of a Correlation Matrix}
\usage{
\method{names}{procmod_corls}(x)
}
\arguments{
\item{x}{a \code{procmod_corls} object}
}
\description{
Returns the names of the elements associated to a \code{procmod_corls}
object.
}
\examples{
# Build Three matrices of 3 rows.
A <- simulate_matrix(10,3)
B <- simulate_matrix(10,5)
C <- simulate_correlation(B,10,r2=0.6)
# Computes the correlation matrix
data <- procmod_frame(A = A, B = B, C = C)
cls <- corls(data, nrand = 1000)
names(cls)
}
\seealso{
\code{\link[ProcMod]{corls}}
}
\author{
Eric Coissac
Christelle Gonindard-Melodelima
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/covls.R
\name{names.procmod_varls}
\alias{names.procmod_varls}
\title{The Names of the elements of a Variance / Covariance Matrix.}
\usage{
\method{names}{procmod_varls}(x)
}
\arguments{
\item{x}{a \code{procmod_varls} object}
}
\description{
Returns the names of the elements associated to a \code{procmod_varls}
object.
}
\examples{
# Build Three matrices of 3 rows.
A <- simulate_matrix(10,3)
B <- simulate_matrix(10,5)
C <- simulate_correlation(B,10,r2=0.6)
# Computes the variance covariance matrix
data <- procmod_frame(A = A, B = B, C = C)
v <- varls(data, nrand = 1000)
names(v)
}
\seealso{
\code{\link[ProcMod]{varls}}
}
\author{
Eric Coissac
Christelle Gonindard-Melodelima
}
......@@ -34,6 +34,18 @@ NDMS being only to project point in an orthogonal space therefore
without any correlation between axis. Because a non-metric method
is used no condition is required on the used distance.
}
\examples{
data(bacteria)
bacteria_rel_freq <- sweep(bacteria,
1,
rowSums(bacteria),
"/")
bacteria_hellinger <- sqrt(bacteria_rel_freq)
bacteria_dist <- dist(bacteria_hellinger)
project <- nmds(bacteria_dist)
}
\author{
Eric Coissac
......
......@@ -44,6 +44,34 @@ for other distance the \code{\link[ProcMod]{nmds}} is used.
When points are described by a set of variable the
\code{\link[ProcMod]{nmds}} is used.
}
\examples{
library(vegan)
data(bacteria)
data(eukaryotes)
data(soil)
dataset <- procmod_frame(euk = vegdist(decostand(eukaryotes,
method = "hellinger"),
method = "euclidean"),
bac = vegdist(decostand(bacteria,
method = "hellinger"),
method = "euclidean"),
soil = scale(soil,
center = TRUE,
scale = TRUE))
dp <- ortho(dataset)