prior_density_ordinate() classifies the mathematical behavior of a prior at
one exact value. The classification uses the prior definition and
deterministic provenance recorded on linear-combination prior densities. It
does not use samples, kernel density estimates, numerical grids, or nearby
probe values to establish the behavior.
Declared atom producers refuse nonrepresentable finite-source transformation
images with BayesTools_transformation_image_unavailable (parent
BayesTools_transformation); fields transformation,
source_values and images identify the failing entries, with
call = NULL. Conservative provenance certification remains unknown
when an image cannot be established, without manufacturing a boundary atom.
prior_density_ordinate(x, value)A named list of class prior_density_ordinate with fields:
schema_version: the stable result-schema version, currently "1";
value: the requested value;
behavior: one of "regular", "zero", "infinite",
"point_mass", "undefined", or "unknown";
log_density: the continuous log-density ordinate, when available;
point_mass: discrete probability at exactly value;
exact: whether behavior follows from deterministic prior provenance
and, for a "regular" ordinate, log_density is available (in closed
form or from a quadrature accepted by its diagnostics). A regular ordinate
without a value (a quadrature rejected by its diagnostics, or a boundary
limit without a structural value) has exact = FALSE, log_density = NA
and the failure in reason; so has an ordinate whose evaluation point, or
a value computed from value on the way to it, is not representable at
full double precision (e.g. a subnormal value or distance from an
offset), with behavior = "regular" where the route has established it
(inside the support) and "unknown" otherwise (e.g. an inverse affine
value that is not representable). exact = TRUE never comes with a
missing regular log_density;
method: a machine-readable classification method;
reason: NULL for an ordinary regular ordinate and a concise diagnostic
otherwise;
provenance: compact deterministic information used for classification.
When behavior is "point_mass" (and only then), it contains
continuous_behavior: the behavior of the continuous part of the prior at
value, i.e., of the measure without its point masses, as one of
"regular", "zero", "infinite", "undefined", or "unknown", with
the same meaning as behavior. It is "zero" when the prior has no
continuous part there (e.g., a point prior) and "unknown" when the
continuous part has no structural classification. log_density is then
the log density of that continuous part (not renormalized by the
continuous probability), which for an "unknown" continuous part may be a
numerical grid value or NA.
A regular classification is structural. Consequently, log_density may
be -Inf when an otherwise positive finite density underflows in ordinary
floating-point evaluation. General numerical convolutions, products, and
arbitrary user transformations are reported as unknown unless exact point
mass establishes the requested behavior.
Named monotone transformations retain their normalized arguments and declared
source support and atoms through composition. Two-term convolutions retain
their independent primitive definitions and signed support hull. Missing
structural support gives unknown, while a known invalid transformation
domain gives undefined. Finite endpoints or atoms whose images round to
an exponential or hyperbolic-tangent limit do not certify exact provenance.
Constant affine routes declare a point even without a source definition.
A stored point-only measure has exact zero continuous density away from its
atoms, including when no adaptive provenance is attached. Positive continuous
grids and deferred measures without a declared continuous mass remain unknown.
For exp_lin, positive powers are defined on nonnegative sources and map a
zero atom to zero with its original mass. The continuous density retains its
original mixture weight; atoms have no Jacobian density contribution. Negative
powers still refuse zero atoms, and negative source domains remain undefined.
Supported conditional-normal mixtures are structurally regular because they
include an independent positive-variance Gaussian term. A product term
(multiply_by) without an additive normal term is a pure scale mixture:
away from its deterministic offset it is regular, and at the offset its
density is \(\phi(b_m / b_s) E[1 / |s|] / b_s\) for a multiplied
\(N(b_m, b_s)\) term and multiplier \(s\), finite exactly when the
multiplier's declared density vanishes at zero and infinite otherwise.
Closed inverse moments retain their logarithms even when the natural
moment overflows. Provenance records availability, its reason and a
floating-resolution diagnostic; the diagnostic is not a rigorous
special-function error bound. Unsupported mapped-Beta shifts, differences
of log normalizers and unresolved offset arithmetic give a structurally
regular inexact ordinate with no log density. For example, a standard
Normal multiplied by a Lognormal with meanlog zero and sdlog 40 has
offset log density \(800 - \log(2\pi)/2\), which remains available.
Levels of ordered priors are the ordered total times their Dirichlet
allocation share and are classified in the same way; a non-normal total or
multiplied term uses the analogous "scale_mixture" quadrature. A level of
an interaction takes the share of its slice (the coordinates of the ordinary
factors, whose totals and allocations are independent). A level of several
ordered factors, a combination across slices, or a combination of
increments that is not one cumulative share is a total (or several
independent totals) times a multilinear function of independent Beta
coordinates of the allocations: for a single total with a simple
continuous prior, or normal totals, the ordinate and region probabilities
integrate the closed-form conditional law over these coordinates with a
tensor Gauss-Jacobi rule, doubled until two rules agree (method
"scale_mixture", provenance ordered_product); a total with a finite
support bound is integrated with the closed-form breakpoints where the
argument of its density crosses a bound (at most three coordinates; a
density that is infinite at a bound is smoothed there with its closed-form
exponent, and refused when the exponent is unknown or below 0.5). Its
offset density is classified for a single total times a product of shares,
and a Beta exponent below 0.1 rejects the quadrature. Other combinations (several
totals that are not normal, point totals that make the level a nonlinear
function of several shares) are unknown and refused. Their
ordinates use
quadrature over the multiplier's declared support, split at its bounds, at
quantiles of its declared prior (spaced out next to a bound with infinite
density) and around the location peak of the conditional normal density
(kept next to such a bound) when the multiplied standard deviation is at
most half of the absolute value of its mean (always for a Gaussian
convolution), and retain
integration errors and evaluation budgets in provenance. Every independent
quadrature
(each piece of a split integral, each distinct design row, model or
conditional mixture component, and spike-and-slab or mixture leaf) receives
the full evaluation budget of the
density (its grid size) and its own convergence check. provenance reports
the evaluations summed over all of them; its budget is the grid size per
split integral (the budget of each of its pieces), summed over rows,
components and leaves. Split integrals also keep each piece's evaluations
and absolute error, and row mixtures each row's diagnostics. An accepted
quadrature has exact = TRUE (the structural classification), while
provenance$integration$exact = FALSE describes the numerical ordinate.
A quadrature rejected by its diagnostics keeps the behavior "regular"
with exact = FALSE, log_density = NA, the rejection in reason and its
diagnostics (converged = FALSE) in provenance; requesting a density
height then rejects the result.
Mixture ordinates (model-averaged and conditional mixtures, and linear
combinations of mixture or spike-and-slab priors) are the probability-
weighted sums of their component ordinates, each classified by its own
method; a component with a truncated prior at its support bound uses the
one-sided limit inside the support. The continuous behavior of the mixture
follows the precedence "undefined" over "infinite" over "unknown": one
undefined component makes the mixture undefined, else one infinite component
makes it infinite (even beside an unknown one); otherwise, if any component
remains unknown, the whole mixture is unknown, and else it is "regular"
(some component regular) or "zero" (all zero). In any linear combination
(inside or outside a mixture), a Gaussian term plus one other continuous
scalar term is a Gaussian convolution evaluated by the same quadrature over
that term's declared support. When that term is a truncated normal, the
density is the closed form (method "truncated_normal_convolution")
\(\phi(x; m, s) [\Phi(\beta(x)) - \Phi(\alpha(x))] / [\Phi(B) - \Phi(A)]\):
\(m\) and \(s^2\) are the sums of the means and variances of the
untruncated terms, \(A\) and \(B\) the standardized truncation bounds,
and \(\alpha(x)\) and \(\beta(x)\) the truncation bounds standardized
by the normal distribution of the truncated term given the sum \(x\).
The exponential of a log-transformed positive term \(X\) plus a Gaussian
part \(G\) (e.g. the unscaled intercept of a log(intercept) formula
scaling) is the scale product of \(X\) and the lognormal
\(\exp(G)\) (method "scale_mixture"), and the log-scale sum
\(\log(X) + G\) is the log image of that product, with density
\(f(e^z) e^z\) (method "scale_mixture", provenance kind
"log_scale_product").
A linear combination \(a'X\) of a multivariate t vector prior
("mt", and "mcauchy" with one degree of freedom; e.g. levels and
contrasts of mean-difference and orthonormal factor priors) with location
\(\mu\), scale \(s\) (the scale matrix \(s^2 I\)) and \(\nu\)
degrees of freedom is the univariate t with location \(\mu \sum_j a_j\),
scale \(s \|a\|\) and \(\nu\) degrees of freedom; it enters the
combination as that scalar term, recorded in provenance$multivariate_t
(alone it is exact with method "scalar_affine").
Sums of Cauchy terms are Cauchy (method
"scalar_affine"), and two other continuous scalar terms without a
Gaussian part are a "convolution" quadrature over one term's declared
support; where finite support bounds of both terms meet at value, the
ordinate is classified from the terms' declared behavior at those bounds
(the positive finite limit at an end of the support where the density
exponents sum to one, e.g. two arcsine terms, is unknown). Sums of three
or more non-normal terms, or of a Gaussian part and two or more non-normal
terms, are unknown.
normal_prior <- prior("normal", list(mean = 0, sd = 1))
prior_density_ordinate(normal_prior, 0)
#> $schema_version
#> [1] "1"
#>
#> $value
#> [1] 0
#>
#> $behavior
#> [1] "regular"
#>
#> $log_density
#> [1] -0.9189385
#>
#> $point_mass
#> [1] 0
#>
#> $exact
#> [1] TRUE
#>
#> $method
#> [1] "primitive"
#>
#> $reason
#> NULL
#>
#> $provenance
#> $provenance$kind
#> [1] "primitive"
#>
#> $provenance$family
#> [1] "normal"
#>
#> $provenance$parameters
#> $provenance$parameters$mean
#> [1] 0
#>
#> $provenance$parameters$sd
#> [1] 1
#>
#>
#> $provenance$truncation
#> $provenance$truncation$lower
#> [1] -Inf
#>
#> $provenance$truncation$upper
#> [1] Inf
#>
#>
#>
#> attr(,"class")
#> [1] "prior_density_ordinate" "list"
gamma_prior <- prior("gamma", list(shape = 0.5, rate = 1))
prior_density_ordinate(gamma_prior, 0)
#> $schema_version
#> [1] "1"
#>
#> $value
#> [1] 0
#>
#> $behavior
#> [1] "infinite"
#>
#> $log_density
#> [1] Inf
#>
#> $point_mass
#> [1] 0
#>
#> $exact
#> [1] TRUE
#>
#> $method
#> [1] "primitive"
#>
#> $reason
#> [1] "The continuous prior density tends to positive infinity at the requested value."
#>
#> $provenance
#> $provenance$kind
#> [1] "primitive"
#>
#> $provenance$family
#> [1] "gamma"
#>
#> $provenance$parameters
#> $provenance$parameters$shape
#> [1] 0.5
#>
#> $provenance$parameters$rate
#> [1] 1
#>
#>
#> $provenance$truncation
#> $provenance$truncation$lower
#> [1] 0
#>
#> $provenance$truncation$upper
#> [1] Inf
#>
#>
#>
#> attr(,"class")
#> [1] "prior_density_ordinate" "list"
mixture_prior <- prior_mixture(
list(
prior("point", list(location = 0), prior_weights = 1),
prior("normal", list(mean = 0, sd = 1), prior_weights = 3)
),
is_null = c(TRUE, FALSE)
)
prior_density_ordinate(mixture_prior, 0)
#> $schema_version
#> [1] "1"
#>
#> $value
#> [1] 0
#>
#> $behavior
#> [1] "point_mass"
#>
#> $log_density
#> [1] -1.206621
#>
#> $point_mass
#> [1] 0.25
#>
#> $exact
#> [1] TRUE
#>
#> $method
#> [1] "finite_mixture"
#>
#> $reason
#> [1] "The prior assigns positive discrete probability to the requested value."
#>
#> $provenance
#> $provenance$kind
#> [1] "finite_mixture"
#>
#> $provenance$weights
#> [1] 0.25 0.75
#>
#> $provenance$components
#> $provenance$components[[1]]
#> $provenance$components[[1]]$weight
#> [1] 0.25
#>
#> $provenance$components[[1]]$behavior
#> [1] "point_mass"
#>
#> $provenance$components[[1]]$continuous_behavior
#> [1] "zero"
#>
#> $provenance$components[[1]]$point_mass
#> [1] 1
#>
#> $provenance$components[[1]]$provenance
#> $provenance$components[[1]]$provenance$kind
#> [1] "primitive"
#>
#> $provenance$components[[1]]$provenance$family
#> [1] "point"
#>
#> $provenance$components[[1]]$provenance$parameters
#> $provenance$components[[1]]$provenance$parameters$location
#> [1] 0
#>
#>
#> $provenance$components[[1]]$provenance$truncation
#> $provenance$components[[1]]$provenance$truncation$lower
#> [1] 0
#>
#> $provenance$components[[1]]$provenance$truncation$upper
#> [1] 0
#>
#>
#> $provenance$components[[1]]$provenance$continuous_behavior
#> [1] "zero"
#>
#>
#>
#> $provenance$components[[2]]
#> $provenance$components[[2]]$weight
#> [1] 0.75
#>
#> $provenance$components[[2]]$behavior
#> [1] "regular"
#>
#> $provenance$components[[2]]$continuous_behavior
#> [1] "regular"
#>
#> $provenance$components[[2]]$point_mass
#> [1] 0
#>
#> $provenance$components[[2]]$provenance
#> $provenance$components[[2]]$provenance$kind
#> [1] "primitive"
#>
#> $provenance$components[[2]]$provenance$family
#> [1] "normal"
#>
#> $provenance$components[[2]]$provenance$parameters
#> $provenance$components[[2]]$provenance$parameters$mean
#> [1] 0
#>
#> $provenance$components[[2]]$provenance$parameters$sd
#> [1] 1
#>
#>
#> $provenance$components[[2]]$provenance$truncation
#> $provenance$components[[2]]$provenance$truncation$lower
#> [1] -Inf
#>
#> $provenance$components[[2]]$provenance$truncation$upper
#> [1] Inf
#>
#>
#>
#>
#>
#> $provenance$continuous_behavior
#> [1] "regular"
#>
#>
#> attr(,"class")
#> [1] "prior_density_ordinate" "list"