add descriptions & details to coercer documentation

Author: corybrunson

.Rbuildignore

@@ -10,5 +10,8 @@
 ^LICENSE\.md$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+
+# R package
+^man-roxygen$
 ^cran-comments\.md$
 ^CRAN-SUBMISSION$

NAMESPACE

@@ -5,30 +5,25 @@ S3method(as_cmplx,default)
 S3method(as_cmplx,gudhi.simplex_tree.SimplexTree)
 S3method(as_cmplx,igraph)
 S3method(as_cmplx,network)
-S3method(as_cmplx,simplextree)
 S3method(as_igraph,Rcpp_SimplexTree)
 S3method(as_igraph,default)
 S3method(as_igraph,gudhi.simplex_tree.SimplexTree)
 S3method(as_igraph,igraph)
 S3method(as_igraph,network)
-S3method(as_igraph,simplextree)
 S3method(as_network,Rcpp_SimplexTree)
 S3method(as_network,default)
 S3method(as_network,gudhi.simplex_tree.SimplexTree)
 S3method(as_network,igraph)
 S3method(as_network,network)
-S3method(as_network,simplextree)
 S3method(as_py_gudhi,Rcpp_SimplexTree)
 S3method(as_py_gudhi,default)
 S3method(as_py_gudhi,igraph)
 S3method(as_py_gudhi,network)
-S3method(as_py_gudhi,simplextree)
 S3method(as_simplextree,Rcpp_SimplexTree)
 S3method(as_simplextree,default)
 S3method(as_simplextree,gudhi.simplex_tree.SimplexTree)
 S3method(as_simplextree,igraph)
 S3method(as_simplextree,network)
-S3method(as_simplextree,simplextree)
 export(as_cmplx)
 export(as_igraph)
 export(as_network)

R/as-cmplx.r

@@ -1,6 +1,18 @@
-#' @title Coerce objects to lists in the TDA package style
+#' @title Coerce objects to lists of simplices
+#'
+#' @description Coerce objects to lists of simplices, as used by
+#'   [the TDA package][TDA::TDA-package].
+#'
+#' @details
+#'
+#' `as_cmplx()` is a generic function with specific methods for different
+#' simplicial complex S3 classes. It returns a list of integer vectors, each of
+#' which represents a simplex, and _all_ simplices are included in the list.
+#' When a filtration is constructed using `TDA::*Filtration()`, the first named
+#' element of the returned list, `cmplx`, is a list whose *i*th element
+#' contains the vertices of the *i*th simplex.
 #' 
-#' @description This generic function...
+#' @template sec-classes-methods
 #' 
 #' @param x An R object to be coerced. See Details.
 #' @param index Integer-valued vertex attribute to be used as 0-simplex indices.
@@ -28,12 +40,6 @@ as_cmplx.Rcpp_SimplexTree <- function(x, ...) {
   simplextree_list(x)
 }
 
