ergm (version 2.4-2)

mcmc.diagnostics.ergm: Conduct MCMC diagnostics on an ergm fit

Description

This function creates simple diagnostic plots for the MCMC sampled statistics produced from a fit. It also prints the Raftery-Lewis diagnostics, indicates if they are sufficient, and suggests the run length required.

Usage

## S3 method for class 'ergm':
mcmc.diagnostics(object, sample = "sample", smooth = TRUE, 
                 r = 0.0125, digits = 6, maxplot = 1000, verbose = TRUE, 
                 center = TRUE, main = "Summary of MCMC samples", xlab =
                 "Iterations", ylab = "", curved=TRUE, \dots)

Arguments

object

An object. See documentation for ergm.

sample

The component of object on which the diagnosis is based. The two usuals ones are thetasample from the auxilary sample of the natural parameter and sample the (default) sample of the sufficient statistics

smooth

Draw a smooth line through trace plots

r

Percentile of the distribution to estimate

digits

Number of digits to print

maxplot

Maximum number of statistics to plot

verbose

If this is TRUE, print out more information about the MCMC runs including lag correlations.

center

logical; should the samples be centered on the observed statistics.

main

Figure title for the diagnostic plots.

xlab

X-axis label for diagnostic plots

ylab

Y-axis label for diagnostic plots

curved

If this is TRUE, summarize the curved statistics (evaluated at the MLE of any non-linear parameters), rather than the raw components of the curved statistics.

...

Additional arguments, to be passed to lower-level functions in the future.

Value

• mcmc.diagnostics.ergm returns a matrix of Raftery-Lewis diagnostics.

Details

The plots produced are a trace of the sampled output and a density estimate for each variable in the chain.

The Raftery-Lewis diagnostic is a run length control diagnostic based on a criterion of accuracy of estimation of the quantile q. It is intended for use on a short pilot run of a Markov chain. The number of iterations required to estimate the quantile q to within an accuracy of +/- r with probability p is calculated. Separate calculations are performed for each variable within each chain.

In fact, an object contains the matrix of statistics from the MCMC run as component $sample. This matrix is actually an object of class mcmc and can be used directly in the coda package to assess MCMC convergence. Hence all MCMC diagnostic methods available in coda are available directly. See the examples and http://www.mrc-bsu.cam.ac.uk/bugs/classic/coda04/readme.shtml.

More information can be found by looking at the documentation of ergm.

References

Warnes, G.W. (2000). Multi-Chain and Parallel Algorithms for Markov Chain Monte Carlo. Dissertation, Department of Biostatistics, University of Washington,

Raftery, A.E. and Lewis, S.M. (1992). One long run with diagnostics: Implementation strategies for Markov chain Monte Carlo. Statistical Science, 7, 493-497.

Raftery, A.E. and Lewis, S.M. (1995). The number of iterations, convergence diagnostics and generic Metropolis algorithms. In Practical Markov Chain Monte Carlo (W.R. Gilks, D.J. Spiegelhalter and S. Richardson, eds.). London, U.K.: Chapman and Hall.

This package is based on the coda package and also ideas from mcgibbsit by Gregory R. Warnes [e-mail]. It is based on the the R function raftery.diag in coda. raftery.diag, in turn, is based on the FORTRAN program gibbsit written by Steven Lewis which is available from the Statlib archive.

See Also

ergm, network package, coda package, mcgibbsit package, summary.ergm

Examples

#
data(florentine)
#
# test the mcmc.diagnostics function
#
gest <- ergm(flomarriage ~ edges + kstar(2))
summary(gest)

#
# Plot the probabilities first
#
mcmc.diagnostics(gest)
#
# Use coda directly
#
library(coda)
#
plot(gest$sample, ask=FALSE)
ergm.raftery.diag(gest$sample, r=0.1)
#
# A full range of diagnostics is available 
# using codamenu()
#