Skip to content

Probabilistic graphs ​

Use ReactiveKernelsPPL to declare a model, bind its data and prepare a log-density query. The nested package supplies probabilistic authoring and coordinate transforms on top of the core graph compiler.

Declaration and binding ​

A model is a Julia block of sampling statements and deterministic assignments. Inputs such as prior scales and observations are supplied when binding, so their values remain data.

julia
using ReactiveKernelsPPL

model = @rkppl begin
    a ~ Normal(prior_location, prior_scale)
    b ~ Normal(prior_location, prior_scale)
    sigma ~ Exponential(noise_scale)
    mu = a .+ b .* x
    y .~ Normal.(mu, sigma)
end

x = [-1.0, 0.0, 1.0]
y = [-0.8, 1.1, 2.9]
bound = model(; x, prior_location=0.0, prior_scale=2.0, noise_scale=1.0) | (; y)
built = build_kernel(bound)
u = unconstrain(built.layout, (; a=1.0, b=2.0, sigma=0.3))
density = prepare_query(built, bound, :sampler)
density(u)

-4.831374751824716

The left side of | binds inputs. The right side observes declared variables and retains their densities as likelihood terms. An observed response whose element type admits missing is bound with a presence mask, however many entries are missing, so one program serves every absence pattern and the likelihood skips the absent entries. Supplying a declared variable directly as a model-call keyword pins it instead: that declaration and its density are removed. Choose the operation that expresses the intended probability model.

Coordinates ​

The layout maps structured constrained parameters to a packed unconstrained vector. Use the layout conversion rather than constructing that vector from an assumed ordering.

julia
parameters = constrain(built.layout, u)
(; names=coordinate_names(built.layout), parameters)

(names = [:a, :b, :sigma], parameters = (a = 1.0, b = 2.0, sigma = 0.3))

The sampler target includes the prior, likelihood and support-transform log Jacobian. A likelihood query excludes the other terms, and a pointwise query retains observation contributions under their response names.

julia
likelihood = prepare_query(built, bound, :likelihood)
pointwise = prepare_query(built, bound, :pointwise)
contributions = pointwise(u).y
@assert sum(contributions) ≈ likelihood(u)
(; contributions, sum=sum(contributions), likelihood=likelihood(u))

(contributions = [0.06281204889904135, 0.22947871556570776, 0.22947871556570776], sum = 0.5217694800304569, likelihood = 0.5217694800304568)

Observation parameters ​

:observations reads named numeric distribution parameters from the model graph, preserving shared scalars and observation order:

julia
outcomes = @rkppl begin
    a ~ Normal(0, 1)
    b ~ Normal(0, 1)
    @plate for i in eachindex(x)
        event[i] ~ BernoulliLogit(a + b * x[i])
        time[i] ~ Exponential(exp(a + b * x[i]))
    end
end
observed = outcomes(; x) | (; event = Bool[0, 1, 1], time = [0.5, 1.0, 2.0])
outcome_kernel = build_kernel(observed)
coordinates = unconstrain(outcome_kernel.layout, (; a = 0.2, b = 0.4))
parameters = prepare_query(outcome_kernel, observed, :observations)
parameters(coordinates)

(event = (probability = [0.45016600268752216, 0.549833997312478, 0.6456563062257954], logit = [-0.2, 0.2, 0.6000000000000001]), time = (scale = [0.8187307530779818, 1.2214027581601699, 1.822118800390509],))

Use prepare_query_ad for derivatives or ReactiveKernels.js_source for JavaScript. WORKFLOW_WANTS lists the fields and coverage.

Inspection ​

A model view combines the generated program with graph inspection. It is derived from the built model and its binding, so it describes the program used by the queries above.

julia
using Main.Tutorials
Tutorials.html(model_view(built; bound))

prepare_query returns a raw prepared callable. Calls made from an already compiled Julia function may require a world-age barrier; prepare_sampler supplies the managed sampler boundary. See the PPL reference for derivative, predictive and conditional-latent queries.

Integrating out a linear-Gaussian recurrence ​

