Plots

pymc3.plots.traceplot(trace, varnames=None, transform=<function identity_transform>, figsize=None, lines=None, combined=False, plot_transformed=False, grid=False, alpha=0.35, priors=None, prior_alpha=1, prior_style='--', bw=4.5, ax=None, live_plot=False, skip_first=0, refresh_every=100, roll_over=1000)

Plot samples histograms and values.

Parameters:

trace : result of MCMC run

varnames : list of variable names

Variables to be plotted, if None all variable are plotted

transform : callable

Function to transform data (defaults to identity)

figsize : figure size tuple

If None, size is (12, num of variables * 2) inch

lines : dict

Dictionary of variable name / value to be overplotted as vertical lines to the posteriors and horizontal lines on sample values e.g. mean of posteriors, true values of a simulation. If an array of values, line colors are matched to posterior colors. Otherwise, a default red line

combined : bool

Flag for combining multiple chains into a single chain. If False (default), chains will be plotted separately.

plot_transformed : bool

Flag for plotting automatically transformed variables in addition to original variables (defaults to False).

grid : bool

Flag for adding gridlines to histogram. Defaults to True.

alpha : float

Alpha value for plot line. Defaults to 0.35.

priors : iterable of PyMC distributions

PyMC prior distribution(s) to be plotted alongside posterior. Defaults to None (no prior plots).

prior_alpha : float

Alpha value for prior plot. Defaults to 1.

prior_style : str

Line style for prior plot. Defaults to ‘–’ (dashed line).

bw : float

Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott’s rule of thumb (the default rule used by SciPy).

ax : axes

Matplotlib axes. Accepts an array of axes, e.g.:

live_plot: bool

Flag for updating the current figure while sampling

skip_first : int

Number of first samples not shown in plots (burn-in). This affects frequency and stream plots.

refresh_every : int

Period of plot updates (in sample number)

roll_over : int

Width of the sliding window for the sample stream plots: last roll_over samples are shown (no effect on frequency plots).

>>> fig, axs = plt.subplots(3, 2) # 3 RVs
>>> pymc3.traceplot(trace, ax=axs)

Creates own axes by default.

Returns:

ax : matplotlib axes

pymc3.plots.plot_posterior(trace, varnames=None, transform=<function identity_transform>, figsize=None, text_size=None, alpha_level=0.05, round_to=3, point_estimate='mean', rope=None, ref_val=None, kde_plot=False, plot_transformed=False, bw=4.5, ax=None, **kwargs)

Plot Posterior densities in style of John K. Kruschke book.

Parameters:

trace : result of MCMC run

varnames : list of variable names

Variables to be plotted, if None all variable are plotted

transform : callable

Function to transform data (defaults to identity)

figsize : figure size tuple

If None, size is (12, num of variables * 2) inch

text_size : int

Text size of the point_estimates, axis ticks, and HPD (Default:16)

alpha_level : float

Defines range for High Posterior Density

round_to : int

Controls formatting for floating point numbers

point_estimate: str

Must be in (‘mode’, ‘mean’, ‘median’)

rope: list or numpy array

Lower and upper values of the Region Of Practical Equivalence

ref_val: float or list-like

display the percentage below and above the values in ref_val. If a list is provided, its length should match the number of variables.

kde_plot: bool

if True plot a KDE instead of a histogram. For discrete variables this argument is ignored.

plot_transformed : bool

Flag for plotting automatically transformed variables in addition to original variables (defaults to False).

bw : float

Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott’s rule of thumb (the default rule used by SciPy). Only works if kde_plot is True.

ax : axes

Matplotlib axes. Defaults to None.

**kwargs

Passed as-is to plt.hist() or plt.plot() function, depending on the value of the argument kde_plot Some defaults are added, if not specified color=’#87ceeb’ will match the style in the book

Returns:

ax : matplotlib axes

pymc3.plots.forestplot(trace, models=None, varnames=None, transform=<function identity_transform>, alpha=0.05, quartiles=True, rhat=True, main=None, xtitle=None, xlim=None, ylabels=None, colors='C0', chain_spacing=0.1, vline=0, gs=None, plot_transformed=False, plot_kwargs=None)

Forest plot (model summary plot).

Generates a “forest plot” of 100*(1-alpha)% credible intervals from a trace or list of traces.

Parameters:

trace : trace or list of traces

