docs for data_list, towards mjskay#8

R/compose_data.R

@@ -4,72 +4,40 @@
 ###############################################################################
 
 
-#' A data_list for input into a Bayesian sampler
+#' Data lists for input into a Bayesian sampler
 #'
-#' Used by \code{\link{compose_data}} to create lists of data suitable for
-#' input into a Bayesian sampler.  This typically should not be called directly
-#' (instead use \code{\link{compose_data}}) unless you need to implement your
-#' own conversion routines for a data type not already supported.
+#' Functions used by \code{\link{compose_data}} to create lists of data suitable for
+#' input into a Bayesian sampler. \textbf{These functions typically should not be called directly}
+#' (instead use \code{\link{compose_data}}), but are exposed for the rare cases in which
+#' you may need to provide your own conversion routines for a data type not already
+#' supported (see `Details`).
 #'
-#' This function creates a list with class \code{c("data_list", "list")}
-#' instead of \code{c("list")}, but otherwise acts like the \code{\link{list}}
-#' function.  It is used by \code{\link{as_data_list}} to create data lists for
-#' input into Bayesian samplers. See the implementations of
-#' \code{as_data_list.numeric}, \code{as_data_list.logical}, etc for examples.
+#' \code{data_list} creates a list with class \code{c("data_list", "list")}
+#' instead of \code{c("list")}, but largely otherwise acts like the \code{\link{list}}
+#' function.
 #'
-#' @param ...  Items to include in the list.
-#' @return An object of class \code{c("data_list", "list")}
-#' @author Matthew Kay
-#' @seealso \code{\link{compose_data}}, \code{\link{spread_samples}}, \code{\link{gather_samples}}.
-#' @keywords manip
-#' @export
-data_list = function(...) {
-  x = list(...)
-  class(x) = c("data_list", "list")
-  x
-}
-#' @export
-c.data_list = function(x, ..., recursive=FALSE) {
-  class(x) = class(x)[-which(class(x) == "data_list")]
-  x = c(x, ..., recursive = recursive)
-  class(x) = c("data_list", class(x))
-  x
-}
-#' @export
-print.data_list = function(x, ...) {
-  cat("data_list:\n\n")
-  class(x) = class(x)[-which(class(x) == "data_list")]
-  print(x, ...)
-}
-
-
-#' Convert data into a data_list
+#' \code{as_data_list} recursively translates its first argument into list elements,
+#' concatenating all resulting lists together. By default this means that:
 #'
-#' Used by \code{\link{compose_data}} to create lists of data suitable for
-#' input into a Bayesian sampler.  This typically should not be called directly
-#' (instead use \code{\link{compose_data}}) unless you need to implement your
-#' own conversion routines for a data type not already supported (see
-#' `Details`).
+#' \itemize{
+#'  \item numerics are included as-is.
+#'  \item logicals are translated into numeric using \code{\link{as.numeric}}.
+#'  \item factors are translated into numeric using \code{\link{as.numeric}}, and an additional element named
+#'    \code{.n_name(name)} is added with the number of levels in the factor.
+#'  \item character vectors are converted into factors then translated into numeric in the same manner as factors are.
+#'  \item lists are translated by translating all elements of the list
+#'    (recursively) and adding them to the result.
+#'  \item data.frames are translated by translating every column of the data.frame and adding them to
+#'    the result. A variable named \code{"n"} (or \code{.n_name(name)} if \code{name} is not \code{""})
+#'    is also added containing the number of rows in the data frame.
+#'  \item all other types are dropped (and a warning given)
+#' }
 #'
-#' This function recursively translates its first argument into list elements,
-#' concatenating all resulting lists together. By default this means that:
-#' \itemize{ \item numerics are included as-is.  \item logicals are translated
-#' into numeric using \code{\link{as.numeric}}.  \item factors are translated
-#' into numeric using \code{\link{as.numeric}}, and an additional element named
-#' \code{.n_name(name)} is added with the number of levels in the factor.
-#' \item lists are translated by translating all elements of the list
-#' (recursively) and adding them to the result.  \item data.frames are
-#' translated by translating every column of the data.frame and adding them to
-#' the result.  A variable named \code{"n"} (or \code{.n_name(name)} if
-#' \code{name} is not \code{""}) is also added containing the number of rows in
-#' the data frame.  \item all other types are dropped (and a warning given) }
 #' If you wish to add support for additional types not described above, provide
 #' an implementation of \code{\link{as_data_list}} for the type. See the
 #' implementations of \code{as_data_list.numeric}, \code{as_data_list.logical},
 #' etc for examples.
 #'
-#' as_data_list.logical as_data_list.factor as_data_list.list
-#' as_data_list.data.frame as_data_list.data_list
 #' @param object The object to convert (see `Details`).
 #' @param name The name of the element in the returned list corresponding to
 #' this object.
