**[BAYES] bayesgraph** -- Graphical summaries and convergence diagnostics

__Syntax__

Graphical summaries and convergence diagnostics for single parameter

**bayesgraph** *graph* *scalar_param* [**,** *singleopts*]

Graphical summaries and convergence diagnostics for multiple parameters

**bayesgraph** *graph* *spec* [*spec* ...] [**,** *multiopts*]

**bayesgraph matrix** *spec* *spec* [*spec* ...] [**,** *singleopts*]

Graphical summaries and convergence diagnostics for all parameters

**bayesgraph** *graph* **_all** [**,** *multiopts* **showreffects**[**(***reref***)**]]

*graph* Description
-------------------------------------------------------------------------
__diag__**nostics** multiple diagnostics in compact form
**trace** trace plots
**ac** autocorrelation plots
__hist__**ogram** histograms
__kdens__**ity** density plots
**cusum** cumulative sum plots
**matrix** scatterplot matrix
-------------------------------------------------------------------------
**bayesgraph matrix** requires at least two parameters.

*scalar_param* is a scalar model parameter specified as **{param}** or
**{eqname:param}** or an expression *exprspec* of scalar model
parameters. Matrix model parameters are not allowed, but you may
refer to their individual elements.

*exprspec* is an optionally labeled expression of model parameters
specified in parentheses:

**(**[*exprlabel***:**]*expr***)**

*exprlabel* is a valid Stata name, and *expr* is a scalar expression
which may not contain matrix model parameters. See *Specifying*
*functions of model parameters* in **[BAYES] bayesian postestimation**
for examples.

*spec* is either *scalar_param* or *exprspec*.

