Adds some docs to the package

DESCRIPTION

@@ -17,16 +17,19 @@ Imports: MASS,
     mvtnorm,
     stats,
     doParallel,
-    foreach
+    foreach,
+    Rdpack
 Suggests: knitr,
     rmarkdown,
     roxygen2,
     vegan
+RdMacros: Rdpack
 VignetteBuilder: knitr
 Collate: 
     'internals.R'
     'procmod_frame.R'
     'multivariate.R'
+    'procmod.R'
     'covls.R'
     'corls_test.R'
     'procuste.R'

NAMESPACE

@@ -40,3 +40,4 @@ export(varls)
 import(MASS)
 import(doParallel)
 import(foreach)
+importFrom(Rdpack,reprompt)

R/corls_test.R

@@ -6,9 +6,9 @@ NULL
 
 #' Generate permutation matrix according to a schema.
 #'
-#' @param perm
-#' @param n
-#' @param strata
+#' @param perm xxx
+#' @param n zzz
+#' @param strata eeee
 #'
 #'
 #' The permutation schema is defined using the `how` function.

R/covls.R

+#' @include procmod.R
 #' @include procmod_frame.R
 #' @include multivariate.R
 #' @import doParallel
@@ -12,6 +13,9 @@ registerDoParallel(1)
 
 #' Compute the trace of a square matrix.
 #'
+#' The trace of a square matrix is defined as the sum
+#' of its diagonal elements.
+#'
 #' @param X a square matrix
 #' @return the trace of X
 #'
@@ -20,16 +24,12 @@ registerDoParallel(1)
 #' ProcMod:::.Trace(m)
 #' @note Internal function do not use.
 #'
-#' @rdname internal.getPermuteMatrix
+#' @rdname internal.Trace
 #' @author Eric Coissac
 #' @author Christelle Gonindard-Melodelima
 #'
 .Trace <- function(X) sum(diag(X))
 
-.estimate_mode <- function(x) {
-  d <- density(x)
-  d$x[which.max(d$y)]
-}
 
 .var2cor <- function(c) {
   v <- sqrt(diag(c))
@@ -37,20 +37,62 @@ registerDoParallel(1)
   c / vv
 }
 
-#' Compute the variance, covariance matrix of K coordinate matrices.
+#' Compute the procrustean variance, covariance matrix of K matrices.
 #'
-#' Covariance between two matrices is defined as the sum of the
-#' sigular values of the X'Y matrix. All the matrices must have
+#' 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.
 #'
-#' @param ... the set of matrices
+#' \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}. .
+#'
+#' Before computing the covariances, matrices are projected into an
+#' orthogonal space using the \code{\link[ProcMod]{ortho}} function.
+#'
+#' @references{
+#'  \insertRef{Gower:71:00}{ProcMod}
+#'
+#'  \insertRef{Lingoes:74:00}{ProcMod}
+#'
+#'  \insertRef{Coissac-Eric:19:00}{ProcMod}
+#' }
+#'
+#' @param ...   the set of matrices or a \code{\link[ProcMod]{procmod.frame}}
+#'              object.
 #' @param nrand number of randomisation used to estimate the mean
 #'              covariance observed between two random matrix.
+#'              If rand is \code{NULL} or equal to \code{0}, no correction
+#'              is estimated and the raw procrustean covariances are
+#'              estimated.
 #' @param p.adjust.method the multiple test correction method used
-#'              to adjust p values. \code{p.adjust.method} belongs
-#'              one of the folowing values: "holm", "hochberg", "hommel",
-#'              "bonferroni", "BH", "BY", "fdr",  "none". The default is
-#'              set to "holm".
+#'              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"}.
+#'
+#' @return a \code{procmod.varls} object which corresponds to a numeric
+#'              matrix annotated by several attributes.
+#'
+#'              The following attribute is always added:
+#'
+#'              - \code{nrand} an integer value indicating the number of
+#'                randomisations used to estimate the mean of the random
+#'                covariance.
+#'
+#'              When \code{nrand} is greater than 0 a couple of attributes
+#'              is added:
+#'
+#'              - \code{rcovls} a numeric matrix containing the estimation
+#'                of the mean of the random covariance.
+#'
+#'              - \code{p.value} a numeric matrix containing the estimations
+#'                of the p.values of tests checking that the observed
+#'                covariance is larger than the mean of the random covariance.
+#'                p.values are corrected for multiple tests according to the
+#'                method specified by the \code{p.adjust.method} parameter.
 #'
 #' @examples
 #' # Build Three matrices of 3 rows.
@@ -60,6 +102,8 @@ registerDoParallel(1)
 #' # compute 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)
 #' @author Eric Coissac
 #' @author Christelle Gonindard-Melodelima
 #' @export

R/procmod.R

+#' @docType package
+#' @importFrom Rdpack reprompt
+NULL

R/procmod_frame.R

@@ -238,7 +238,7 @@ procmod.frame <- function(...,
       .siteNames(value[[i]]) <- NULL
   }
 
-  return(make_subS3Class(value, "procmod.frame"))
+  make_subS3Class(value, "procmod.frame")
 }
 
 #'
@@ -386,7 +386,8 @@ dim.procmod.frame <- function(x)
 #' @export
 `$<-.procmod.frame` <- function(x, name, value) {
   x[[name]] <- value
-  return(x)
+
+  x
 }
 
 #' @author Eric Coissac
@@ -437,7 +438,7 @@ dim.procmod.frame <- function(x)
     attr(y, "row.names") <- rownames(y[[1]])
   }
 
-  return(y)
+  y
 }
 
 #' @author Eric Coissac
@@ -469,5 +470,6 @@ subset.procmod.frame <- function(x, subset, select, drop = FALSE, ...) {
 #' @export
 as.list.procmod.frame <- function(x, ...) {
   class(x) <- "list"
-  return(x)
+
+  x
 }

R/procuste.R

@@ -11,7 +11,7 @@ NULL
 #'
 #' The optimal rotation is computed according to the procruste methode.
 #' Rotation is based on singular value decomposition (SVD).
-#' No scaling is done, only the rotation.
+#' No scaling and no centrering are done, before computing the SVD.
 #'
 #' @param src a numeric matrix to be rotated
 #' @param dest a numeric matrix used as reference space