R: ggplot2 for RStan

Plots {rstan} | R Documentation

## ggplot2 for RStan

### Description

Visual posterior analysis using ggplot2.

### Usage

      stan_plot(object, pars, include = TRUE, unconstrain = FALSE, ...)
      stan_trace(object, pars, include = TRUE, unconstrain = FALSE,
                inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...,
                window = NULL)
      stan_scat(object, pars, unconstrain = FALSE,
                inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...)
      stan_hist(object, pars, include = TRUE, unconstrain = FALSE,
                inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...)
      stan_dens(object, pars, include = TRUE, unconstrain = FALSE,
                inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...,
                separate_chains = FALSE)
      stan_ac(object, pars, include = TRUE, unconstrain = FALSE,
                inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...,
                separate_chains = FALSE, lags = 25, partial = FALSE)
      quietgg(gg)

### Arguments

`object` | A stanfit or stanreg object.
`pars` | Optional character vector of parameter names. If `object` is a stanfit object, the default is to show all user-defined parameters or the first 10 (if there are more than 10). If `object` is a stanreg object, the default is to show all (or the first 10) regression coefficients (including the intercept). For `stan_scat` only, `pars` should not be missing and should contain exactly two parameter names.
`include` | Should the parameters given by the `pars` argument be included (the default) or excluded from the plot?
`unconstrain` | Should parameters be plotted on the unconstrained space? Defaults to `FALSE`. Only available if `object` is a stanfit object.
`inc_warmup` | Should warmup iterations be included? Defaults to `FALSE`.
`nrow,ncol` | Passed to `facet_wrap`.
`...` | Optional additional named arguments passed to geoms (e.g. for `stan_trace` the geom is `geom_path` and we could specify `linetype`, `size`, `alpha`, etc.). For `stan_plot` there are also additional arguments that can be specified in `...` (see Details).
`window` | For `stan_trace` `window` is used to control which iterations are shown in the plot. See `traceplot`.
`separate_chains` | For `stan_dens`, should the density for each chain be plotted? The default is `FALSE`, which means that for each parameter the draws from all chains are combined. For `stan_ac`, if `separate_chains=FALSE` (the default), the autocorrelation is averaged over the chains. If `TRUE` each chain is plotted separately.
`lags` | For `stan_ac`, the maximum number of lags to show.
`partial` | For `stan_ac`, should partial autocorrelations be plotted instead? Defaults to `FALSE`.
`gg` | A ggplot object or an expression that creates one.

### Details

For `stan_plot`, there are additional arguments that can be specified in `...`. The optional arguments and their default values are:

`point_est = "median"`

  The point estimate to show. Either "median" or "mean".

`show_density = FALSE`

  Should kernel density estimates be plotted above the intervals?

`ci_level = 0.8`

  The posterior uncertainty interval to highlight. Central `100*ci_level`% intervals are computed from the quantiles of the posterior draws.

`outer_level = 0.95`

  An outer interval to also draw as a line (if `show_outer_line` is `TRUE`) but not highlight.

`show_outer_line = TRUE`

  Should the `outer_level` interval be shown or hidden? Defaults to = `TRUE` (to plot it).

`fill_color`, `outline_color`, `est_color`

  Colors to override the defaults for the highlighted interval, the outer interval (and density outline), and the point estimate.

### Value

A `ggplot` object that can be further customized using the ggplot2 package.

### Note

Because the rstan plotting functions use ggplot2 (and thus the resulting plots behave like `ggplot` objects), when calling a plotting function within a loop or when assigning a plot to a name (e.g., `graph <- plot(fit, plotfun = "rhat")`), if you also want the side effect of the plot being displayed you must explicity print it (e.g., `(graph <- plot(fit, plotfun = "rhat"))`, `print(graph <- plot(fit, plotfun = "rhat"))`).

### See Also

`List of RStan plotting functions`, `Plot options`

### Examples

    ## Not run:
    example("read_stan_csv")
    stan_plot(fit)
    stan_trace(fit)

    library(gridExtra)
    fit <- stan_demo("eight_schools")

    stan_plot(fit)
    stan_plot(fit, point_est = "mean", show_density = TRUE, fill_color = "maroon")

    # histograms
    stan_hist(fit)
    # suppress ggplot2 messages about default bindwidth
    quietgg(stan_hist(fit))
    quietgg(h <- stan_hist(fit, pars = "theta", binwidth = 5))

    # juxtapose histograms of tau and unconstrained tau
    tau <- stan_hist(fit, pars = "tau")
    tau_unc <- stan_hist(fit, pars = "tau", unconstrain = TRUE) +
                xlab("tau unconstrained")
    grid.arrange(tau, tau_unc)

    # kernel density estimates
    stan_dens(fit)
    (dens <- stan_dens(fit, fill = "skyblue", ))
    dens <- dens + ggtitle("Kernel Density Estimates\n") + xlab("")
    dens

    (dens_sep <- stan_dens(fit, separate_chains = TRUE, alpha = 0.3))
    dens_sep + scale_fill_manual(values = c("red", "blue", "green", "black"))
    (dens_sep_stack <- stan_dens(fit, pars = "theta", alpha = 0.5,
                                 separate_chains = TRUE, position = "stack"))

    # traceplot
    trace <- stan_trace(fit)
    trace +
      scale_color_manual(values = c("red", "blue", "green", "black"))
    trace +
      scale_color_brewer(type = "div") +
      theme(legend.position = "none")

    facet_style <- theme(strip.background = ggplot2::element_rect(fill = "white"),
                         strip.text = ggplot2::element_text(size = 13, color = "black"))
    (trace <- trace + facet_style)

    # scatterplot
    (mu_vs_tau <- stan_scat(fit, pars = c("mu", "tau"), color = "blue", size = 4))
    mu_vs_tau +
      ggplot2::coord_flip() +
      theme(panel.background = ggplot2::element_rect(fill = "black"))

    ## End(Not run)

[Package rstan version 2.21.5 Index]