Model as a Distribution

to_distribution wraps a compiled BUGSModel as a Distributions.Distribution whose variate is a NamedTuple. This lets you treat a model's joint density as an ordinary distribution object: you can rand a draw and evaluate logpdf / pdf / loglikelihood on a NamedTuple keyed by the model's parameter symbols.

The wrapper is deliberately a constrained-space view of the model. It always evaluates in the model's original parameter space, always uses graph evaluation, and logpdf returns the full joint density (prior plus the likelihood of any observed data baked into the model). It is not an unconstrained-space target for gradient-based samplers — see the Limitations admonition below.

You obtain a BUGSModel by compiling a model definition with compile (see Getting Started and Two Macros: @bugs & @model), then pass it to to_distribution.

Quick Example

using JuliaBUGS, Distributions, Random
Random.seed!(123)  # make the draw below reproducible

model_def = @bugs begin
    x ~ dnorm(0, 1)
    y ~ dnorm(x, 1)
end

# `y` is observed data; `x` is the only free parameter.
model = compile(model_def, (; y = 1.0))
d = to_distribution(model)

BUGSModelDistribution{(:x,)}(…)

A draw is a NamedTuple keyed by the parameter symbol:

nt = rand(d)

(x = -1.4632513788889214,)

logpdf returns the log joint density:

logpdf(d, nt)   # logprior(x) + loglikelihood(y | x)

-5.9422330431185975

pdf is its exponential, and loglikelihood is an alias for the same joint (not a data-only likelihood) — so it equals logpdf:

pdf(d, nt), loglikelihood(d, nt) == logpdf(d, nt)

(0.002626158772714837, true)

rand(d) performs ancestral sampling and returns one NamedTuple field per unique parameter symbol; logpdf(d, nt) accepts the same shape and returns the log joint density in the model's original (constrained) parameter space.

Interface Reference

The variate type

to_distribution(model) returns a BUGSModelDistribution{names,M,S,T} <: Distribution{NamedTupleVariate{names},S}. The variate is a NamedTuple whose fields are the unique top-level parameter symbols of the model. The keys are derived by iterating parameters(model), taking AbstractPPL.getsym(vn) for each parameter VarName, and deduplicating while preserving graph evaluation order.

There is exactly one field per top-level symbol. An array parameter is therefore a single whole-array field (e.g. (x = [v1, v2, v3],)) — never one key per element. A NamedTuple's field names must be plain Symbols, so indexed names like Symbol("x[1]") are not used (and would not resolve as @varname(x[1])).

Type parameters

Sampling and density methods

logpdf (and thus pdf / loglikelihood) throws

ArgumentError: logpdf: missing value for parameter `$vn` in NamedTuple input

when AbstractPPL.hasvalue(x, vn) is false for any free-parameter VarName.

Semantics

rand bakes observed data into whole arrays

rand(rng, d) runs ancestral sampling and then reads each parameter symbol back out of the evaluation environment with getfield. Because it reads the whole top-level symbol, for a partially-observed array the returned field is the full array — free slots filled by the sampled values, observed slots holding the model's baked-in data. The draw is therefore ready to be fed straight back into logpdf.

logpdf reads only the free parameters

logpdf starts from an isolated copy of the model's evaluation environment (smart_copy_evaluation_env(model.evaluation_env, model.mutable_symbols), not the live env, to avoid mutating the model's deterministic array nodes), which already contains the observed data. It then overlays only the free parameters: for each vn in parameters(model) it reads the value from x by that VarName's optic (AbstractPPL.getvalue) and writes it with BangBang.setindex!!(env, value, vn). Observed data (already in env) and deterministic nodes (recomputed during evaluation) are never read from x.

A direct consequence: logpdf is invariant to whatever you place in observed or deterministic slots of the input. For a partially-observed array, only the free-parameter slots affect the result; the observed slots are ignored and the model's own data is scored instead.

using JuliaBUGS, Distributions

model_def = @bugs begin
    for i in 1:3
        x[i] ~ dnorm(0, 1)
    end
end

# x[1] observed, x[2] and x[3] free.
model = compile(model_def, (; x = [1.0, missing, missing]))
d = to_distribution(model)

# Pass a full-shaped array. The first slot's value is ignored — the model's
# observed x[1] = 1.0 is scored regardless of what you put there:
logpdf(d, (x = [999.0, 0.5, -0.5],)) == logpdf(d, (x = [1.0, 0.5, -0.5],))

true

