Merge pull request #155 from mcol/fix_14

Add iter1 option to mcmc_trace() to start iteration counting after warmup

NEWS.md

@@ -4,45 +4,57 @@
 
 Items for next release go here
 
+* [`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)
+
 
 # bayesplot 1.6.0
 
 (GitHub issue/PR numbers in parentheses)
 
-* Loading **bayesplot** no longer overrides the ggplot theme! Rather, it sets a
-theme specific for **bayesplot**. Some packages using **bayesplot** may still
-override the default **ggplot** theme  (e.g., **rstanarm** does but only until
-next release), but simply loading **bayesplot** itself will not.  There are new
-functions for controlling the ggplot theme for **bayesplot** that work like
-their **ggplot2** counterparts but only affect plots made using **bayesplot**.
-Thanks to Malcolm Barrett. (#117, #149).    
-    - `bayesplot_theme_set()` 
-    - `bayesplot_theme_get()` 
+* Loading **bayesplot** no longer overrides the ggplot theme! Rather, it sets
+  a theme specific for **bayesplot**. Some packages using **bayesplot** may
+  still override the default **ggplot** theme (e.g., **rstanarm** does but
+  only until next release), but simply loading **bayesplot** itself will not.
+  There are new functions for controlling the ggplot theme for **bayesplot**
+  that work like their **ggplot2** counterparts but only affect plots made
+  using **bayesplot**. Thanks to Malcolm Barrett. (#117, #149).
+    - `bayesplot_theme_set()`
+    - `bayesplot_theme_get()`
     - `bayesplot_theme_update()`
     - `bayesplot_theme_replace()`
 
-* The [Visual MCMC Diagnostics vignette](http://mc-stan.org/bayesplot/articles/visual-mcmc-diagnostics.html) 
-has been reorganized and has a lot of useful new content thanks to Martin Modrák. (#144, #153)
+* The [Visual MCMC Diagnostics
+  vignette](http://mc-stan.org/bayesplot/articles/visual-mcmc-diagnostics.html)
+  has been reorganized and has a lot of useful new content thanks to Martin
+  Modrák. (#144, #153)
+
+* The [LOO predictive
+  checks](http://mc-stan.org/bayesplot/reference/PPC-loo.html) now require
+  **loo** version `>= 2.0.0`. (#139)
+
+* Histogram plots gain a `breaks` argument that can be used as an alternative
+  to `binwidth`. (#148)
 
-* The [LOO predictive checks](http://mc-stan.org/bayesplot/reference/PPC-loo.html) 
-now require **loo** version `>= 2.0.0`. (#139)
+* [`mcmc_pairs()`](http://mc-stan.org/bayesplot/reference/MCMC-scatterplots.html)
+  now has an argument `grid_args` to provide a way of passing optional
+  arguments to `gridExtra::arrangeGrob()`. This can be used to add a title to
+  the plot, for example. (#143)
 
-* Histogram plots gain a `breaks` argument that can be used as an alternative to `binwidth`. (#148)
+* [`ppc_ecdf_overlay()`](http://mc-stan.org/bayesplot/reference/PPC-distributions.html)
+  gains an argument `discrete`, which is `FALSE` by default, but can be used
+  to make the Geom more appropriate for discrete data. (#145)
 
-* [`mcmc_pairs()`](http://mc-stan.org/bayesplot/reference/MCMC-scatterplots.html) 
-now has an argument `grid_args` to provide a way of passing optional arguments to 
-`gridExtra::arrangeGrob()`. This can be used to add a title to the plot, for example. (#143)
+* [PPC intervals 
+  plots](http://mc-stan.org/bayesplot/reference/PPC-intervals.html) and [LOO
+  predictive checks](http://mc-stan.org/bayesplot/reference/PPC-loo.html) now
+  draw both an outer and an inner probability interval, which can be
+  controlled through the new argument `prob_outer` and the already existing
+  `prob`. This is consistent with what is produced by `mcmc_intervals()`.
+  (#152, #154, @mcol)
 
-* [`ppc_ecdf_overlay()`](http://mc-stan.org/bayesplot/reference/PPC-distributions.html) 
-gains an argument `discrete`, which is `FALSE` by default, but can be used to make the 
-Geom more appropriate for discrete data. (#145)
 
-* [PPC intervals plots](http://mc-stan.org/bayesplot/reference/PPC-intervals.html)
-and [LOO predictive checks](http://mc-stan.org/bayesplot/reference/PPC-loo.html)
-now draw both an outer and an inner probability interval, which can be
-controlled through the new argument `prob_outer` and the already existing
-`prob`. This is consistent with what is produced by `mcmc_intervals()`.
-(#152, #154, @mcol)
 
 
 # bayesplot 1.5.0
@@ -75,7 +87,10 @@ controlled through the new argument `prob_outer` and the already existing
 * Added `ppc_loo_pit_overlay()` function for a better LOO PIT predictive check.
   (#123)
 
-* Started using __vdiffr__ to add visual unit tests to the existing PPC unit tests. (#137)
+* Started using **vdiffr** to add visual unit tests to the existing PPC unit
+  tests. (#137)
+
+
 
 
 # bayesplot 1.4.0

R/mcmc-traces.R

@@ -22,6 +22,10 @@
 #'   \code{x}. The default is \code{n_warmup = 0}, i.e. to assume no warmup
 #'   iterations are included. If \code{n_warmup > 0} then the background for
 #'   iterations \code{1:n_warmup} is shaded gray.
+#' @param iter1 An integer; the iteration number of the first included draw
+#'   (default 0). This can be used to make it more obvious that the warmup
+#'   iterations have been discarded from the traceplot. It cannot be specified
+#'   if \code{n_warmup} is also set to a positive value.
 #' @param window An integer vector of length two specifying the limits of a
 #'   range of iterations to display.
 #' @param np For models fit using \code{\link{NUTS}} (more generally, any
@@ -146,6 +150,7 @@ mcmc_trace <-
            facet_args = list(),
            ...,
            n_warmup = 0,
+           iter1 = 0,
            window = NULL,
            size = NULL,
            np = NULL,
@@ -183,6 +188,7 @@ mcmc_trace <-
       style = "line",
       np = np,
       np_style = np_style,
+      iter1 = iter1,
       ...
     )
   }
@@ -261,11 +267,24 @@ trace_style_np <-
                         alpha = 0.2,
                         np = NULL,
                         np_style = trace_style_np(),
+                        iter1 = 0,
                         ...) {
 
   style <- match.arg(style)
   x <- prepare_mcmc_array(x, pars, regex_pars, transformations)
 
+  if (iter1 < 0) {
+    stop(
+      "'iter1' cannot be negative."
+    )
+  }
+
+  if (n_warmup > 0 && iter1 > 0) {
+    stop(
+      "'n_warmup' and 'iter1' can't both be specified."
+    )
+  }
+
   if (!is.null(highlight)) {
     if (!has_multiple_chains(x))
       STOP_need_multiple_chains()
@@ -287,10 +306,10 @@ trace_style_np <-
   geom_args$size <- size %||% ifelse(style == "line", 1/3, 1)
 
   if (is.null(highlight)) {
-    mapping <- aes_(x = ~ Iteration, y = ~ Value, color = ~ Chain)
+    mapping <- aes_(x = ~ Iteration + iter1, y = ~ Value, color = ~ Chain)
   } else {
     stopifnot(length(highlight) == 1)
-    mapping <- aes_(x = ~ Iteration,
+    mapping <- aes_(x = ~ Iteration + iter1,
                     y = ~ Value,
                     alpha = ~ Chain == highlight,
                     color = ~ Chain == highlight)

tests/testthat/test-mcmc-traces.R

@@ -38,6 +38,9 @@ test_that("mcmc_trace options work", {
   expect_gg(g2 <- mcmc_trace(arr, regex_pars = "beta", n_warmup = 10))
   ll <- g2$labels
   expect_true(all(c("xmin", "xmax", "ymin", "ymax") %in% names(ll)))
+
+  expect_error(mcmc_trace(arr, iter1 = -1))
+  expect_error(mcmc_trace(arr, n_warmup = 50, iter1 = 20))
 })