*singleopts* Description
-------------------------------------------------------------------------
Options
**skip(***#***)** skip every *#* observations from the MCMC
sample; default is **skip(0)**
**name(***name***,** ...**)** specify name of graph
**saving(***filename***,** ...**)** save graph in file
*graphopts* graph-specific options
-------------------------------------------------------------------------

*multiopts* Description
-------------------------------------------------------------------------
Options
**byparm**[**(***grbyparmopts***)**] specify the display of plots on one
graph; default is a separate graph for
each plot; not allowed with graphs
**diagnostics** or **matrix** or with option
**combine()**
**combine**[**(***grcombineopts***)**] specify the display of plots on one
graph; recommended when the number of
parameters is large; not allowed with
graphs **diagnostics** or **matrix** or with
option **byparm()**
**sleep(***#***)** pause for *#* seconds between multiple
graphs; default is **sleep(0)**
**wait** pause until the --**more**-- condition is
cleared
[**no**]**close** (do not) close Graph windows when the
next graph is displayed with multiple
graphs; default is **noclose**
**skip(***#***)** skip every *#* observations from the MCMC
sample; default is **skip(0)**
**name(***namespec***,** ...**)** specify names of graphs
**saving(***filespec***,** ...**)** save graphs in file
**graphopts(***graphopts***)** control the look of all graphs; not
allowed with **byparm()**
**graph**[*#*]**opts(***graphopts***)** control the look of *#*th graph; not
allowed with **byparm()**
*graphopts* equivalent to **graphopts(***graphopts***)**; only
one may be specified
-------------------------------------------------------------------------

*graphopts* Description
-------------------------------------------------------------------------
*diagnosticsopts* options for **bayesgraph diagnostics**
*tslineopts* options for **bayesgraph trace** and **bayesgraph cusum**
*acopts* options for **bayesgraph ac**
*histopts* options for **bayesgraph histogram**
*kdensityopts* options for **bayesgraph kdensity**
*grmatrixopts* options for **bayesgraph matrix**
-------------------------------------------------------------------------

*diagnosticsopts* Description
-------------------------------------------------------------------------
**traceopts(***tslineopts***)** affect rendition of all trace plots
**trace**[*#*]**opts(***tslineopts***)** affect rendition of *#*th trace plot
**acopts(***acopts***)** affect rendition of all autocorrelation
plots
**ac**[*#*]**opts(***acopts***)** affect rendition of *#*th autocorrelation
plot
**histopts(***histopts***)** affect rendition of all histogram plots
**hist**[*#*]**opts(***histopts***)** affect rendition of *#*th histogram plot
**kdensopts(***kdensityopts***)** affect rendition of all density plots
**kdens**[*#*]**opts(***kdensityopts***)** affect rendition of *#*th density plot
*grcombineopts* any option documented in **[G-2] graph**
**combine**
-------------------------------------------------------------------------

*acopts* Description
-------------------------------------------------------------------------
**ci** plot autocorrelations with confidence intervals; not
allowed with **byparm()**
*acopts* any options other than **generate()** documented for the **ac**
command in **[TS] corrgram**
-------------------------------------------------------------------------

*kdensityopts* Description
-------------------------------------------------------------------------
*kdensopts* options for the overall kernel density plot
**show(***showspec***)** show first-half density, second-half density,
or both; default is **both**
**kdensfirst(***kdens1opts***)** affect rendition of the first-half density
plot
**kdenssecond(***kdens2opts***)** affect rendition of the second-half density
plot
-------------------------------------------------------------------------

__Menu__

**Statistics > Bayesian analysis > Graphical summaries**

__Description__

**bayesgraph** provides graphical summaries and convergence diagnostics for
simulated posterior distributions (MCMC samples) of model parameters and
functions of model parameters obtained after Bayesian estimation.
Graphical summaries include trace plots, autocorrelation plots, and
various distributional plots.

__Options__

+---------+
----+ Options +----------------------------------------------------------

**byparm**[**(***grbyparmopts***)**] specifies the display of all plots of parameters
as subgraphs on one graph. By default, a separate graph is produced
for each plot when multiple parameters are specified. This option is
not allowed with **bayesgraph diagnostics** or **bayesgraph** **matrix** and may
not be combined with option **combine()**. When many parameters or
expressions are specified, this option may fail because of memory
constraints. In that case, you may use option **combine()** instead.

*grbyparmopts* is any of the suboptions of **by()** documented in **[G-3]**
*by_option*.

**byparm()** allows y scales to differ for all graph types and forces x
scales to be the same only for **bayesgraph trace** and **bayesgraph** **cusum**.
Use **noyrescale** within **byparm()** to specify a common y axis, and use
**xrescale** or **noxrescale** to change the default behavior for the x axis.

**byparm()** with **bayesgraph trace** and **bayesgraph cusum** defaults to
displaying multiple plots in one column to accommodate the x axis
with many iterations. Use **norowcoldefault** within **byparm()** to switch
back to the default behavior of options **rows()** and **cols()** of the
**[G-3] ***by_option*.

**combine**[**(***grcombineopts***)**] specifies the display of all plots of parameters
as subgraphs on one graph and is an alternative to **byparm()** with a
large number of parameters. By default, a separate graph is produced
for each plot when multiple parameters are specified. This option is
not allowed with **bayesgraph diagnostics** or **bayesgraph** **matrix** and may
not be combined with option **byparm()**. It can be used in cases where
a large number of parameters or expressions are specified and the
**byparm()** option would cause an error because of memory constraints.

*grcombineopts* is any of the options documented in **[G-2] graph**
**combine**.

**sleep(***#***)** specifies pausing for *#* seconds before producing the next graph.
This option is allowed only when multiple parameters are specified.
This option may not be combined with **wait**, **combine()**, or **byparm()**.

**wait** causes **bayesgraph** to display --**more**-- and pause until any key is
pressed before producing the next graph. This option is allowed when
multiple parameters are specified. This option may not be combined
with **sleep()**, **combine()**, or **byparm()**. **wait** temporarily ignores the
global setting that is specified using **set more off**.

[**no**]**close** specifies that, for multiple graphs, the Graph window be closed
when the next graph is displayed. The default is **noclose** or to not
close any Graph windows.

**skip(***#***)** specifies that every *#* observations from the MCMC sample not be
used for computation. The default is **skip(0)** or to use all
observations in the MCMC sample. Option **skip()** can be used to
subsample or thin the chain. **skip(***#***)** is equivalent to a thinning
interval of *#*+1. For example, if you specify **skip(1)**, corresponding
to the thinning interval of 2, the command will skip every other
observation in the sample and will use only observations 1, 3, 5, and
so on in the computation. If you specify **skip(2)**, corresponding to
the thinning interval of 3, the command will skip every 2
observations in the sample and will use only observations 1, 4, 7,
and so on in the computation. **skip()** does not thin the chain in the
sense of physically removing observations from the sample, as is done
by, for example, **bayesmh**'s **thinning()** option. It only discards
selected observations from the computation and leaves the original
sample unmodified.

**name(***namespec*[**, replace**]**)** specifies the name of the graph or multiple
graphs. See **[G-3] ***name_option* for a single graph. If multiple
graphs are produced, then the argument of **name()** is either a list of
names or a *stub*, in which case graphs are named *stub***1**, *stub***2**, and so
on. With multiple graphs, if **name()** is not specified and neither
**sleep()** nor **wait** is specified, **name(Graph__***#***, replace)** is assumed,
and thus the produced graphs may be replaced by subsequent **bayesgraph**
commands.

The **replace** suboption causes existing graphs with the specified name
or names to be replaced.

**saving(***filespec*[**, replace)** specifies the filename or filenames to use to
save the graph or multiple graphs to disk. See **[G-3]** *saving_option*
for a single graph. If multiple graphs are produced, then the
argument of **saving()** is either a list of filenames or a *stub*, in
which case graphs are saved with filenames *stub***1**, *stub***2**, and so on.

The **replace** suboption specifies that the file (or files) may be
replaced if it already exists.

**showreffects** and **showreffects(***reref***)** are for use after multilevel models,
and they specify that the results for all or a list *reref* of
random-effects parameters be provided in addition to other model
parameters. By default, all random-effects parameters are excluded
from the results to conserve computation time.

**graphopts(***graphopts***)** and **graph**[*#*]**opts(***graphopts***)** affect the rendition of
graphs. **graphopts()** affects the rendition of all graphs but may be
overridden for specific graphs by using the **graph***#***opts()** option. The
options specified within **graph***#***opts()** are specific for each type of
graph.

The two specifications

**bayesgraph** ...**, graphopts(***graphopts***)**

and

**bayesgraph** ...**,** *graphopts*

are equivalent, but you may specify one or the other.

These options are not allowed with **byparm()** and when only one
parameter is specified.

*graphopts* specifies options specific to each graph type.

*diagnosticsopts* specifies options for use with **bayesgraph**
**diagnostics**. See the corresponding table in the syntax diagram
for a list of options.

*tslineopts* specifies options for use with **bayesgraph trace** and
**bayesgraph cusum**. See the options of **[TS] tsline** except **by()**.

*acopts* specifies options for use with **bayesgraph ac**.

**ci** requests that the graph of autocorrelations with confidence
intervals be plotted. By default, confidence intervals are
not plotted. This option is not allowed with **byparm()**.

*acoptsts* specifies any options except **generate()** of the **ac**
command in **[TS] corrgram**.

*histopts* specifies options for use with **bayesgraph histogram**. See
options of **[R] histogram** except **by()**.

*kdensityopts* specifies options for use with **bayesgraph kdensity**.

*kdensopts* specifies options for the overall kernel density plot.
See the options documented in **[R] kdensity** except **generate()**
and **at()**.

**show(***showspec***)** specifies which kernel density curves to plot.
*showspec* is one of **both**, **first**, **second**, or **none**. **show(both)**,
the default, overlays both the first-half density curve and
the second-half density curve with the overall kernel density
curve. If **show(first)** is specified, only the first-half
density curve, obtained from the first half of an MCMC
sample, is plotted. If **show(second)** is specified, only the
second-half density curve, obtained from the second half of
an MCMC sample, is plotted. If **show(none)** is specified, only
the overall kernel density curve is shown.

**kdensfirst(***kdens1opts***)** specifies options of **[G-2] graph twoway**
**kdensity** except **by()** to affect rendition of the first-half
kernel density plot.

**kdenssecond(***kdens2opts***)** specifies options of **[G-2] graph twoway**
**kdensity** except **by()** to affect rendition of the second-half
kernel density plot.

*grmatrixopts* specifies options for use with **bayesgraph matrix**. See
the options of **[G-2] graph matrix** except **by()**.

__Remarks__

**bayesgraph** requires specifying at least one parameter with all graph
types, except **matrix** which requires at least two parameters. To request
graphs for all parameters, use **_all**.

By default when multiple graphs are produced, they are automatically
stored in memory with names **Graph__***#* and will all appear on the screen.
After you are done reviewing the graphs, you can type **. graph drop**
**Graph__*** to close the graphs and drop them from memory.

If you would like to see only one graph at a time, you can specify either
the **sleep()** or **wait** options to include a pause between the subsequent
graphs. **close** can be specified to automatically close a graph after the
pause.

You can also combine separate graphs into one by specifying the **byparm()**
or **combine()** options. These options are not allowed with **diagnostics** and
**matrix** graphs.

With multiple graphs, you can control the look of each individual graph
with **graph***#***opts()**. Options common to all graphs may be specified in
**graphopts()** or passed directly to the command as with single graphs.

__Examples__

Setup
**. webuse oxygen**
**. set seed 14**
**. bayesmh change age group, likelihood(normal({var}))**
**prior({change:}, flat) prior({var}, jeffreys)**

Diagnostic graphs for all parameters in the model
**. bayesgraph diagnostics _all**

Autocorrelation plots for parameters **{change:age}** and **{change:_cons}**
**. bayesgraph ac {change:age} {change:_cons}**

Trace plots for parameters **{var}** and **{change:age}** in a single graph
**. bayesgraph trace {var} {change:age}, byparm**

Histogram of the marginal posterior distribution for parameter
**{change:age}** with normal distribution overlayed
**. bayesgraph histogram {change:age}, normal**

Kernel density plot for parameter **{var}**
**. bayesgraph kdensity {var}**

Cumulative sum plot for parameter **{change:age}**
**. bayesgraph cusum {change:age}**

Bivariate scatterplot of parameters **{change:age}** and **{change:_cons}**
**. bayesgraph matrix {change:age} {change:_cons}**