A latent @scan whose steps are linear in the previous state with Normal innovations, observed through a Normal law whose location is affine in it, can be integrated out exactly. marginalize(model, :x) keeps the model source as written and lowers the recurrence and its observation into a Kalman filter. The sampler then has no coordinates for x or its innovations, and the likelihood is the exact marginal density of the observations given the remaining parameters.

julia
using ReactiveKernelsPPL, Random

model = @rkppl begin
    level ~ Normal(0, 2)
    sd ~ Exponential(1)
    length_scale ~ LogNormal(0, 1)
    noise ~ Exponential(0.5)
    @scan begin
        x[1] ~ Normal(0, 1)
        for t in 2:T
            e ~ Normal(0, 1)
            r = exp(-gap[t] / length_scale)
            x[t] = r * x[t - 1] + sqrt(1 - r * r) * e
        end
    end
    y .~ Normal.(level .+ sd .* x, noise)
end

gap = [1.0, 0.5, 2.0, 1.0, 0.7, 1.3]
y = [0.3, 0.5, -0.1, 0.0, 0.4, 0.2]
latent = build_kernel(model(; gap, T = length(y)) | (; y))
plan = marginalize(model(; gap, T = length(y)), :x) | (; y)
built = build_kernel(plan)
(; latent=coordinate_names(latent.layout), marginal=coordinate_names(built.layout))

(latent = [:level, :sd, :length_scale, :noise, Symbol("_ppl_scan_z_x.1"), Symbol("_ppl_scan_z_x.2"), Symbol("_ppl_scan_z_x.3"), Symbol("_ppl_scan_z_x.4"), Symbol("_ppl_scan_z_x.5"), Symbol("_ppl_scan_z_x.6")], marginal = [:level, :sd, :length_scale, :noise])

Each step's coefficients may read parameters, data and the loop index, so irregular gaps and resets where a new series begins are covered. The pointwise query holds each observation's one-step-ahead predictive density. Draws of the integrated-out trajectory come afterward, one per parameter draw, by forward filtering and backward sampling:

julia
u = unconstrain(built.layout, (; level=0.2, sd=0.3, length_scale=1.5, noise=0.2))
latents = prepare_marginalized_latents(built, plan)
marginalized_latent_draws(latents, u, Xoshiro(1)).x

0.7412871105569291.28087297692360850.5820921838348327-0.72195681143352240.53704419930750590.0016960561626081921

The filter's own values become values of the program when the call names them. These are each observation's one-step-ahead predictive location, variance or scale given the observations before it, and the filtered mean and variance of the state given the observations up to each step. They are queried by name and emitted by jax_source(built, plan; values = …) like any other value. The density stays as it was:

julia
named = marginalize(model(; gap, T = length(y)), :x;
    predictive = (location = :y_loc, scale = :y_sd),
    filtered = (mean = :x_mean, variance = :x_var)) | (; y)
built_named = build_kernel(named)
values_of = prepare_query(built_named, named, (:y_loc, :y_sd, :x_mean))
values_of(u)

([0.2, 0.24960601380895464, 0.2521418788547619, 0.10364883360723273, 0.0974973883418144, 0.23553330008110673], [0.36055512754639896, 0.31306575047714086, 0.35410665256470114, 0.3368332448109273, 0.32371648646524753, 0.34419101674182145], [0.2307692307692307, 0.6593632392658999, -0.6255548222617203, -0.5448593831690992, 0.28177524743347226, 0.03999219282565544])

A missing entry of y is a step that only predicts: the filter carries the state through it without an update, and the likelihood has no term for it. The draws then condition on the present entries alone, and one program serves every pattern of missing entries:

julia
y_gaps = Union{Missing,Float64}[0.3, missing, -0.1, 0.0, missing, 0.2]
with_gaps = marginalize(model(; gap, T = length(y_gaps)), :x) | (; y = y_gaps)
built_gaps = build_kernel(with_gaps)
latents_gaps = prepare_marginalized_latents(built_gaps, with_gaps)
marginalized_latent_draws(latents_gaps, u, Xoshiro(1)).x

