trankplot: Diagnostic trace and rank histogram plots for MCMC output

In rmcelreath/rethinking: Statistical Rethinking book package

Diagnostic trace and rank histogram plots for MCMC output

Description

The functions trankplot and traceplot display MCMC chain diagnostic plots. trankplot displays ranked histograms and traceplot shows the more traditional trace of the samples.

Usage

trankplot( object , bins=30 , pars , chains , col=rethink_palette , alpha=1 , 
  bg=col.alpha("black",0.15) , ask=TRUE , window , n_cols=3 , max_rows=5 , 
  lwd=1.5 , lp=FALSE  , axes=FALSE , ... )
traceplot( object , pars , chains , col=rethink_palette , alpha=1 , 
  bg=col.alpha("black",0.15) , ask=TRUE , window , trim=100 , n_cols=3 , 
  max_rows=5 , lwd=0.5 , lp=FALSE , ... )

Arguments

object	A stanfit, ulam or map2stan object
bins	For trankplot, the number of histogram bins to use
pars	Optional character vector of parameters to display
chains	Optional integer vector of chains to display
col	Vector of colors to use for chains
alpha	Transparency
bg	Background color for warmup samples
ask	Interactive paging when TRUE
window	Optional range of samples to show
n_cols	Number of columns in display
max_rows	Maximum number of rows on each page
lwd	Line width
lp	Whether to include log_prob in display
axes	Whether to show axes on plots
trim	For traceplot, number of samples to trim for start. Helps with display, since early warmup samples typically very far from typical samples.
...	Additional arguments to pass to plot

Details

trankplot produces rank histograms of each chain, as described in Vehtari et al 2019 (see reference below). For each parameter, the samples from all chains are first ranked, using rank_mat. This returns a matrix of ranks, with the chains preserved. Then a histogram is built for each chain, using the same break points. These historgrams are then overlain in the plot.

For healthy well-mixing chains, the histrograms should be uniform. When there are spikes for some chains, especially in the low or high ranks, this suggests problems in exploring the posterior.

traceplot shows the sequential samples for each parameter and chain. This is the same information as the trankplot, but often much harder to see, given the volume of samples.

Author(s)

Richard McElreath

References

Vehtari, Gelman, Simpson, Carpenter, Bürkner. 2019. Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of MCMC. https://arxiv.org/abs/1903.08008

Examples

## Not run: 
library(rethinking)
data(chimpanzees)

d <- list( 
    pulled_left = chimpanzees$pulled_left ,
    prosoc_left = chimpanzees$prosoc_left ,
    condition = as.integer( 2 - chimpanzees$condition ) ,
    actor = as.integer( chimpanzees$actor ) ,
    blockid = as.integer( chimpanzees$block )
)

m <- ulam(
    alist(
        # likeliood
        pulled_left ~ bernoulli(theta),

        # linear models
        logit(theta) <- A + BP*prosoc_left,
        A <- a + v[actor,1],
        BP <- bp + v[actor,condition+1],

        # adaptive prior
        vector[3]: v[actor] ~ multi_normal( 0 , Rho_actor , sigma_actor ),

        # fixed priors
        c(a,bp) ~ normal(0,1),
        sigma_actor ~ exponential(1),
        Rho_actor ~ lkjcorr(4)
    ) , data=d , chains=3 , cores=1 , sample=TRUE )

trankplot(m)


## End(Not run)

rmcelreath/rethinking documentation built on Sept. 18, 2023, 2:01 p.m.