Merge pull request #184 from stan-dev/coerce-to-array

Call as.array on input to prepare_mcmc_array()

Author: tjmahr

NEWS.md

@@ -6,6 +6,9 @@
 
 <!-- Items for next release go here* -->
 
+* MCMC plots now also accept objects with an `as.array` method as 
+  input. (#175, #184)
+
 * [`mcmc_trace()`](http://mc-stan.org/bayesplot/reference/MCMC-traces.html)
   gains an argument `iter1` which can be used to label the traceplot starting
   from the first iteration after warmup. (#14, #155, @mcol)

R/helpers-mcmc.R

@@ -12,14 +12,27 @@ prepare_mcmc_array <- function(x,
     x <- df_with_chain2array(x)
   } else if (is_chain_list(x)) {
     x <- chain_list2array(x)
+  } else if (is.data.frame(x)) {
+    # data frame without Chain column
+    x <- as.matrix(x)
+  } else if (!is.array(x)) {
+    x <- as.array(x)
+  }
+
+  stopifnot(is.matrix(x) || is.array(x))
+  if (is.array(x) && !(length(dim(x)) %in% c(2,3))) {
+    stop("Arrays should have 2 or 3 dimensions. See help('MCMC-overview').")
+  }
+  if (anyNA(x)) {
+    stop("NAs not allowed in 'x'.")
   }
-  x <- validate_mcmc_x(x)
 
   parnames <- parameter_names(x)
   pars <- select_parameters(
     explicit = pars,
     patterns = regex_pars,
-    complete = parnames)
+    complete = parnames
+  )
 
   # possibly recycle transformations (apply same to all pars)
   if (is.function(transformations) ||
@@ -152,21 +165,19 @@ df_with_chain2array <- function(x) {
 }
 
 
-# Check if an object is a list but not a data.frame
+# Check if an object is a list (but not a data.frame) that contains
+# all 2-D objects
 #
 # @param x object to check
 # @return TRUE or FALSE
 is_chain_list <- function(x) {
-  !is.data.frame(x) && is.list(x)
+  check1 <- !is.data.frame(x) && is.list(x)
+  dims <- sapply(x, function(chain) length(dim(chain)))
+  check2 <- isTRUE(all(dims == 2)) # all elements of list should be matrices/2-D arrays
+  check1 && check2
 }
 
 validate_chain_list <- function(x) {
-  stopifnot(is_chain_list(x))
-  dims <- sapply(x, function(chain) length(dim(chain)))
-  if (!isTRUE(all(dims == 2))) {
-    stop("If 'x' is a list then all elements must be matrices.")
-  }
-
   n_chain <- length(x)
   for (i in seq_len(n_chain)) {
     nms <- colnames(as.matrix(x[[i]]))
@@ -276,25 +287,6 @@ STOP_need_multiple_chains <- function(call. = FALSE) {
 }
 
 
-# Perform some checks on user's 'x' input for MCMC plots
-#
-# @param x User's 'x' input to one of the mcmc_* functions.
-# @return x, unless an error is thrown.
-validate_mcmc_x <- function(x) {
-  stopifnot(!is_df_with_chain(x), !is_chain_list(x))
-  if (is.data.frame(x)) {
-    x <- as.matrix(x)
-  }
-
-  stopifnot(is.matrix(x) || is.array(x))
-  if (anyNA(x)) {
-    stop("NAs not allowed in 'x'.")
-  }
-
-  x
-}
-
-
 # Validate that transformations match parameter names
 validate_transformations <-
   function(transformations = list(),

R/mcmc-overview.R

@@ -18,9 +18,9 @@
 #'  corresponds to a Markov chain. All of the matrices should have the same
 #'  number of iterations (rows) and parameters (columns), and parameters should
 #'  have the same names and be in the same order.
-#'  \item \strong{matrix}: A \code{\link{matrix}} with one column per parameter.
-#'  If using matrix there should only be a single Markov chain or all chains
-#'  should already be merged (stacked).
+#'  \item \strong{matrix (2-D array)}: A \code{\link{matrix}} with one column
+#'  per parameter. If using matrix there should only be a single Markov chain or
+#'  all chains should already be merged (stacked).
 #'  \item \strong{data frame}: There are two types of \link[=data.frame]{data
 #'  frames} allowed. Either a data frame with one column per parameter (if only
 #'  a single chain or all chains have already been merged), or a data frame with

man-roxygen/args-mcmc-x.R

@@ -1,3 +1,5 @@
 #' @param x A 3-D array, matrix, list of matrices, or data frame of MCMC draws.
 #'   The \link{MCMC-overview} page provides details on how to specify each these
-#'   allowed inputs.
+#'   allowed inputs. It is also possible to use an object with an
+#'   \code{as.array} method that returns the same kind of 3-D array described on
+#'   the \link{MCMC-overview} page.