Trace(s) from an MCMC sample.

models : list (optional)

List with names for the models in the list of traces. Useful when plotting more that one trace.

varnames: list

List of variables to plot (defaults to None, which results in all variables plotted).

transform : callable

Function to transform data (defaults to identity)

alpha : float, optional

Alpha value for (1-alpha)*100% credible intervals (defaults to 0.05).

quartiles : bool, optional

Flag for plotting the interquartile range, in addition to the (1-alpha)*100% intervals (defaults to True).

rhat : bool, optional

Flag for plotting Gelman-Rubin statistics. Requires 2 or more chains (defaults to True).

main : string, optional

Title for main plot. Passing False results in titles being suppressed; passing None (default) results in default titles.

xtitle : string, optional

Label for x-axis. Defaults to no label

xlim : list or tuple, optional

Range for x-axis. Defaults to matplotlib’s best guess.

ylabels : list or array, optional

User-defined labels for each variable. If not provided, the node __name__ attributes are used.

colors : list or string, optional

list with valid matplotlib colors, one color per model. Alternative a string can be passed. If the string is `cycle `, it will automatically chose a color per model from the matyplolib’s cycle. If a single color is passed, eg ‘k’, ‘C2’, ‘red’ this color will be used for all models. Defauls to ‘C0’ (blueish in most matplotlib styles)

chain_spacing : float, optional

Plot spacing between chains (defaults to 0.1).

vline : numeric, optional

Location of vertical reference line (defaults to 0).

gs : GridSpec

Matplotlib GridSpec object. Defaults to None.

plot_transformed : bool

Flag for plotting automatically transformed variables in addition to original variables (defaults to False).

plot_kwargs : dict

Optional arguments for plot elements. Currently accepts ‘fontsize’, ‘linewidth’, ‘marker’, and ‘markersize’.

Returns:

gs : matplotlib GridSpec

pymc3.plots.compareplot(comp_df, insample_dev=True, se=True, dse=True, ax=None, plot_kwargs=None)

Model comparison summary plot in the style of the one used in the book Statistical Rethinking by Richard McElreath.

Parameters:

comp_df: DataFrame

the result of the pm.compare() function

insample_dev : bool

plot the in-sample deviance, that is the value of the IC without the penalization given by the effective number of parameters (pIC). Defaults to True

se : bool

plot the standard error of the IC estimate. Defaults to True

dse : bool

plot standard error of the difference in IC between each model and the top-ranked model. Defaults to True

plot_kwargs : dict

Optional arguments for plot elements. Currently accepts ‘color_ic’, ‘marker_ic’, ‘color_insample_dev’, ‘marker_insample_dev’, ‘color_dse’, ‘marker_dse’, ‘ls_min_ic’ ‘color_ls_min_ic’, ‘fontsize’

ax : axes

Matplotlib axes. Defaults to None

Returns:

ax : matplotlib axes

pymc3.plots.autocorrplot(trace, varnames=None, max_lag=100, burn=0, plot_transformed=False, symmetric_plot=False, ax=None, figsize=None)

Bar plot of the autocorrelation function for a trace.

Parameters:

trace : result of MCMC run

varnames : list of variable names

Variables to be plotted, if None all variable are plotted. Vector-value stochastics are handled automatically.

max_lag : int

Maximum lag to calculate autocorrelation. Defaults to 100.

burn : int

Number of samples to discard from the beginning of the trace. Defaults to 0.

plot_transformed : bool

Flag for plotting automatically transformed variables in addition to original variables (defaults to False).

symmetric_plot : boolean

Plot from either [0, +lag] or [-lag, lag]. Defaults to False, [-, +lag].

ax : axes

Matplotlib axes. Defaults to None.

figsize : figure size tuple

If None, size is (12, num of variables * 2) inches. Note this is not used if ax is supplied.

Returns:

ax : matplotlib axes

pymc3.plots.energyplot(trace, kind='kde', figsize=None, ax=None, legend=True, shade=0.35, bw=4.5, frame=True, kwargs_shade=None, **kwargs)

Plot energy transition distribution and marginal energy distribution in order to diagnose poor exploration by HMC algorithms.

Parameters:

trace : result of MCMC run

kind : str

Type of plot to display (kde or histogram)

figsize : figure size tuple

If None, size is (8 x 6)

ax : axes

Matplotlib axes.

