## **************************************************************************
##
## (c) 2018-2023 Guillaume Guénard
## Department de sciences biologiques,
## Université de Montréal
## Montreal, QC, Canada
##
## **Package codep description**
##
## This file is part of codep
##
## codep is free software: you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation, either version 3 of the License, or
## (at your option) any later version.
##
## codep is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with codep. If not, see <https://www.gnu.org/licenses/>.
##
## R source code file
##
## **************************************************************************
##
#' \packageTitle{codep}
#'
#' @description \packageDescription{codep}
#' Multiscale Codependence Analysis (MCA) consists in assessing the coherence of
#' pairs of variables in space (or time) using the product of their correlation
#' coefficients with series of spatial (or temporal) eigenfunctions. That
#' product, which is positive or negative when variables display similar or
#' opposing trends, respectively, is called a codependence coefficient.
#'
#' The eigenfunctions used in the calculation are obtained in three steps: 1) a
#' distance matrix is calculated from the locations of samples in space (or the
#' sampling organisation through time). 2) From that distance matrix, a matrix
#' of Moran spatial weights is obtained; this is the same matrix as used to
#' calculate Moran's autocorrelation index, hence the name. And 3) the spatial
#' weight matrix is eigenvalue-decomposed after centring the rows and columns of
#' the spatial weight matrix.
#'
#' The statistical significance of codependence coefficients is tested using
#' parametric or permutational testing of a tau statistic. The `tau` statistic
#' is the product of the Student's `t` statistics obtained from comparison of
#' the two variables with a given eigenfunction. The `tau` statistic can take
#' either positive or negative values, thereby allowing one to perform
#' one-tailed or two-tailed testing. For multiple response variables, testing is
#' performed using the `phi` statistic instead of `tau`. That statistic follows
#' the distribution of the product of two Fisher-Snedocor F statistics (see
#' \link{product-distribution} for details).
#'
#' @docType package
#'
#' @name codep-package
#'
#' @details Function \code{\link{MCA}} performs Multiscale Codependence Analysis
#' (MCA). Functions \code{\link{test.cdp}} and \code{\link{permute.cdp}} handle
#' parametric or permutation testing of the codependence coefficients,
#' respectively.
#'
#' Methods are provided to print and plot \link{cdp-class} objects
#' (\code{\link{print.cdp}} and \code{\link{plot.cdp}}, respectively) as well as
#' summary (\code{\link{summary.cdp}}), fitted values
#' (\code{\link{fitted.cdp}}), residuals (\code{\link{residuals.cdp}}), and for
#' making predictions (\code{\link{predict.cdp}}).
#'
#' Function \code{\link{eigenmap}} calculates spatial eigenvector maps following
#' the approach outlined in Dray et al. (2006), and which are necessary to
#' calculate \code{\link{MCA}}. It returns a \link{eigenmap-class} object. The
#' package also features methods to print (\code{\link{print.eigenmap}}) and
#' plot (\code{\link{plot.eigenmap}}) these objects. Function
#' \code{\link{eigenmap.score}} can be used to make predictions for spatial
#' models built from the eigenfunctions of \code{\link{eigenmap}} using
#' distances between one or more target locations and the sampled locations for
#' which the spatial eigenvector map was built.
#'
#' The package also features an exemplary dataset \link{salmon} containing 76
#' sampling site positions along a 1520 m river segment. It also contains
#' functions \code{\link{cthreshold}} and \code{\link{minpermute}}, which
#' compute the testwise type I error rate threshold corresponding to a given
#' familywise threshold and the minimal number of permutations needed for
#' testing Multiscale Codependence Analysis given the alpha threshold,
#' respectively.
#'
#' The DESCRIPTION file:
#' \packageDESCRIPTION{codep}
#' \packageIndices{codep}
#'
#' @author \packageAuthor{codep}
#' Maintainer: \packageMaintainer{codep}
#'
#' @references
#' Dray, S.; Legendre, P. and Peres-Neto, P. 2006. Spatial modelling: a
#' comprehensive framework for principal coordinate analysis of neighbor
#' matrices (PCNM). Ecol. Modelling 196: 483-493
#'
#' Guénard, G., Legendre, P., Boisclair, D., and Bilodeau, M. 2010. Multiscale
#' codependence analysis: an integrated approach to analyse relationships across
#' scales. Ecology 91: 2952-2964
#'
#' Guénard, G. Legendre, P. 2018. Bringing multivariate support to multiscale
#' codependence analysis: Assessing the drivers of community structure across
#' spatial scales. Meth. Ecol. Evol. 9: 292-304
#'
#' @seealso
#' Legendre, P. and Legendre, L. 2012. Numerical Ecology, 3rd English edition.
#' Elsevier Science B.V., Amsterdam, The Neatherlands.
#'
#' @examples
#' data(mite)
#' emap <- eigenmap(x = mite.geo, weighting = wf.RBF, wpar = 0.1)
#' emap
#'
#' ## Organize the environmental variables
#' mca0 <- MCA(Y = log1p(mite.species), X = mite.env, emobj = emap)
#' mca0_partest <- test.cdp(mca0, response.tests = FALSE)
#' summary(mca0_partest)
#' plot(mca0_partest, las = 2, lwd = 2)
#' plot(mca0_partest, col = rainbow(1200)[1L:1000], las = 3, lwd = 4,
#' main = "Codependence diagram", col.signif = "white")
#'
#' rng <- list(x = seq(min(mite.geo[,"x"]) - 0.1, max(mite.geo[,"x"]) + 0.1, 0.05),
#' y = seq(min(mite.geo[,"y"]) - 0.1, max(mite.geo[,"y"]) + 0.1, 0.05))
#' grid <- cbind(x = rep(rng[["x"]], length(rng[["y"]])),
#' y = rep(rng[["y"]], each = length(rng[["x"]])))
#' newdists <- matrix(NA, nrow(grid), nrow(mite.geo))
#' for(i in 1L:nrow(grid)) {
#' newdists[i,] <- ((mite.geo[,"x"] - grid[i,"x"])^2 +
#' (mite.geo[,"y"] - grid[i,"y"])^2)^0.5
#' }
#'
#' spmeans <- colMeans(mite.species)
#' pca0 <- svd(log1p(mite.species) - rep(spmeans, each = nrow(mite.species)))
#'
#' prd0 <- predict(
#' mca0_partest,
#' newdata = list(target = eigenmap.score(emap, newdists))
#' )
#' Uprd0 <- (prd0 - rep(spmeans, each = nrow(prd0))) %*% pca0$v %*%
#' diag(pca0$d^-1)
#'
#' ## Printing the response variable
#' prmat <- Uprd0[,1L]
#' dim(prmat) <- c(length(rng$x), length(rng$y))
#' zlim <- c(min(min(prmat), min(pca0$u[,1L])), max(max(prmat), max(pca0$u[,1L])))
#' image(z = prmat, x = rng$x, y = rng$y, asp = 1, zlim = zlim,
#' col = rainbow(1200L)[1L:1000], ylab = "y", xlab = "x")
#' points(
#' x = mite.geo[,"x"], y = mite.geo[,"y"], pch = 21,
#' bg = rainbow(1200L)[round(1+(999*(pca0$u[,1L] - zlim[1L])/
#' (zlim[2L] - zlim[1L])),0)]
#' )
#'
NULL
#'
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.