0.70060942278341081.16194992895780950.5206661491393029-0.84090495061004790.09185114848440551-0.0853332767299268

The observed vector may also be one the model computes, as long as it does not read x. Censored rows enter the filter this way (data augmentation). Each censored row's unknown value is a latent bounded by its own range (per-element bounds), and the measured rows join those values in time order. The scan's length is then supplied, and the measured rows are conditioned: their entries' one-step-ahead predictive densities are the likelihood and :pointwise.measured, and the censored rows' densities are prior factors. Bound as inputs instead, the measured rows are not conditioned, and the whole density is a prior factor:

julia
censored = @rkppl begin
    level ~ Normal(0, 2)
    phi ~ Uniform(-1, 1)
    sigma ~ Exponential(1)
    noise ~ Exponential(0.5)
    @scan begin
        x[1] ~ Normal(0, sigma / sqrt(1 - phi^2))
        for t in 2:T
            x[t] ~ Normal(phi * x[t - 1], sigma)
        end
    end
    gap[1:K] .~ restricted.(Flat.(), 0, Inf)    # a row below its limit: limit - gap
    value = vcat(measured, limit .- gap)[order]
    value .~ Normal.(level .+ x, noise)
end
measured = [0.3, 0.5, 0.0, 0.4]
limit = [-0.2, -0.3]                            # rows 3 and 6 fell below these
order = invperm([1, 2, 4, 5, 3, 6])
augmented = marginalize(censored(; T = 6, K = 2, limit, order), :x) | (; measured)
built_censored = build_kernel(augmented)
censored_pointwise = prepare_query(built_censored, augmented, :pointwise)
v = zeros(built_censored.layout.total)
(; coordinates = coordinate_names(built_censored.layout), pointwise = censored_pointwise(v))

(coordinates = [:level, :phi, :sigma, :noise, Symbol("gap.1"), Symbol("gap.2")], pointwise = (measured = [-1.2880121234846453, -1.3280121234846454, -1.2655121234846454, -1.3055121234846454],))

Rows may also observe the state at their steps, x[step] with step bound integer data, so that a step has several rows or none (several sensors, irregular sampling). The filter then runs over the steps and their rows in order, and the scan's length is supplied:

julia
sensors = @rkppl begin
    phi ~ Uniform(-1, 1)
    sigma ~ Exponential(1)
    bias[1:S] .~ Normal.(0, 1)
    noise ~ Exponential(0.5)
    @scan begin
        x[1] ~ Normal(0, sigma / sqrt(1 - phi^2))
        for t in 2:T
            x[t] ~ Normal(phi * x[t - 1], sigma)
        end
    end
    y .~ Normal.(bias[sensor] .+ x[step], noise)
end
step = [1, 1, 2, 4, 4, 5]                       # step 3 has no row
sensor = [1, 2, 1, 1, 2, 2]
readings = [0.2, 0.4, -0.1, 0.3, 0.1, 0.0]
rows = marginalize(sensors(; T = 5, S = 2, step, sensor), :x) | (; y = readings)
built_rows = build_kernel(rows)
u = zeros(built_rows.layout.total)
(; coordinates=coordinate_names(built_rows.layout),
    x=marginalized_latent_draws(prepare_marginalized_latents(built_rows, rows), u, Xoshiro(1)).x)

(coordinates = [:phi, :sigma, :noise, Symbol("bias.1"), Symbol("bias.2")], x = [0.8725403599231294, 1.687355233576168, -0.806852326006714, 0.44018158019809017, -0.04990981619173357])

A @scan carrying several arrays, or reading one at a lag above one, has a vector state: name every array it carries, and the filter carries them as one Gaussian state. A local linear trend:

julia
trend = @rkppl begin
    s_level ~ Exponential(1)
    s_slope ~ Exponential(0.5)
    noise ~ Exponential(1)
    @scan begin
        level[1] ~ Normal(0, 2)
        slope[1] ~ Normal(0, 1)
        for t in 2:T
            level[t] ~ Normal(level[t - 1] + slope[t - 1], s_level)
            slope[t] ~ Normal(slope[t - 1], s_slope)
        end
    end
    y .~ Normal.(level, noise)