-#' @rdname as_cmplx
-#' @export
-as_cmplx.simplextree <- function(x, ...) {
-  as_cmplx.Rcpp_SimplexTree(x, ...)
-}
-
 #' @rdname as_cmplx
 #' @export
 as_cmplx.gudhi.simplex_tree.SimplexTree <- function(x, ...) {

R/as-igraph.r

@@ -1,7 +1,16 @@
 #' @title Coerce objects to class 'igraph'
-#' 
-#' @description This generic function...
-#' 
+#'
+#' @description Coerce objects to 'igraph' objects, as implemented in
+#'   [the igraph package][igraph::igraph-package].
+#'
+#' @details
+#'
+#' `as_igraph()` is a generic function with specific methods for different
+#' simplicial complex S3 classes. It returns an [igraph][igraph::igraph] object.
+#'
+#' @template sec-classes-methods
+#' @template to-graph
+#'
 #' @param x An R object to be coerced. See Details.
 #' @param index Character string to be added as a vertex attribute containing
 #'   0-simplex indices. Ignored if `NULL` (the default).
@@ -56,12 +65,6 @@ as_igraph.Rcpp_SimplexTree <- function(x, index = NULL, ...) {
   res
 }
 
-#' @rdname as_igraph
-#' @export
-as_igraph.simplextree <- function(x, index = NULL, ...) {
-  as_igraph.Rcpp_SimplexTree(x, index = index, ...)
-}
-
 #' @rdname as_simplextree
 #' @export
 as_igraph.gudhi.simplex_tree.SimplexTree <- function(x, index = NULL, ...) {

R/as-network.r

@@ -1,6 +1,16 @@
 #' @title Coerce objects to class 'network'
 #'
-#' @description This generic function...
+#' @description Coerce objects to 'network' objects, as implemented in
+#'   [the network package][network::network-package].
+#'
+#' @details
+#'
+#' `as_network()` is a generic function with specific methods for different
+#' simplicial complex S3 classes. It returns a [network][network::network]
+#' object.
+#'
+#' @template sec-classes-methods
+#' @template to-graph
 #'
 #' @param x An R object to be coerced. See Details.
 #' @param index Character string to be added as a vertex attribute containing
@@ -79,12 +89,6 @@ as_network.Rcpp_SimplexTree <- function(x, index = NULL, ...) {
   res
 }
 
-#' @rdname as_network
-#' @export
-as_network.simplextree <- function(x, index = NULL, ...) {
-  as_network.Rcpp_SimplexTree(x, index = index, ...)
-}
-
 #' @rdname as_network
 #' @export
 as_network.gudhi.simplex_tree.SimplexTree <- function(x, index = NULL, ...) {

R/as-py-gudhi.r

@@ -1,12 +1,24 @@
-#' @title Coerce objects to GUDHI simplex trees
-#' 
-#' @description This generic function...
-#' 
+#' @title Coerce objects to Python GUDHI simplex trees
+#'
+#' @description Coerce objects to 'SimplexTree' objects in Python GUDHI,
+#'   accessed via [the reticulate package][reticulate::reticulate].
+#'
+#' @details
+#'
+#' `as_py_gudhi()` is a generic function with specific methods for different
+#' simplicial complex S3 classes. It returns an object of class
+#' 'gudhi.simplex_tree.SimplexTree', which is a
+#' [reticulate][reticulate::reticulate] accessor to a Python object of class
+#' 'SimplexTree' implemented in GUDHI.
+#'
+#' @template sec-classes-methods
+#'
 #' @param x An R object to be coerced. See Details.
 #' @param index Integer-valued vertex attribute to be used as 0-simplex indices.
 #'   Ignored if `NULL` (the default).
 #' @param ... Additional arguments passed to methods.
-#' @return A list of integer vectors, each encoding one simplex.
+#' @return A simplex tree instantiated in Python GUDHI accessed through
+#'   reticulate.
 #' @example inst/examples/ex-as-py-gudhi.r
 #' @author Jason Cory Brunson
 #' @author Yara Skaf
@@ -56,12 +68,6 @@ as_py_gudhi.Rcpp_SimplexTree <- function(x, ...) {
   res
 }
 
-#' @rdname as_py_gudhi
-#' @export
-as_py_gudhi.simplextree <- function(x, ...) {
-  as_py_gudhi.Rcpp_SimplexTree(x, ...)
-}
-
 #' @rdname as_py_gudhi
 #' @export
 as_py_gudhi.igraph <- function(x, index = NULL, ...) {

R/as-simplextree.r

@@ -1,12 +1,24 @@
 #' @title Coerce objects to class 'simplextree'
 #'
-#' @description This generic function...
+#' @description Coerce objects to 'Rcpp_SimplexTree' objects, as implemented in
+#'   [the simplextree package][simplextree::simplextree-package].
+#'
+#' @details
+#'
+#' `as_simplextree()` is a generic function with specific methods for different
+#' simplicial complex S3 classes. It returns an object of class
+#' ['Rcpp_SimplexTree'][simplextree::Rcpp_SimplexTree], which is an [Rcpp
+#' Module][Rcpp::Module] that exposes an instance of a C++ instance of a simplex
+#' tree.
+#'
+#' @template sec-classes-methods
 #'
 #' @param x An R object to be coerced. See Details.
 #' @param index Integer-valued vertex attribute to be used as 0-simplex indices.
 #'   Ignored if `NULL` (the default).
 #' @param ... Additional arguments passed to methods.
-#' @return An object of class 'simplextree'.
+#' @return An instance of a simplex tree, exposed as an Rcpp Module with class
+#'   'Rcpp_SimplexTree'.
 #' @example inst/examples/ex-as-simplextree.r
 #' @export
 as_simplextree <- function(x, ...) UseMethod("as_simplextree")
@@ -27,12 +39,6 @@ as_simplextree.default <- function(x, ...) {
 #' @export
 as_simplextree.Rcpp_SimplexTree <- function(x, ...) x
 
-#' @rdname as_simplextree
-#' @export
-as_simplextree.simplextree <- function(x, ...) {
-  as_simplextree.Rcpp_SimplexTree(x, ...)
-}
-
 #' @rdname as_simplextree
 #' @export
 as_simplextree.gudhi.simplex_tree.SimplexTree <- function(x, ...) {

R/interplex-package.r

@@ -30,11 +30,6 @@
 #'   as implemented
 #'   in [the network package][network::network-package]
 
-#'
-#' When coercing from a simplicial complex structure to a graph structure,
-#' only the 1-skeleton is coerced; simplices of dimension > 1 are discarded
-#' and no warning is printed.
-
 #' @docType package
 #' @name interplex
 NULL

inst/examples/ex-as-cmplx.r

@@ -15,6 +15,7 @@ cp_st <- as_cmplx(st)
 print(cp_st)
 
 \dontrun{
+
 # convert a Python GUDHI simplex tree
 gd <- reticulate::import("gudhi")
 gd_st <- gd$SimplexTree()

inst/examples/ex-as-igraph.r

@@ -17,6 +17,7 @@ ig_st <- as_igraph(st)
 print(ig_st)
 
 \dontrun{
+
 # convert a Python GUDHI simplex tree
 gd <- reticulate::import("gudhi")
 gd_st <- gd$SimplexTree()

inst/examples/ex-as-network.r

@@ -17,6 +17,7 @@ nw_st <- as_network(st)
 print(nw_st)
 
 \dontrun{
+
 # convert a Python GUDHI simplex tree
 gd <- reticulate::import("gudhi")
 gd_st <- gd$SimplexTree()

inst/examples/ex-as-py-gudhi.r

@@ -1,4 +1,5 @@
 \dontrun{
+
 # print GUDHI simplices
 print_py_gudhi <- function(x) {
   reticulate::iterate(

inst/examples/ex-as-simplextree.r

@@ -11,6 +11,7 @@ st_rf2 <- as_simplextree(rf$cmplx)
 print(st_rf2)
 
 \dontrun{
+
 # convert a Python GUDHI simplex tree
 gd <- reticulate::import("gudhi")
 gd_st <- gd$SimplexTree()

man-roxygen/sec-classes-methods.r

@@ -0,0 +1,8 @@
+#' 
+#' The generic coercers recognize the following S3 classes during method
+#' dispatch: 'Rcpp_SimplexTree', 'gudhi.simplex_tree.SimplexTree', 'igraph', and
+#' 'network'. In case `x` matches none of these classes, the default method
+#' requires `x` to be a list of integer vectors representing simplices, or else
+#' a list with a named element `cmplx` having this structure, as used in
+#' [TDA::TDA-package].
+#' 

man-roxygen/to-graph.r

@@ -0,0 +1,5 @@
+#'
+#' When coercing from a simplicial complex structure to a graph structure,
+#' only the 1-skeleton is coerced; simplices of dimension > 1 are discarded
+#' and no warning is printed.
+#'