# ‘MCMCvis’ package

#### Casey Youngflesh

## Intro

`MCMCvis` is an R package used to visualize, manipulate, and summarize MCMC output. MCMC output may be derived from Bayesian model output fit with JAGS, Stan, or other MCMC samplers.

The package contains four functions:

- `MCMCsummary` - summarize MCMC output for particular parameters of interest
- `MCMCtrace` - create trace and density plots of MCMC chains for particular parameters of interest
- `MCMCchains` - easily extract posterior chains from MCMC output for particular parameters of interest
- `MCMCplot` - create caterpillar plots from MCMC output for particular parameters of interest

`MCMCvis` was designed to perform key functions for MCMC analysis using minimal code, in order to free up time/brainpower for interpretation of analysis results. Functions support simple and straightforward subsetting of model parameters within the calls, and produce presentable and ‘publication-ready’ output.

## MCMCsummary

`MCMCsummary` is used to output summary information from MCMC output. This function accepts `stanfit` objects, `mcmc.list` objects, `R2jags` model output, and matrices of MCMC output (one chain per column). The function automatically detects the object type and proceeds accordingly. Two decimal places are reported by default. This can be changed using the `digits` argument.

    library(MCMCvis)

    data(MCMC_data)

    MCMCsummary(MCMC_data)

    ##             mean   2.5%    50%  97.5% Rhat
    ## alpha[1]   -6.77 -20.66  -6.86   7.02    1
    ## alpha[2]  -13.06 -21.60 -13.03  -4.22    1
    ## alpha[3]  -12.51 -24.48 -12.57  -0.36    1
    ## alpha[4]  -12.86 -14.21 -12.87 -11.48    1
    ## alpha[5]   -9.87 -27.76  -9.83   7.78    1
    ## alpha[6]   -9.52 -15.36  -9.47  -3.83    1
    ## alpha[7]  -10.04 -15.54 -10.05  -4.42    1
    ## alpha[8]   -9.40 -10.70  -9.41  -8.07    1
    ## alpha[9]  -15.42 -30.33 -15.44  -0.27    1
    ## alpha[10]  -8.08 -23.37  -8.17   7.87    1
    ## beta[1]     0.16   0.06   0.15   0.25    1
    ## beta[2]    -7.77 -25.82  -7.68   9.78    1
    ## beta[3]    -5.64 -28.53  -5.76  17.23    1
    ## beta[4]   -10.39 -25.98 -10.63   5.27    1
    ## beta[5]     7.52   6.03   7.52   9.05    1
    ## beta[6]    10.89  10.10  10.89  11.68    1
    ## beta[7]    -1.91  -4.83  -1.92   1.08    1
    ## beta[8]     5.38  -6.86   5.45  17.67    1
    ## beta[9]    13.39   3.28  13.38  23.60    1
    ## beta[10]   17.63  14.41  17.63  20.86    1
    ## gamma[1]   -4.66 -14.15  -4.60   4.83    1
    ## gamma[2]   -7.83 -19.52  -7.78   4.05    1
    ## gamma[3]    1.80 -12.98   1.66  16.78    1
    ## gamma[4]   -2.88 -18.42  -2.86  13.13    1
    ## gamma[5]    0.75  -7.07   0.78   8.45    1
    ## gamma[6]   12.08   6.97  12.08  17.06    1
    ## gamma[7]    0.82  -8.78   0.81  10.28    1
    ## gamma[8]    5.00   1.66   5.01   8.23    1
    ## gamma[9]    3.31  -2.91   3.34   9.45    1
    ## gamma[10]   5.37  -9.16   5.42  20.57    1

Specific parameters can be specified to subset summary information. Partial names may be used to specify any parameter containing that name. For instance, for all `alpha` parameters.

    MCMCsummary(MCMC_data,
              params = 'alpha')

    ##             mean   2.5%    50%  97.5% Rhat
    ## alpha[1]   -6.77 -20.66  -6.86   7.02    1
    ## alpha[2]  -13.06 -21.60 -13.03  -4.22    1
    ## alpha[3]  -12.51 -24.48 -12.57  -0.36    1
    ## alpha[4]  -12.86 -14.21 -12.87 -11.48    1
    ## alpha[5]   -9.87 -27.76  -9.83   7.78    1
    ## alpha[6]   -9.52 -15.36  -9.47  -3.83    1
    ## alpha[7]  -10.04 -15.54 -10.05  -4.42    1
    ## alpha[8]   -9.40 -10.70  -9.41  -8.07    1
    ## alpha[9]  -15.42 -30.33 -15.44  -0.27    1
    ## alpha[10]  -8.08 -23.37  -8.17   7.87    1

Individual parameters can also be specified.

    MCMCsummary(MCMC_data,
              params = 'alpha[1]')

    ##   mean   2.5%    50%  97.5%   Rhat
    ##  -6.77 -20.66  -6.86   7.02   1.00

