R: Parallel coordinates plot of MCMC draws

MCMC-parcoord {bayesplot}

R Documentation

Parallel coordinates plot of MCMC draws

Description

Parallel coordinates plot of MCMC draws (one dimension per parameter). See the Plot Descriptions section, below, for details.

Usage

mcmc_parcoord(x, pars = character(), regex_pars = character(),
  transformations = list(), ..., size = 0.2, alpha = 0.3, np = NULL,
  np_style = parcoord_style_np())

mcmc_parcoord_data(x, pars = character(), regex_pars = character(),
  transformations = list(), np = NULL)

parcoord_style_np(div_color = "red", div_size = 0.2, div_alpha = 0.2)

Arguments

`x`	A 3-D array, matrix, list of matrices, or data frame of MCMC draws. The MCMC-overview page provides details on how to specify each these allowed inputs.
`pars`	An optional character vector of parameter names. If neither `pars` nor `regex_pars` is specified then the default is to use all parameters.
`regex_pars`	An optional regular expression to use for parameter selection. Can be specified instead of `pars` or in addition to `pars`.
`transformations`	Optionally, transformations to apply to parameters before plotting. If `transformations` is a function or a single string naming a function then that function will be used to transform all parameters. To apply transformations to particular parameters, the `transformations` argument can be a named list with length equal to the number of parameters to be transformed. Currently only univariate transformations of scalar parameters can be specified (multivariate transformations will be implemented in a future release). If `transformations` is a list, the name of each list element should be a parameter name and the content of each list element should be a function (or any item to match as a function via `match.fun`, e.g. a string naming a function). If a function is specified by its name as a string (e.g. `"log"`), then it can be used to construct a new parameter label for the appropriate parameter (e.g. `"log(sigma)"`). If a function itself is specified (e.g. `log` or `function(x) log(x)`) then `"t"` is used in the new parameter label to indicate that the parameter is transformed (e.g. `"t(sigma)"`).
`...`	Currently ignored.
`size, alpha`	Arguments passed on to `geom_line`.
`np`	For models fit using `NUTS` (more generally, any symplectic integrator), an optional data frame providing NUTS diagnostic information. The data frame should be the object returned by `nuts_params` or one with the same structure.
`np_style`	A call to the `parcoord_style_np` helper function to specify arguments controlling the appearance of superimposed lines representing NUTS diagnostics (in this case divergences) if the `np` argument is specified.
`div_color, div_size, div_alpha`	Optional arguments to the `parcoord_style_np` helper function that are eventually passed to `geom_line` if the `np` argument is also specified. They control the color, size, and transparency specifications for showing divergences in the plot. The default values are displayed in the Usage section above.

Value

A ggplot object that can be further customized using the ggplot2 package. The _data functions return the data that would have be drawn by the plotting function.

Plot Descriptions

mcmc_parcoord

(Parallel coordinates plot) of MCMC draws. There is one dimension per parameter along the horizontal axis and each set of connected line segments represents a single MCMC draw (i.e., a vector of length equal to the number of parameters).

The parallel coordinates plot is most useful if the optional HMC/NUTS diagnostic information is provided via the np argument. In that case divergences are highlighted in the plot. The appearance of the divergences can be customized using the np_style argument and the parcoord_style_np helper function.

When the plotted model parameters are on very different scales the transformations argument can be useful. For example, to standardize all variables before plotting you could use function (x - mean(x))/sd(x) when specifying the transformations argument to mcmc_parcoord. See the Examples section for how to do this.

References

Gabry, J., Simpson, D., Vehtari, A., Betancourt, M., Gelman, A. (2017). Visualization in Bayesian workflow. arXiv preprint arvix:1709.01449.

Examples

color_scheme_set("pink")
x <- example_mcmc_draws(params = 5)
mcmc_parcoord(x)
mcmc_parcoord(x, regex_pars = "beta")

## Not run: 
# Example using a Stan demo model
library(rstan)
fit <- stan_demo("eight_schools")
draws <- as.array(fit, pars = c("mu", "tau", "theta", "lp__"))
np <- nuts_params(fit)
str(np)
levels(np$Parameter)

color_scheme_set("brightblue")
mcmc_parcoord(draws, alpha = 0.05)
mcmc_parcoord(draws, np = np)

# customize appearance of divergences
color_scheme_set("darkgray")
div_style <- parcoord_style_np(div_color = "green", div_size = 0.05, div_alpha = 0.4)
mcmc_parcoord(draws, size = 0.25, alpha = 0.1,
              np = np, np_style = div_style)

# to use a transformation (e.g., to standarde all the variables)
# specify the 'transformations' argument (though partial argument name
# matching means we can just use 'trans' or 'transform')
mcmc_parcoord(
  draws,
  transform = function(x) {(x - mean(x)) / sd(x)},
  size = 0.25,
  alpha = 0.1,
  np = np,
  np_style = div_style
 )

# mcmc_parcoord_data returns just the data in a conventient form for plotting
d <- mcmc_parcoord_data(x, np = np)
head(d)
tail(d)

## End(Not run)

[Package bayesplot version 1.4.0 Index]