Transform posterior draws with their metadata

Applies a strictly monotone transformation to BayesTools posterior draws (an element returned by marginal_posterior(), parameter_mixed_posterior(), as_mixed_posteriors(), or mix_posteriors(), or a list of them) and transforms the draw metadata (posterior_metadata()) with the values, so that inference, plots, and summaries of the transformed draws remain valid. Arithmetic on draws returns plain numeric draws without metadata; this function is the route for transformed posterior distributions.

posterior_transform(x, transformation, transformation_arguments = NULL)

Arguments

x

BayesTools posterior draws with metadata, or a list of them.

transformation

a transformation in the form accepted by marginal_posterior(): "lin" (a + b * x), "exp_lin" (exp(a + b * log(x))), "exp", "tanh", or a list of functions fun, inv, and jac (the transformation, its inverse, and its derivative), optionally with output_support.

transformation_arguments

optional named list of arguments of the transformation (a and b of "lin" and "exp_lin").

Value

x with transformed values and metadata.

Details

The transformation must be strictly monotone and invertible. "lin" and "exp_lin" with b = 0 are constant, and a transformation given as functions must have a finite, nonzero derivative of one sign at every draw and atom; otherwise the function stops with an error of class BayesTools_nonmonotone_transformation. Draws that the transformation maps to non-finite values (for example, negative draws of "exp_lin") stop with class BayesTools_transformation_domain. Both classes have the parent class BayesTools_transformation. Finite builtin images that round to mathematical limits (exponential zero, tanh endpoints, or positive-power zero from a strictly positive source) stop with BayesTools_transformation_image_unavailable, also inheriting BayesTools_transformation, error and condition. Its call is NULL; transformation names the builtin or "custom", and source_values and images contain matched failing finite entries. Declared point and support mapping uses the same condition for nonrepresentable images. True source zero under a positive power and infinite mathematical support limits remain valid. No clipping or probability-mass repair is performed.

The metadata are transformed as follows: A missing canonical prior law is first built from the complete declared source context and recipe, preserving its conditioning and coefficient or formula-contribution space. It is then transformed once. An attached law on the current output scale takes precedence over the original source context in plots. Known unsupported or numerical prior-law routes retain usable posterior draws and declare the prior density unavailable; requesting a prior overlay raises BayesTools_formula_prior_density_unavailable. Transformed publication-bias scalar prior overlays require a supported current-scale law and otherwise have the same explicit limitation.

support

the bounds and points are mapped, and the bounds of decreasing transformations swapped. The support of a transformation given as functions is unknown and removed.

atoms

the locations are mapped; the masses are kept.

prior_density, prior_densities

change of variables through the transformation machinery of the prior densities: a density built from a prior-density context or a linear combination of priors is rebuilt with the transformation as its output transformation (the density marginal_posterior() returns with transformation), a density that already has an output transformation or is an allocation product is transformed on top of its recorded provenance, and a density grid without provenance stays a grid for plotting only.

posterior_density, posterior_ordinate

the locations are mapped and the heights divided by the absolute derivative of the transformation; a density or ordinate whose transformed heights are not finite and positive (e.g. at a point where the derivative vanishes) is removed. Diagnostics are kept; their null-value entries (bf_value, value, null_hypothesis) are mapped.

components

the per-component supports are transformed.

linear_weights

"lin" scales the weights by b and adds a to the offset (linear_offset); any other transformation removes them and records its name in the joint prior transformation.

quantities

the name of the transformation ("custom" for functions) is appended to the transformation of the label parts; the columns are no longer the catalog quantities (the quantity id is "") and declare fitted coordinates only for "lin" with a = 0, whose weights are scaled by b. The rendered labels are unchanged.

The conditioning (condition), undefined draws, and the other metadata are kept, the applied transformation is appended to the output_transformations metadata (whether or not the draws have a quantities table), and the metadata record the fingerprint of the transformed values. The prior_list attribute of mixed posteriors describes their untransformed values: marginal_posterior() refuses transformed mixed posteriors whose prior it would build from it; use its transformation argument instead.

See also

marginal_posterior(), posterior_metadata()

Examples

draws <- structure(stats::rnorm(100), class = c("marginal_posterior.simple", "marginal_posterior"))
posterior_metadata(draws, "support") <- posterior_support_attribute(c(-Inf, Inf))
posterior_metadata(draws, "atoms") <- posterior_atom_attribute()
transformed <- posterior_transform(draws, "exp")
posterior_metadata(transformed, "support")
#> $bounds
#> [1]   0 Inf
#> 
#> $points
#> numeric(0)
#> 
#> $exact
#> [1] TRUE
#> 
#> $source
#> NULL
#> 
#> $type
#> [1] "interval"
#> 
#> attr(,"class")
#> [1] "BayesTools_posterior_support" "list"