rethinking (version 2.13)

trankplot: 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.

References

Vehtari, Gelman, Simpson, Carpenter, B<U+00FC>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)

# }