Computes density of a prior distribution across a range of values.
# S3 method for class 'prior'
density(
x,
x_seq = NULL,
x_range = NULL,
x_range_quant = NULL,
n_points = 1000,
n_samples = 10000,
force_samples = FALSE,
individual = FALSE,
transformation = NULL,
transformation_arguments = NULL,
transformation_settings = FALSE,
truncate_end = TRUE,
...
)a prior
sequence of x coordinates
vector of length two with
lower and upper display limits
(used if x_seq is unspecified)
quantile used for
automatically obtaining x_range
if both x_range and x_seq
are unspecified. A number in the open interval (0, 0.5);
other values are refused. Defaults to 0.005
for all but Cauchy, Student-t, Gamma, inverse-gamma,
moment, and inverse-moment distributions that use
0.010.
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)
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.
whether the density should be set to zero for endpoints of truncated distributions
additional arguments
density.prior returns an object of class 'density'. For
Dirichlet simplex priors it returns a named list of beta-marginal density
objects, one for each simplex coordinate. Ordered priors return one component
per factor level. When a level has both discrete and continuous probability,
its atoms table stores exact location and mass values,
while its continuous table stores a density already weighted to
integrate to the remaining continuous mass over its full support. A clipped
plotting grid preserves density heights;
diagnostics$continuous_integral reports its numerical trapezoid
integral, which can differ from the exact continuous mass because of
clipping and grid discretization. Nonfinite continuous ordinates are omitted
by the structural mixed-measure route; the curve is not renormalized.
A supported scalar point total times a random allocation share has a
continuous scaled-Beta distribution at intermediate levels, with declared
atoms retained for zero-total branches, reference levels, fixed shares,
and the full-total level.
A spike-and-slab prior returns a list of class
density.prior.spike_and_slab with the slab density (variable)
and the density of the spike at zero (inclusion), each scaled by its
prior mass. Under a transformation, a prior with inclusion probability
1 has no prior mass in the spike, returns inclusion = NULL, and does
not require a representable image of the spike location (for example
log(0)); any other inclusion probability does.
Sample-based density estimates for continuous priors with finite
support use boundary-reflected kernel density estimates. The plotting range
controls the evaluation grid, while reflection is based on the prior's true
truncation bounds.
Automatic transformed prior-coordinate ranges keep the existing source
range and equally spaced source grid. Where the existing marginal and
transformed density route supports it, a source display endpoint with an
infinite transformed image uses the prior's existing marginal
tail quantile, controlled by x_range_quant. Prior-list plots use the
union of participating component marginal quantiles. This is a finite display window;
the prior support, density, probability masses and mixture weights are unchanged.
Invalid atom images remain unavailable. When an endpoint quantile is
unavailable or its transformed image is still not finite (for example the 0.995
quantile of a very wide prior under "exp"), the automatic display range
of the transformed prior is unavailable: density() stops with
BayesTools_prior_range_unavailable, parent
BayesTools_transformation_domain and BayesTools_transformation,
with call = NULL, and the message names the remedy of explicit display
limits (x_range or x_seq; xlim in the plotting functions).
In plot_posterior() only the prior curve is omitted, with a warning of
class BayesTools_prior_curve_unavailable (see there), and the posterior
is drawn alone. Explicit source or transformed coordinates keep
their supplied interpretation. Individual weightfunction and ordered routes
retain their existing transformation behavior and conditions.
Nonindividual PET/PEESE standard-error axes
and weightfunction p-value axes retain their specialized interpretation.
Declared point locations and finite builtin support bounds must have
representable images. Finite-source exponential underflow, tanh saturation,
positive-power underflow and nonfinite point images stop with
BayesTools_transformation_image_unavailable, parent
BayesTools_transformation, with call = NULL and fields
transformation, source_values, and images for the
matched failing finite sources. True zero under positive powers and infinite
mathematical support limits retain their meaning. Continuous display grids
retain their existing handling.
Direct ordered Dirichlet-product densities use stable log-share arithmetic
for literal, untruncated Normal totals with mean zero and finite positive SD,
retaining the existing quadrature budget and tolerances. This guarded route
does not certify tiny or nonrepresentable ranges. Every other total takes
the same quadrature at each display value and accepts it when it converges
within its tolerances and exceeds the absolute tolerance (the integral of a
total concentrated away from zero can miss the band where the integrand is
positive and give zero); the display values it does not accept take the
structural route of the level (its total times a Beta share), built without
a numerical grid. A quadrature that does not converge is not repeated for the
rest of the level. Small second Beta shapes remain a numerical risk of the
quadrature. A display value whose density neither the quadrature nor the route
resolves (an NA height inside the support) is left out of the level and
reported by a warning of class
BayesTools_prior_curve_unavailable with the fields
unresolved_values, structural_values (the limits at support
ends without a structural classification, which are not warned about) and
levels.