The cleanest usage is to start from a rand(d) draw and modify only the free positions before calling logpdf.

Constrained space, no Jacobian

Both rand and logpdf force transformed=false, regardless of model.transformed. logpdf adds no log-abs-det-Jacobian: it returns a density with respect to the natural (constrained) variate the user supplies and receives. This makes the wrapper a faithful density over the NamedTuple it accepts, but means it is not, on its own, a correct unconstrained-space target.

Full joint density

logpdf returns the untempered joint log_densities.logprior + log_densities.loglikelihood (independent of any temperature default), with observed data baked into the model. Two models that differ only in their observed data are different BUGSModelDistributions and give different logpdf values for the same free-parameter input. loglikelihood(d, x::NamedTuple) is an alias for this joint logpdf — it is not a prior-only or data-only quantity. Use the underlying model API if you need those terms separately.

Value support reduction

The S type parameter is computed by collecting the value_support of every free (stochastic, unobserved) node's distribution and reducing with promote_type. A model whose free parameters mix discrete and continuous distributions therefore reports Continuous; a model with no free stochastic nodes defaults to Continuous. This reported support is lossy and is cosmetic for density evaluation — each node still uses its true distribution — but generic code dispatching on value_support(typeof(d)) should be aware of the collapse.

Always graph evaluation; evaluation_mode warning

The wrapper always uses graph evaluation (UseGraph) and ignores model.evaluation_mode. If the model's mode is not a UseGraph, to_distribution emits a one-time (maxlog=1) @warn noting that it ignores the mode and that its logpdf may differ from LogDensityProblems.logdensity for such a model (e.g. a marginalized one). See Evaluation Modes and Auto-Marginalization for the modes this concerns.

Design notes / decisions

Symbol-grouped NamedTuple variate

The variate keys are top-level symbols, not per-element optics. A NamedTuple's fields must be plain Symbols, so they can only carry top-level identifiers; getsym is exactly the function that maps a VarName back to its top-level symbol, and deduplicating with a membership check (rather than a Set) keeps a stable, reproducible field ordering tied to graph evaluation order.

The tradeoff is intrinsic to choosing a NamedTuple variate: it cannot distinguish a loop-declared array x[i] from a single multivariate node x[1:3] (both become (x = Vector,)), and it cannot key individual array elements. Callers needing per-element addressing must use a container with real VarName keys (e.g. a Dict{VarName}), which is outside this interface.

Observed data sourced from the model

logpdf overlays only free parameters by their precise VarName optic and leaves observed and deterministic entries to the model. An earlier implementation overlaid whole top-level symbols by bare Symbol (setindex!!(env, x.x, :x)), which clobbered the observed slots of a partially-observed array with caller-supplied values — making the density depend on junk in observed positions. Addressing each free parameter by VarName touches exactly the stochastic-unobserved slots; using smart_copy rather than the live env keeps logpdf free of observable side effects on the model's deterministic array nodes.

Full-joint semantics and the loglikelihood alias

Because observed data is part of the model rather than the variate, the natural density over the free-parameter NamedTuple is the joint (prior times the likelihood of the baked-in data). Defining Distributions.loglikelihood as an alias for the joint logpdf populates the Distributions interface without inventing a separate, ambiguous data-only quantity the wrapper cannot cleanly express.

Always UseGraph

Graph evaluation is the well-defined path for ancestral sampling and for overlaying free parameters by VarName, giving a consistent, predictable joint density. Other modes (e.g. marginalization) compute a different quantity, so the wrapper fixes the mode rather than silently producing a number whose meaning depends on a mode the caller may not be tracking; the rate-limited warning informs without spamming. For a marginalized model, logpdf(d, nt) can disagree with LogDensityProblems.logdensity(model, ...) — the warning flags this, but the divergence is real.

Partially-observed arrays

A symbol-grouped variate forces one field per array, so the contract is: pass a full-shaped array (exactly what rand(d) returns), and the wrapper extracts only the free-parameter slots it actually needs. This makes rand/logpdf round-trip cleanly while remaining invariant to observed-slot contents. The surprise is that some supplied entries are silently ignored; the cleanest usage is to modify a rand(d) draw in place.

Limitations and non-goals

API

to_distribution(model::BUGSModel)

model_def = @bugs begin
    x ~ dnorm(0, 1)
    y ~ dnorm(x, 1)
end
model = compile(model_def, (; y = 1.0))
d = to_distribution(model)
nt = rand(d)             # (x = ...,)
logpdf(d, nt)