Merge pull request #287 from thibautjombart/snapclust_doc

adding doc for snapclust

DESCRIPTION

@@ -102,7 +102,7 @@ Suggests:
     poppr
 Encoding: UTF-8
 LazyLoad: yes
-RoxygenNote: 7.1.0
+RoxygenNote: 7.1.1
 Collate:
     'adegenet.package.R'
     'datasets.R'

R/snapclust.R

@@ -1,7 +1,22 @@
 #' Maximum-likelihood genetic clustering using EM algorithm
 #'
-#' Do not use. We work on that stuff. Contact us if interested.
-#'
+#' This function implements the fast maximum-likelihood genetic clustering
+#' approach described in Beugin et al (2018). The underlying model is very close
+#' to the model implemented by STRUCTURE, but allows for much faster estimation
+#' of genetic clusters thanks to the use of the Expectation-Maximization (EM)
+#' algorithm. Optionally, the model can explicitely account for hybridization
+#' and detect different types of hybrids (see \code{hybrids} and
+#' \code{hybrid.coef} arguments). The method is fully documented in a dedicated
+#' tutorial which can be accessed using \code{adegenetTutorial("snapclust")}.
+#'
+#' @details The method is described in Beugin et al (2018) A fast likelihood
+#'   solution to the genetic clustering problem. Methods in Ecology and
+#'   Evolution \url{https://doi.org/10.1111/2041-210X.12968}. A dedicated
+#'   tutorial is available by typing \code{adegenetTutorial("snapclust")}.
+#'
+#' @seealso The function \code{\link{snapclust.choose.k}} to investigate the optimal
+#'   value number of clusters 'k'. 
+#' 
 #' @author Thibaut Jombart \email{thibautjombart@@gmail.com} and Marie-Pauline
 #' Beugin
 #'
@@ -128,7 +143,7 @@
 #'
 #' ## method with back-cross
 #' res2.back <- snapclust(y, k = 2, hybrids = TRUE, hybrid.coef = c(.25,.5))
-#'  compoplot(res2.hyb, col.pal = hybridpal(), n.col = 2)
+#' compoplot(res2.back, col.pal = hybridpal(), n.col = 2)
 #'
 #' }
 

R/snapclust.choose.k.R

@@ -1,7 +1,18 @@
-#' Choose the number of clusters for snapclust using BIC
-#'
-#' Do not use. We work on that stuff. Contact us if interested.
+#' Choose the number of clusters for snapclust using AIC, BIC or AICc
 #'
+#' This function implements methods for investigating the optimal number of
+#' genetic clusters ('k') using the fast maximum-likelihood genetic clustering
+#' approach described in Beugin et al (2018). The method runs
+#' \code{\link{snapclust}} for varying values of 'k', and computes the requested
+#' summary statistics for each clustering solution to assess goodness of
+#' fit. The method is fully documented in a dedicated tutorial which can be
+#' accessed using \code{adegenetTutorial("snapclust")}.
+#' 
+#' @details The method is described in Beugin et al (2018) A fast likelihood
+#'   solution to the genetic clustering problem. Methods in Ecology and
+#'   Evolution \url{https://doi.org/10.1111/2041-210X.12968}. A dedicated
+#'   tutorial is available by typing \code{adegenetTutorial("snapclust")}.
+#' 
 #' @author Thibaut Jombart \email{thibautjombart@@gmail.com}
 #'
 #' @export