legend : bool

Flag for plotting legend (defaults to True)

shade : float

Alpha blending value for the shaded area under the curve, between 0 (no shade) and 1 (opaque). Defaults to 0.35

bw : float

Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott’s rule of thumb (the default rule used by SciPy). Only works if kind=’kde’.

frame : bool

Flag for plotting frame around figure.

kwargs_shade : dicts, optional

Additional keywords passed to fill_between (to control the shade)

Returns

——-

ax : matplotlib axes

pymc3.plots.kdeplot(values, label=None, shade=0, bw=4.5, ax=None, kwargs_shade=None, **kwargs)

1D KDE plot taking into account boundary conditions

Parameters:

values : array-like

Values to plot

label : string

Text to include as part of the legend

shade : float

Alpha blending value for the shaded area under the curve, between 0 (no shade) and 1 (opaque). Defaults to 0

bw : float

Bandwidth scaling factor. Should be larger than 0. The higher this number the smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott’s rule of thumb (the default rule used by SciPy).

ax : matplotlib axes

kwargs_shade : dicts, optional

Additional keywords passed to matplotlib.axes.Axes.fill_between (to control the shade)

Returns

———-

ax : matplotlib axes

pymc3.plots.densityplot(trace, models=None, varnames=None, alpha=0.05, point_estimate='mean', colors='cycle', outline=True, hpd_markers='', shade=0.0, bw=4.5, figsize=None, textsize=12, plot_transformed=False, ax=None)

Generates KDE plots for continuous variables and histograms for discretes ones. Plots are truncated at their 100*(1-alpha)% credible intervals. Plots are grouped per variable and colors assigned to models.

Parameters:

trace : trace or list of traces

Trace(s) from an MCMC sample.

models : list

List with names for the models in the list of traces. Useful when plotting more that one trace.

varnames: list

List of variables to plot (defaults to None, which results in all variables plotted).

alpha : float

Alpha value for (1-alpha)*100% credible intervals (defaults to 0.05).

point_estimate : str or None

Plot point estimate per variable. Values should be ‘mean’, ‘median’ or None. Defaults to ‘mean’.

colors : list or string, optional

List with valid matplotlib colors, one color per model. Alternative a string can be passed. If the string is cycle, it will automatically choose a color per model from matplolib’s cycle. If a single color is passed, e.g. ‘k’, ‘C2’ or ‘red’ this color will be used for all models. Defaults to cycle.

outline : boolean

Use a line to draw KDEs and histograms. Default to True

hpd_markers : str

A valid matplotlib.markers like ‘v’, used to indicate the limits of the hpd interval. Defaults to empty string (no marker).

shade : float

Alpha blending value for the shaded area under the curve, between 0 (no shade) and 1 (opaque). Defaults to 0.

bw : float

Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott’s rule of thumb (the default rule used by SciPy).

figsize : tuple

Figure size. If None, size is (6, number of variables * 2)

textsize : int

Text size of the legend. Default 12.

plot_transformed : bool

Flag for plotting automatically transformed variables in addition to original variables Defaults to False.

ax : axes

Matplotlib axes.

Returns:

ax : Matplotlib axes

pymc3.plots.pairplot(trace, varnames=None, figsize=None, text_size=None, gs=None, ax=None, hexbin=False, plot_transformed=False, divergences=False, kwargs_divergence=None, sub_varnames=None, **kwargs)

Plot a scatter or hexbin matrix of the sampled parameters.

Parameters:

trace : result of MCMC run

varnames : list of variable names

Variables to be plotted, if None all variable are plotted

figsize : figure size tuple

If None, size is (8 + numvars, 8 + numvars)

text_size: int

Text size for labels

gs : Grid spec

Matplotlib Grid spec.

ax: axes

Matplotlib axes

hexbin : Boolean

If True draws an hexbin plot

plot_transformed : bool

Flag for plotting automatically transformed variables in addition to original variables (defaults to False). Applies when varnames = None. When a list of varnames is passed, transformed variables can be passed using their names.

divergences : Boolean

If True divergences will be plotted in a diferent color

kwargs_divergence : dicts, optional

Aditional keywords passed to ax.scatter for divergences

sub_varnames : list

Aditional varnames passed for plotting subsets of multidimensional variables

Returns

——-

ax : matplotlib axes

gs : matplotlib gridspec