end
series = [0.1, 0.4, 0.9, 1.1, 1.8, 2.2]
smooth = marginalize(trend(; T = length(series)), :level, :slope) | (; y = series)
built_trend = build_kernel(smooth)
u = zeros(built_trend.layout.total)
draws = marginalized_latent_draws(prepare_marginalized_latents(built_trend, smooth), u, Xoshiro(1))
(; coordinates=coordinate_names(built_trend.layout), draws.level, draws.slope)

(coordinates = [😒_level, 😒_slope, :noise], level = [-0.2092792198814652, 0.9828863415651627, 0.22413184654700738, 0.001580114814045741, 0.6334945131727117, 2.49670563633992], slope = [0.8691332618661264, -0.18675344503347174, -1.0490526627337715, 0.5986658547723094, 2.4078120178529963, 1.1786220698077265])

An AR(p) seeded at x[1], …, x[p] integrates out the same way, as marginalize(model, :x). A recurrence a submodel holds is named by its path, marginalize(model, Symbol("z.x")) for x of z ~ sm(…), and its draws nest as draws.z.x.

A recurrence in a @plate cell integrates out the same way, one filter per index, when the cell observes it through y[g] .~ Normal.(offset .+ loading .* x, noise) and the bound y holds one vector per index. The draws then hold one trajectory per index:

julia
grouped = @rkppl begin
    phi ~ Uniform(-1, 1)
    sigma ~ Exponential(1)
    noise ~ Exponential(0.5)
    level[1:G] .~ Normal.(0, 2)
    @plate for g in eachindex(y)
        @scan begin
            x[1] ~ Normal(0, 1)
            for t in 2:length(y[g])
                x[t] ~ Normal(phi * x[t - 1], sigma)
            end
        end
        y[g] .~ Normal.(level[g] .+ x, noise)
    end
end
ys = [[0.3, 0.5, -0.1], [0.0, 0.4], [0.2, 0.1, 0.6, 0.3]]
cells = marginalize(grouped(; G = length(ys)), :x) | (; y = ys)
built_cells = build_kernel(cells)
u = zeros(built_cells.layout.total)
latents = prepare_marginalized_latents(built_cells, cells)
(; coordinates=coordinate_names(built_cells.layout),
    x=marginalized_latent_draws(latents, u, Xoshiro(1)).x)

(coordinates = [:phi, :sigma, :noise, Symbol("level.1"), Symbol("level.2"), Symbol("level.3")], x = [[-0.42053075113548644, 0.6258108166431111, -0.09990981619173357], [0.8236903566197061, 1.937355233576168], [-0.6373373057894631, -0.5340849033672174, 1.5373899806135372, 0.3391966148167208]])

Recurrences inside nested @plate cells, missing entries or gathered rows in a @plate cell's series, a vector state in a @plate cell or observed through missing entries, a defined vector or gathered rows, and observations that are not Normal are refused with an error naming the statement.

Adaptive partial centering ​

Select affine cells when setting up WarmupHMC. Declare their location and log-scale as ordinary named values in the model, then pass those names to adaptive_centering_problem. It is public but not exported, because BayesianRegressionModels exports a different function of that name; import it explicitly:

julia
using ReactiveKernelsPPL, WarmupHMC, LogDensityProblems, Enzyme
using ReactiveKernelsPPL: adaptive_centering_problem
using DifferentiationInterface: AutoEnzyme

model = @rkppl begin
    mu ~ Normal(0, mu_sd)
    sigma ~ Exponential(sigma_scale)
    z[1:N] .~ Normal.(0, 1)
    z_location = mu .+ offsets
    z_log_scale = log(sigma)
    total = z_location .+ exp(z_log_scale) .* z
    y .~ Normal.(total, se)