The `excl` argument can be used to exclude any parameters. This can be used in conjunction with the `params` argument. For instance, if all `alpha` parameters are desired except for `alpha[1]`, `params = 'alpha', excl = 'alpha[1]'` can be used. These arguments can be used in any of the functions in the package.

    MCMCsummary(MCMC_data,
              params = 'alpha',
              excl = 'alpha[1]')

    ##             mean   2.5%    50%  97.5% Rhat
    ## alpha[2]  -13.06 -21.60 -13.03  -4.22    1
    ## alpha[3]  -12.51 -24.48 -12.57  -0.36    1
    ## alpha[4]  -12.86 -14.21 -12.87 -11.48    1
    ## alpha[5]   -9.87 -27.76  -9.83   7.78    1
    ## alpha[6]   -9.52 -15.36  -9.47  -3.83    1
    ## alpha[7]  -10.04 -15.54 -10.05  -4.42    1
    ## alpha[8]   -9.40 -10.70  -9.41  -8.07    1
    ## alpha[9]  -15.42 -30.33 -15.44  -0.27    1
    ## alpha[10]  -8.08 -23.37  -8.17   7.87    1

## MCMCtrace

`MCMCtrace` is used to create trace and density plots for MCMC output. This is useful for diagnostic purposes. Particular parameters can also be specified, as with `MCMCsummary`.

    MCMCtrace(MCMC_data,
            params = c('beta[1]', 'beta[2]', 'beta[3]'))

Just trace plot can be plotted with `type = 'trace'`. Just density plots can be plotted with `type = 'density'`. Default is `type = 'both'` which outputs both trace and density plots. Individual chains for the density plot can be output using the `ind` argument.

    MCMCtrace(MCMC_data,
            params = c('beta[1]', 'beta[2]', 'beta[3]',
                    'beta[4]', 'beta[5]', 'beta[6]'),
            type = 'density',
            ind = TRUE)

`iter_st` denotes at which iteration in the chain the trace and density plots should start with. The default is 1, meaning that the entire chain is plotted. `iter_st = 1800` means that both the trace plots and density plots will begin at iteration 1800 of the posterior chains. Remember, this is the final posterior chain, not including the specified burn-in (specified when the model was run).

    MCMCtrace(MCMC_data,
            params = c('beta[1]', 'beta[2]', 'beta[3]'),
            iter_st = 1800,
            ind = TRUE)

Trace plots can also be output to PDF format. This is recommended for large numbers of parameters, as output to PDF makes for quicker browsing compared to browsing within the R GUI. PDF document will be output to the current working directory by default, but another directory can be specified.

    MCMCtrace(MCMC_data,
            pdf = TRUE,
            filename = 'MYpdf',
            wd = 'DIRECTORY HERE')

## MCMCchains

`MCMCchains` is used to extract MCMC chains from MCMC objects. Chains can then be manipulated directly. Particular parameters can be specified as with other functions.

    ex <- MCMCchains(MCMC_data,
                   params = 'beta')

    #extract mean values for each parameter
    apply(ex, 2, mean)

    ##     beta[1]     beta[2]     beta[3]     beta[4]     beta[5]     beta[6]
    ##   0.1552233  -7.7730129  -5.6395230 -10.3909353   7.5234015  10.8927480
    ##     beta[7]     beta[8]     beta[9]    beta[10]
    ##  -1.9125980   5.3810511  13.3874634  17.6273181

## MCMCplot

`MCMCplot` is used to create caterpillar plots from MCMC output. Points represent posterior medians. For parameters where 50% credible intervals overlap 0 are indicated by ‘open’ circles. For parameters where 50 percent credible intervals DO NOT overlap 0 AND 95 percent credible intervals DO overlap 0 are indicated by ‘closed’ grey circles. For parameters where 95 percent credible intervals DO NOT overlap 0 are indicated by ‘closed’ black circles. Thick lines represent 50 percent credible intervals while thin lines represent 95 percent credible intervals.

As with the other functions in the package, particular parameters of interest can be specified.

    MCMCplot(MCMC_data,
           params = 'beta')

`ref_ovl = FALSE` can be used to disable this feature. All median dots will be represented as ‘closed’ black circles. A vertical reference at 0 is plotted by default. The position of this reference line can be modified with the `ref` argument. `ref = NULL` removes the reference line altogether.

    MCMCplot(MCMC_data,
           params = 'beta',
           ref_ovl = FALSE,
           ref = NULL)

Parameters can be ranked by posterior median estimates using the `rank` argument.

    MCMCplot(MCMC_data,
           params = 'beta',
           rank = TRUE)

Graphical parameters for x and y-axis limitation, axis labels, row labels, title, median dot size, CI line thickness, axis and tick thickness, text size, and margins can be specified.

    MCMCplot(MCMC_data,
           params = 'beta',
           xlim = c(-60, 25),
           xlab = 'My x-axis label',
           main = 'MCMCvis plot',
           labels = c('First param', 'Second param', 'Third param',
                      'Fourth param', 'Fifth param', 'Sixth param',
                      'Seventh param', 'Eighth param', 'Nineth param',
                      'Tenth param'),
           labels_sz = 1.5,
           med_sz = 2,
           thick_sz = 7,
           thin_sz = 3,
           ax_sz = 4,
           main_text_sz = 2)

For more information see `?MCMCplot`