@@ -84,25 +52,50 @@ print.data_list = function(x, ...) {
 #' \code{.n_name("foo")}, which by default would be "n_foo", containing the
 #' value 3.
 #' @param ...  Additional arguments passed to other implementations of
-#' \code{as_data_list}.
+#' \code{as_data_list}, or for \code{data_list}, passed to \code{\link{list}}.
 #' @return An object of class \code{c("data_list", "list")}, where each element
 #' is a translated variable as described above.
 #' @author Matthew Kay
-#' @seealso \code{\link{compose_data}}, \code{\link{spread_samples}}, \code{\link{gather_samples}}.
+#' @seealso \code{\link{compose_data}}.
 #' @keywords manip
 #' @examples
 #'
-#' ##TODO
+#' # Typically these functions should not be used directly.
+#' # See the compose_data function for examples of how to translate
+#' # data in lists for input to Bayesian samplers.
 #'
+#' @name data_list
+#' @export
+data_list = function(...) {
+  x = list(...)
+  class(x) = c("data_list", "list")
+  x
+}
+#' @export
+c.data_list = function(x, ..., recursive=FALSE) {
+  class(x) = class(x)[-which(class(x) == "data_list")]
+  x = c(x, ..., recursive = recursive)
+  class(x) = c("data_list", class(x))
+  x
+}
+#' @export
+print.data_list = function(x, ...) {
+  cat("data_list:\n\n")
+  class(x) = class(x)[-which(class(x) == "data_list")]
+  print(x, ...)
+}
+
+
+#' @rdname data_list
 #' @export
 as_data_list = function(object, name = "", ...) UseMethod("as_data_list")
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.default = function(object, name = "", ...) {
   warning(deparse0(name), " has unsupported type ", deparse0(class(object)), " and was dropped.")
   data_list()
 }
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.numeric = function(object, name = "",
   scalar_as_array = FALSE,  #treat single scalar values as array of length 1
@@ -114,12 +107,12 @@ as_data_list.numeric = function(object, name = "",
   names(data) = name
   data
 }
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.logical = function(object, name = "", ...) {
   as_data_list(as.numeric(object), name = name, ...)
 }
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.factor = function(object, name = "", .n_name = n_prefix("n"), ...) {
   data = as_data_list(as.numeric(object), name = name, .n_name = .n_name, ...)
@@ -130,12 +123,12 @@ as_data_list.factor = function(object, name = "", .n_name = n_prefix("n"), ...)
   data[[.n_name(name)]] = length(levels(object))
   data
 }
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.character = function(object, name="", ...) {
   as_data_list(as.factor(object), name = name, ...)
 }
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.list = function(object, name="", ...) {
   #go through list and translate variables
@@ -145,7 +138,7 @@ as_data_list.list = function(object, name="", ...) {
   }
   data
 }
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.data.frame = function(object, name="", .n_name = n_prefix("n"), ...) {
   #first, translate all variables in the data frame
@@ -160,7 +153,7 @@ as_data_list.data.frame = function(object, name="", .n_name = n_prefix("n"), ...
   data[[n_name]] = nrow(object)
   data
 }
-#' @rdname as_data_list
+#' @rdname data_list
 #' @export
 as_data_list.data_list = function(object, name="", ...) {
   object
@@ -184,6 +177,8 @@ as_data_list.data_list = function(object, name="", ...) {
 #'          function prefixes \code{"n_"} before the factor name; e.g. a factor
 #'          named \code{foo} will have an element named \code{n_foo} added containing
 #'          the number of levels in \code{foo}.
+#'      \item character vectors are converted into factors then translated into numeric
+#'          in the same manner as factors are.
 #'      \item lists are translated by translating all elements of the list
 #'          (recursively) and adding them to the result.
 #'      \item data.frames are translated by translating every column of the data.frame
@@ -227,8 +222,8 @@ as_data_list.data_list = function(object, name="", ...) {
 #' containing the value 20. See \code{\link{n_prefix}}.
 #' @return A list where each element is a translated variable as described above.
 #' @author Matthew Kay
-#' @seealso \code{\link{as_data_list}}, \code{\link{spread_samples}},
-#' \code{\link{gather_samples}}, \code{\link{x_at_y}}
+#' @seealso \code{\link{x_at_y}}, \code{\link{spread_samples}},
+#' \code{\link{gather_samples}}.
 #' @keywords manip
 #' @examples
 #'
@@ -298,7 +293,7 @@ compose_data = function(..., .n_name = n_prefix("n")) {
 #' named \code{"n_foo"} (the result of \code{n_prefix("n")("foo")}) equal to the
 #' number of levels in \code{df$foo}.
 #'
-#' @seealso The \code{.n_name} argument of \code{\link{compose_data}}
+#' @seealso The \code{.n_name} argument of \code{\link{compose_data}}.
 #'
 #' @export
 n_prefix = function(prefix) {