end
plan = model(; N = 4, offsets = [-0.2, 0.1, 0.3, -0.1],
    mu_sd = 2.0, sigma_scale = 1.0, se = 0.3) | (; y = [0.1, 0.2, 0.7, -0.2])
built = build_kernel(plan)
u0 = zeros(built.layout.total)
problem = prepare_sampler(built, plan, u0; backend = AutoEnzyme())
adaptive = adaptive_centering_problem(built, plan, problem, AutoEnzyme();
    cells = (z = (location = :z_location, log_scale = :z_log_scale),), u0)
@assert LogDensityProblems.logdensity(adaptive, u0) ==
    LogDensityProblems.logdensity(problem, u0)
(; dimension = LogDensityProblems.dimension(adaptive),
    logdensity = LogDensityProblems.logdensity(adaptive, u0))

(dimension = 6, logdensity = -6.6477027620982545)

Pass adaptive to WarmupHMC with nonlinear adaptation enabled. The selected latent starts in its authored non-centered coordinates; the sampler can adapt its centering and returns draws in the original model frame. A cell can set target = 1.0 for an authored centered coordinate and source for a different initial sampler frame. Zero means non-centered; one means centered.

Each location or log-scale accepts either a Real constant shared by the block or a symbol naming a scalar or latent-shaped array in the model graph. For a zero-centered block, use cells = (z = (location = 0.0, log_scale = :z_log_scale),); the zero needs no declaration in the model. Graph values and their derivatives may depend on unselected latent parameters. The adapter selects identity-transformed real coordinates, without changing their priors. For example, a real ICAR block keeps its ICAR density and any soft sum constraint.

Any latent or definition can be named. Append a missing one before binding, without editing the model's text: merge(model, quote log_s = log(s); z_location = a_mean .+ effect end). Definitions only cells read leave the sampler and jax_source unchanged.

A cell's location and log-scale must not read its own latent. They may read another selected cell's latent, as in a nested hierarchy where unit effects z_u are centred about unit_location = mu .+ tau_g .* z_g[group] and the group effects z_g about mu: cells = (z_g = (location = :mu, log_scale = :log_tau_g), z_u = (location = :unit_location, log_scale = :log_tau_u)). Such a read sees the other cell's model-frame values. The reads order the cells into levels, which WarmupHMC maps in order, so re-centering a parent level keeps the meaning of the coordinates centred on it. The adapter checks these graph dependencies before sampling and refuses own reads and cycles. Nested levels need RKPPL 0.1.185 and WarmupHMC 0.3.0 or later.

A latent random walk or AR(1) series observed only in parts has no good fixed frame: written in its innovations, the step size falls as the series grows; written in its states, it mixes badly where nothing is observed. Mark its @scan with markov_chains(model, :w) before binding. The recurrence qualifies when it is linear-Gaussian in its previous state, as for marginalize, written centred or non-centred, at top level or in a @plate cell. RKPPL lowers it in its states, and adaptive_centering_problem gives it one WarmupHMC MarkovChain (WarmupHMC 0.3.1 or later), which adapts how far to centre each time step. cells may then be omitted, or given in the same call when neither reads the other's latents. In a @plate cell the recurrence is still one chain: every index's states in plate order, restarting at each index, so no index's centring reads another's states. WarmupHMC.reparam_sources lists one (; phi, c) per marked array, with one entry per state; the markov_chains docstring gives the count.

RKPPL 0.1.175 with WarmupHMC 0.2.21 or later prepares one joint endpoint kernel, sharing common graph work across selected cells and their location/log-scale roles. It runs once per vector and level on a map or inverse, and shares results across scoring candidates. Within a level, cells are ordered by packed coordinate, regardless of keyword order. Identity maps skip endpoint evaluation. Ordinary AD differentiates the joint graph; arrays remain read-only, without concatenation into a new endpoint buffer. For Enzyme differentiation through cached matrix endpoints, use the const_array_reshape repair (dogfood 9c4df614 or later); the acceptance suite checks ordinary reverse differentiation and unchanged cached inputs.

The Eight-schools example checks the complete density decomposition and its coordinate transformation.