R/model-averaging-plots-posterior.R
plot_posterior.RdPlot samples from the mixed posterior distributions
plot_posterior(
samples,
parameter,
plot_type = "base",
prior = FALSE,
n_points = 1000,
n_samples = 10000,
force_samples = FALSE,
individual = FALSE,
show_figures = NULL,
transformation = NULL,
transformation_arguments = NULL,
transformation_settings = FALSE,
rescale_x = FALSE,
par_name = NULL,
effect_direction = "positive",
dots_prior = list(),
data = NULL,
show_data = FALSE,
dots_data = list(),
legend = TRUE,
legend_title = NULL,
legend_labels = NULL,
legend_position = NULL,
...,
density_method = c("KDE", "precomputed")
)samples from a posterior distribution for a parameter generated by mix_posteriors or as_mixed_posteriors.
parameter name to be plotted. Use "PETPEESE"
for PET-PEESE plot with parameters "PET" and "PEESE",
and "weightfunction" for plotting a weightfunction with
parameters "omega". The combined "PETPEESE" curve requires
individual = FALSE; use "PET" or "PEESE" for individual
coefficient densities.
whether to use a base plot "base"
or ggplot2 "ggplot" for plotting.
whether prior distribution should be added to the figure.
When samples were prepared with as_mixed_posteriors(..., transform_scaled = TRUE),
the transformed prior samples are automatically used.
number of equally spaced points
in the x_range if x_seq is unspecified
number of samples from the prior
distribution if the density cannot be obtained
analytically (or if samples are forced with
force_samples = TRUE)
should prior be sampled instead
of obtaining analytic solution whenever possible. For supported ordered
mixed measures, exact analytic curves and atoms are retained and the
requested samples are attached to each component. Supported scalar ordered
literal point totals and mixtures whose total components are all literal
points do not sample, store draws, or advance the RNG when
force_samples = FALSE. With force_samples = TRUE, their
original seeded draws are attached without replacing the analytic measure.
Other ordered families retain their existing sampling fallback.
should individual densities be returned (e.g., in case of weightfunction)
which figures should be returned in case of
multiple plots are generated. Useful when priors for the omega
parameter are plotted and individual = TRUE. For weight functions
plotted individually by plot.prior() and plot_posterior(),
figure k shows the publication weight omega of the k-th
p-value interval in ascending order, the order in which summary tables
(including RoBMA's) print the omegas; figure 1 is the reference weight of
the most significant interval. In plot.prior(), a negative k
omits figure -k (the default -1 omits the reference weight
fixed at 1). For a two-sided weight function prior, the intervals are its
two-sided p-value bins; tables on the one-sided p-value scale print these
weights first and then repeat them for the mirrored intervals.
transformation to be applied to the prior distribution. Either a character specifying one of the prepared transformations:
linear transformation in form of a + b*x
hyperbolic tangent transformation
exponential transformation
, or a list containing the transformation function fun,
inverse transformation function inv, and derivative of the
transformation jac, evaluated on the original support. A custom
transformation can also declare output_support = c(lower, upper).
Display grids on the transformed scale are evaluated only within these
bounds; a wider plotting range is retained without extending the density.
Infinite inverse values at support boundaries are omitted from continuous
density grids. Point masses retain their transformed locations.
a list with named arguments for
the transformation
boolean indicating whether the
explicitly supplied x_seq or x_range is on
the transformed scale. Automatically selected prior-coordinate ranges
are always obtained on the source scale before the density family's
existing transformation handling.
allows to rescale x-axis in case a weightfunction is plotted.
a type of parameter for which the prior is specified. Only relevant if the prior corresponds to a mu parameter that needs to be transformed.
direction of the effect for PET-PEESE
regression. Use "positive" (default) for
mu + PET*se + PEESE*se^2 or "negative" for
mu - PET*se - PEESE*se^2.
additional arguments for the prior distribution plot
optional numeric vector of observed p-values in [0, 1], or
a data frame with a p column. Used only for weightfunction plots.
whether observed p-values should be shown as rug marks on the weightfunction x-axis.
additional styling arguments for observed p-value rug marks.
Supports col/color, alpha, lwd/linewidth,
side/rug_side, and height/rug_height.
whether factor legends should be drawn.
optional title for factor legends.
optional labels for factor legend levels.
optional legend position for factor legends.
additional graphical arguments. For mixed continuous and point
distributions, ylim controls the density axis, ylim2 controls
the probability-mass axis, and ylab2 controls its label.
density source for continuous posterior curves.
"KDE" computes a kernel density estimate. Plot methods with exact
finite prior-support bounds apply boundary reflection.
"precomputed" uses valid posterior_density metadata when
matching the selected parameter and condition; a missing or unusable
continuous curve stops with a remedy to supply matching metadata or use
"KDE". Pure-atom targets need no continuous curve. A precomputed density is the
continuous part of the posterior; atoms are drawn from the declared
posterior atoms with either method.
plot_posterior returns either NULL or
an object of class 'ggplot' if plot_type is plot_type = "ggplot".
When using scaled predictors (via formula_scale_list in JAGS_fit),
you can plot posteriors on the original (unscaled) scale by preparing samples with
as_mixed_posteriors(..., transform_scaled = TRUE). The function automatically
detects this and uses the pre-computed transformed prior samples when prior = TRUE.
Posterior sample vectors may carry posterior_density metadata
(posterior_metadata()) with x and y coordinates. These densities are used only when
density_method = "precomputed". A stored density describes the
continuous part of the posterior; point masses are drawn from the declared
posterior atoms (the atoms metadata, see posterior_atom_attribute())
with either density method. A declared continuous component (or the
continuous part of a factor level) that received fewer than two distinct
continuous draws has no kernel density, as for a model of posterior
probability near or below one over n_samples in mix_posteriors():
its curve is omitted and the declared point masses are drawn, with a
warning of class BayesTools_posterior_curve_unavailable (also
BayesTools_plot_condition) that reports the declared continuous mass
and the number of continuous draws; use a larger n_samples in
mix_posteriors(). Without declared point masses to draw, the plot stops.
plot_marginal() does likewise.
Prior-density curves are evaluated on their exact routes where they exist.
A combination without an exact route is drawn from its numerical grid;
when that grid cannot resolve the scale of a heavy-tailed product term
(e.g., an intercept plus a level of an ordered factor with a Cauchy total),
the prior curve is omitted with a warning of class
BayesTools_prior_curve_unavailable (also
BayesTools_plot_condition) and the rest of the plot is drawn.
Posterior draws that declare no prior (a prior_list of
prior_none(), as parameter_mixed_posterior() draws of a quantity
without a prior density) and carry no prior density have no prior curve:
with prior = TRUE, the posterior is drawn alone with a warning of
the same class. The same holds for a prior with parameters given as
expression()s, which only JAGS evaluates and which has no R-side
prior law (unless the atoms or the support of the draws are unavailable,
which posterior_measure_check() reports).
Likewise, when the automatic display range of a transformed prior is
unavailable (the marginal-quantile endpoints of a very wide prior have no
finite image under transformation = "exp", see density.prior()), the
prior curve is omitted with the same warning, which names xlim, and the
posterior is drawn alone; an explicit xlim avoids the omission.
Raw numerical plotting evaluations that remain unresolved warn once per
continuous route with the same classes. The warning distinguishes a partly
available curve from a wholly unavailable one; every available curve point
and declared atom is retained. Its unresolved_values field contains
the evaluation coordinates on the source scale, before any plotting
transformation. Use prior = FALSE to draw the posterior
alone. Exact infinite density points and exact zero densities do not trigger
this warning. Finite displayed peak heights depend on the evaluation grid.
Ordered factors are plotted as semantic level effects. Their persisted
zero-design reference rows are omitted for both raw and already transformed
inputs; genuine non-reference zero and point levels remain. Both finite and
singular non-reference prior curves retain their actual finite ordinates.
Colors and legend_labels refer to the full retained non-reference
level list. Visible curves
and point masses determine the axes. Ordered prior overlays default to the
corresponding posterior colors and dashed lines; explicit dots_prior
col, lty, or linetype override these defaults. The
posterior owns the legend.
For base plots, the initial call establishes the density-to-probability
mapping. Calls with add = TRUE reuse that mapping so point masses from
separate prior or posterior objects remain comparable. Point masses outside
the active ylim2 are clipped with a warning; redraw the initial plot
with wider limits to display them.