Backends and model inspection
Lower one declaration to a Julia density, a Stan program or a Python/JAX module. Inspect the intermediate representation and effective priors before choosing a fitting method.
The lowering chain
An @brm builder binds data into a BRMI, a typed collection of declarations, assignments, prior selectors and data. It has not fitted the model. Each backend consumes these same operations and records the fitted preprocessing needed to evaluate new rows consistently.
| Entry point | Result | Uses |
|---|---|---|
SBBRMI(model) | StanBlocks representation and emitted Stan | BridgeStan density and gradients; Stan generated quantities |
RKBRMI(model) | ReactiveKernelsPPL program | Julia density and gradients; MCMC, variational inference, filters and JAX export |
The backends share formula interpretation; their supported terms, custom functions and prediction surfaces differ. See the terms reference for individual contracts. Start with RK for a Julia workflow and use Stan when a needed term or observation mechanism is supported there.
One declaration, two backends and a JAX export
panes: brm|stanblocks|rkppl|stan|jax:3model = (@brm begin
mu ~ 1 + x + (1 | subject)
y ~ Normal(mu, sigma)
effect(mu, Intercept) ~ Normal(0, 1)
effect(mu, x) ~ Normal(0, 0.5)
sd(mu, subject) ~ Exponential(0.5)
sigma ~ Exponential(0.3)
end)((; x=[-1., 0., 1., -1., 0., 1.],
subject=["a", "a", "a", "b", "b", "b"], y=[-0.5, 0.2, 0.8, -0.2, 0.4, 1.1]))SBBRMI with data keys = [:n_subject, :n_terms_mu__subject_subject, :subject_idx, :x, :y]
configured submodels:
ranef_correlated_draws_single_margin_1 = Base.merge(BayesianRegressionModels._sb_single_margin_ranef(BayesianRegressionModels.ranef_correlated_draws), quote
tau ~ (StanBlocks.builtin.restricted)(exponential, 1.0 ./ 0.5; n = n_terms, lower = 0.0)
end)
emitted @slic body:
begin
b_mu__subject_subject ~ ranef_correlated_draws_single_margin_1(; group_idx = subject_idx, n_groups = n_subject, n_terms = n_terms_mu__subject_subject)
X_mu = hcat(rep_vector(1.0, num_elements(x)), x)
pop_mu ~ _popefs_normal(; X = X_mu, beta_loc = [0, 0], beta_scale = [1, 0.5])
r_mu_mu__subject_subject = b_mu__subject_subject[subject_idx, 1]
mu = pop_mu + r_mu_mu__subject_subject
sigma ~ exponential(1.0 ./ 0.3)
y ~ normal(mu, sigma)
end"""
Group-level (varying) effects of grouping `g`.
Non-centered, from the scale `tau[1]` (drawn from its prior) and standardized effects
`z[1:length(levels(g)), 1:1] ~ Normal(0, 1)`. Returns the
level-by-margin matrix `z .* tau[1]`, one row per level of `g` in order.
"""
brm_group_effects(g) = begin
tau[1:1] .~ Exponential.(0.5)
z[1:length(levels(g)), 1:1] .~ Normal.(0, 1)
return z .* tau[1]
end
"""
Population-level effects: one coefficient per column of the design matrix `X`.
Draws `beta_pop[1:ncoef] ~ Normal(loc, scale)` and returns the linear predictor
`X * beta_pop`. `ncoef` is the number of columns of `X`. Each prior argument (`loc`, `scale`) is one value for all coefficients or a vector with one per coefficient.
"""
brm_population_effects(X, ncoef, loc, scale) = begin
beta_pop[1:ncoef] .~ Normal.(loc, scale)
return X * beta_pop
end
begin
subject_fit_levels = brm_fit_levels(subject_fit)
b_mu__subject_subject ~ brm_group_effects(subject_fit_levels)
subject_level = brm_level_indices(subject, subject_fit_levels)
ranef_mu_mu__subject_subject = b_mu__subject_subject[subject_level, 1]
X_mu = hcat(ones(length(subject)), x)
pop_mu ~ brm_population_effects(X_mu, 2, 0.0, [1.0, 0.5])
mu = pop_mu .+ ranef_mu_mu__subject_subject
sigma ~ Exponential(0.3)
y .~ Normal.(mu, sigma)
endfunctions {
matrix hcat(
vector x,
vector y
) {
int n = dims(x)[1];
if (dims(y)[1] != n) reject("hcat: dim mismatch — `y` dim 1 (= ", dims(y)[1], ") does not match `n` (= ", n, "), inferred from `x` dim 1. `n` sizes: `x` dim 1 (= ", dims(x)[1], "), `y` dim 1 (= ", dims(y)[1], ").");
return append_col(x, y);
}
vector normal_lpdfs(
vector obs,
vector loc,
real scale
) {
return jbroadcasted_normal_lpdfs(obs, loc, scale);
}
vector jbroadcasted_normal_lpdfs(
vector x1,
vector x2,
real x3
) {
int n = dims(x1)[1];
vector[n] rv;
for(i in 1:n) {
rv[i] = normal_lpdfs(broadcasted_getindex(x1, i), broadcasted_getindex(x2, i), x3);
}
return rv;
}
real normal_lpdfs(
real args1,
real args2,
real args3
) {
return normal_lpdf(args1 | args2, args3);
}
real broadcasted_getindex(vector x, int i) {
return x[i];
}
vector normal_vector_rng(
int anontok__1,
vector a,
real b
) {
int n = anontok__1;
if((n == 0)) {
vector[n] rv;
return rv;
} else {
return to_vector(normal_rng(a, b));
}
}
}
data {
int n_terms_mu__subject_subject;
int n_subject;
int x_n;
vector[x_n] x;
int subject_idx_n;
array[subject_idx_n] int subject_idx;
int y_n;
vector[y_n] y;
}
transformed data {
matrix[x_n, 2] X_mu = hcat(rep_vector(1.0, num_elements(x)), x);
int pop_mu_n_covariates = 2;
}
parameters {
vector<lower=0.0>[n_terms_mu__subject_subject] b_mu__subject_subject_tau;
vector[(n_terms_mu__subject_subject * n_subject)] b_mu__subject_subject_z_flat;
vector[pop_mu_n_covariates] pop_mu_beta_pop;
real<lower=0.0> sigma;
}
transformed parameters {
matrix[n_terms_mu__subject_subject, n_subject] b_mu__subject_subject_z = to_matrix(b_mu__subject_subject_z_flat, n_terms_mu__subject_subject, n_subject);
matrix[n_subject, n_terms_mu__subject_subject] b_mu__subject_subject = ((diag_matrix(b_mu__subject_subject_tau) * b_mu__subject_subject_z)');
vector[x_n] pop_mu = (X_mu * pop_mu_beta_pop);
vector[subject_idx_n] r_mu_mu__subject_subject = b_mu__subject_subject[subject_idx, 1];
vector[x_n] mu = (pop_mu + r_mu_mu__subject_subject);
}
model {
b_mu__subject_subject_tau ~ exponential((1.0 ./ 0.5));
b_mu__subject_subject_z_flat ~ std_normal();
pop_mu_beta_pop ~ normal([0, 0]', [1, 0.5]');
sigma ~ exponential((1.0 ./ 0.3));
y ~ normal(mu, sigma);
}
generated quantities {
vector[y_n] y_likelihood = normal_lpdfs(y, mu, sigma);
vector[y_n] y_gen = normal_vector_rng(y_n, mu, sigma);
}using ReactiveKernels, ReactiveKernelsPPL
rk = RKBRMI(model)
source = jax_source(rk.model, rk_bound_plan(rk))
write("model.py", source)
inputs = rk_bound_data(rk, source) # exactly the inputs prepare_data readsimport jax
import model as m
prepared = m.prepare_data(**inputs)
lp = m.log_density(u, **prepared) # u: unconstrained, length m.dimension(prepared)
lp = jax.jit(m.log_density)(u, **prepared) # one compiled function for every dataset of these shapes"""Generated by ReactiveKernelsPPL.jax_source from a built @rkppl program; do not edit.
Data: subject, subject_fit, x, y.
Model documentation:
- `b_mu__subject_subject`: Group-level (varying) effects of grouping `g`.
Non-centered, from the scale `tau[1]` (drawn from its prior) and standardized effects
`z[1:length(levels(g)), 1:1] ~ Normal(0, 1)`. Returns the
level-by-margin matrix `z .* tau[1]`, one row per level of `g` in order.
- `pop_mu`: Population-level effects: one coefficient per column of the design matrix `X`.
Draws `beta_pop[1:ncoef] ~ Normal(loc, scale)` and returns the linear predictor
`X * beta_pop`. `ncoef` is the number of columns of `X`. Each prior argument (`loc`, `scale`) is one value for all coefficients or a vector with one per coefficient.
"""
import numpy as np
import scipy.special as ssp
from typing import Any
import jax
import jax.numpy as jnp
import jax.scipy.linalg
import jax.scipy.special as jsp
from jax.typing import ArrayLike
jax.config.update("jax_enable_x64", True)
DATA = {"subject": {"dtype": "object", "ndim": 1, "ragged": False}, "subject_fit": {"dtype": "object", "ndim": 1, "ragged": False}, "x": {"dtype": "float64", "ndim": 1, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}}
INPUTS = ("unconstrained", "ppl_last_b_mu_subject_subject_z", "ppl_axis1_b_mu_subject_subject_z", "ppl_first_pop_mu_beta_pop", "ppl_last_pop_mu_beta_pop", "X_mu", "subject_level", "y")
PREPARED = {"ppl_last_b_mu_subject_subject_z": {"dtype": "int64", "ndim": 0, "ragged": False}, "ppl_axis1_b_mu_subject_subject_z": {"dtype": "int64", "ndim": 0, "ragged": False}, "ppl_first_pop_mu_beta_pop": {"dtype": "int64", "ndim": 0, "ragged": False}, "ppl_last_pop_mu_beta_pop": {"dtype": "int64", "ndim": 0, "ragged": False}, "X_mu": {"dtype": "float64", "ndim": 2, "ragged": False}, "subject_level": {"dtype": "int64", "ndim": 1, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}}
UNTRANSLATED = {}
def _rk_order_key_np(x):
# Julia's isless order of an array as sortable keys: a float is an integer
# key, -0.0 before 0.0 and every NaN last, equal for values isequal treats
# as equal. Integer and string arrays are their own keys.
x = np.asarray(x)
if x.dtype.kind != "f":
return x
bits = np.where(np.isnan(x), np.nan, x).astype(np.float64).view(np.int64)
return np.where(bits < 0, bits ^ np.int64(0x7FFFFFFFFFFFFFFF), bits)
def _rk_unique_np(x):
# Julia's unique of a vector: the first value of each isequal class, in
# order.
x = np.asarray(x)
_, first = np.unique(_rk_order_key_np(x), return_index=True)
return x[np.sort(first)]
def _rk_sort_np(x):
# Julia's sort of a vector: ascending in isless order, equal values in
# their order.
x = np.asarray(x)
return x[np.argsort(_rk_order_key_np(x), kind="stable")]
def _brm_sorted_labels_np(source):
labels = _rk_unique_np(source)
sorted_ = _rk_sort_np(labels)
return sorted_
def _brm_fit_levels_np(source):
value = _brm_sorted_labels_np(source)
levels = value
return levels
def _rk_dict_key(x):
if isinstance(x, tuple):
return (1, tuple(map(_rk_dict_key, x)))
if isinstance(x, np.ndarray):
return (2, x.shape, tuple(map(_rk_dict_key, x.ravel(order="F"))))
if isinstance(x, (complex, np.complexfloating)):
if x.imag == 0 and not np.signbit(x.imag):
return _rk_dict_key(x.real)
return (3, _rk_dict_key(x.real), _rk_dict_key(x.imag))
if isinstance(x, (float, np.floating)):
if np.isnan(x):
return (4,)
if x == 0 and np.signbit(x):
return (5,)
return (0, x)
class _RKDict:
def __init__(self, pairs=()):
self.data = {}
for key, value in pairs:
self[key] = value
def __len__(self):
return len(self.data)
def __contains__(self, key):
return _rk_dict_key(key) in self.data
def __getitem__(self, key):
return self.data[_rk_dict_key(key)][1]
def __setitem__(self, key, value):
self.data[_rk_dict_key(key)] = (key, value)
def get(self, key, default):
item = self.data.get(_rk_dict_key(key))
return default if item is None else item[1]
def setdefault(self, key, default):
return self.data.setdefault(_rk_dict_key(key), (key, default))[1]
def pop(self, key, default):
item = self.data.pop(_rk_dict_key(key), None)
return default if item is None else item[1]
def items(self):
return self.data.values()
def keys(self):
return (item[0] for item in self.items())
def values(self):
return (item[1] for item in self.items())
def copy(self):
return _RKDict(self.items())
def _brm_level_indices_np(labels, source):
value = _brm_fit_levels_np(source)
levels = value
lookup = _RKDict()
for k in range(1, len(levels) + 1):
lookup[levels[k - 1]] = k
indices = np.zeros((len(labels),), dtype=np.int64)
for r in range(1, len(labels) + 1):
position = lookup.get(labels[r - 1], 0)
if position == 0:
raise ValueError("".join([str("RK backend: group label `"), str(labels[r - 1]), str("` is not one of the "), str(len(levels)), str(" fitted levels. A replay keeps the fitted levels of every grouping it does not resample; name the grouping in `resample_groups` to take the new data's own levels.")]))
indices[r - 1] = position
return indices
def _rk_levels_np(x):
arr = np.asarray(x)
values = sorted(set(v for v in arr.tolist() if v is not None))
return np.array(values, dtype=object if arr.dtype == object else arr.dtype)
class StaticInt(int):
"""An integer of the prepared data that sets a shape.
It is an `int` everywhere, and `jax.jit` treats it as static, so the
functions jit with the prepared data as arguments; a new value traces
them again.
"""
def __repr__(self):
return "StaticInt(%d)" % int(self)
jax.tree_util.register_pytree_node(StaticInt, lambda s: ((), int(s)), lambda v, _: StaticInt(v))
def brm_population_effects(X: ArrayLike, beta_pop: ArrayLike, *, outputs: tuple[str, ...]) -> dict:
"""Population-level effects: one coefficient per column of the design matrix `X`.
Draws `beta_pop[1:ncoef] ~ Normal(loc, scale)` and returns the linear predictor
`X * beta_pop`. `ncoef` is the number of columns of `X`. Each prior argument (`loc`, `scale`) is one value for all coefficients or a vector with one per coefficient.
"""
results = {}
if any(name in outputs for name in ("value",)):
value = X @ beta_pop
if any(name in outputs for name in ("ppl_prior_beta_pop", "ppl_pw_prior_beta_pop")):
ppl_parg_beta_pop_2 = jnp.asarray([1.0, 0.5], dtype=jnp.float64)
def ppl_pw_prior_beta_pop_cell(beta_pop_2, scale):
log_scale = jnp.log(scale)
standardized = (beta_pop_2 - 0.0) / jnp.where(jnp.logical_and(scale == 0, beta_pop_2 == 0.0), 1.0, scale)
standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * standardized ** 2
logpdf = standard_logpdf - jnp.where(jnp.logical_and(scale == 0, beta_pop_2 != 0.0), 0.0, log_scale)
return logpdf
ppl_pw_prior_beta_pop = (jnp.zeros(beta_pop.shape[:1], dtype=jnp.float64) if 0 in beta_pop.shape[:1] and ppl_parg_beta_pop_2.shape[:1] == beta_pop.shape[:1] else jax.vmap(ppl_pw_prior_beta_pop_cell, in_axes=(0, 0))(beta_pop, ppl_parg_beta_pop_2))
if any(name in outputs for name in ("ppl_prior_beta_pop",)):
ppl_prior_beta_pop = jnp.sum(ppl_pw_prior_beta_pop)
if "ppl_prior_beta_pop" in outputs:
results["ppl_prior_beta_pop"] = ppl_prior_beta_pop
if "ppl_pw_prior_beta_pop" in outputs:
results["ppl_pw_prior_beta_pop"] = ppl_pw_prior_beta_pop
if "value" in outputs:
results["value"] = value
return results
def brm_group_effects_density(
ppl_last_z: ArrayLike,
tau: ArrayLike,
unconstrained: ArrayLike,
*,
outputs: tuple[str, ...],
) -> dict:
"""Group-level (varying) effects of grouping `g`.
Non-centered, from the scale `tau[1]` (drawn from its prior) and standardized effects
`z[1:length(levels(g)), 1:1] ~ Normal(0, 1)`. Returns the
level-by-margin matrix `z .* tau[1]`, one row per level of `g` in order.
"""
results = {}
if any(name in outputs for name in ("ppl_arrflat_z", "ppl_prior_z", "ppl_pw_prior_z")):
ppl_arrflat_z = unconstrained[2:ppl_last_z]
if any(name in outputs for name in ("ppl_prior_tau", "ppl_pw_prior_tau")):
def ppl_pw_prior_tau_cell(tau_2):
log_scale = np.log(0.5)
logpdf = jax.lax.cond(tau_2 < 0, lambda: -jnp.inf, lambda: -log_scale - tau_2 / 0.5)
return logpdf
ppl_pw_prior_tau = (jnp.zeros(tau.shape[:1], dtype=jnp.float64) if 0 in tau.shape[:1] else jax.vmap(ppl_pw_prior_tau_cell, in_axes=(0,))(tau))
if any(name in outputs for name in ("ppl_prior_tau",)):
ppl_prior_tau = jnp.sum(ppl_pw_prior_tau)
if any(name in outputs for name in ("ppl_prior_z", "ppl_pw_prior_z")):
def ppl_pw_prior_z_cell(z):
log_scale = np.log(1.0)
standardized = (z - 0.0) / jnp.where((z == 0.0 if 1.0 == 0 else False), 1.0, 1.0)
standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * standardized ** 2
logpdf = standard_logpdf - jnp.where((z != 0.0 if 1.0 == 0 else False), 0.0, log_scale)
return logpdf
ppl_pw_prior_z = (jnp.zeros(ppl_arrflat_z.shape[:1], dtype=jnp.float64) if 0 in ppl_arrflat_z.shape[:1] else jax.vmap(ppl_pw_prior_z_cell, in_axes=(0,))(ppl_arrflat_z))
if any(name in outputs for name in ("ppl_prior_z",)):
ppl_prior_z = jnp.sum(ppl_pw_prior_z)
if "ppl_arrflat_z" in outputs:
results["ppl_arrflat_z"] = ppl_arrflat_z
if "ppl_prior_tau" in outputs:
results["ppl_prior_tau"] = ppl_prior_tau
if "ppl_prior_z" in outputs:
results["ppl_prior_z"] = ppl_prior_z
if "ppl_pw_prior_tau" in outputs:
results["ppl_pw_prior_tau"] = ppl_pw_prior_tau
if "ppl_pw_prior_z" in outputs:
results["ppl_pw_prior_z"] = ppl_pw_prior_z
return results
def brm_group_effects(tau: ArrayLike, z: ArrayLike, *, outputs: tuple[str, ...]) -> dict:
"""Group-level (varying) effects of grouping `g`.
Non-centered, from the scale `tau[1]` (drawn from its prior) and standardized effects
`z[1:length(levels(g)), 1:1] ~ Normal(0, 1)`. Returns the
level-by-margin matrix `z .* tau[1]`, one row per level of `g` in order.
"""
results = {}
if any(name in outputs for name in ("value",)):
value = z * tau[0]
if "value" in outputs:
results["value"] = value
return results
def prepare_data(subject: Any, subject_fit: Any, x: ArrayLike, y: ArrayLike) -> dict:
"""The functions' data inputs, computed from the raw data once per dataset.
Pass the data by the names the model reads them; a list of arrays is a ragged
column. Call the other functions with the result: `f(u, **prepared)`.
"""
subject = np.asarray(subject, dtype=object)
subject_fit = np.asarray(subject_fit, dtype=object)
x = np.asarray(x, dtype=np.float64)
y = np.asarray(y, dtype=np.float64)
X_mu = np.asarray(np.concatenate([np.ones((len(subject),), dtype=np.float64)[:, None], x[:, None]], axis=1), dtype=np.float64)
value = _brm_fit_levels_np(subject_fit)
subject_fit_levels = value
value_2 = _brm_level_indices_np(subject, subject_fit_levels)
subject_level = np.asarray(value_2, dtype=np.int64)
ppl_axis1_b_mu_subject_subject_z = len(_rk_levels_np(subject_fit_levels))
ppl_last_b_mu_subject_subject_z = 2 + ppl_axis1_b_mu_subject_subject_z
ppl_first_pop_mu_beta_pop = ppl_last_b_mu_subject_subject_z + 1
ppl_last_pop_mu_beta_pop = ppl_first_pop_mu_beta_pop + 1
return {"ppl_last_b_mu_subject_subject_z": StaticInt(ppl_last_b_mu_subject_subject_z), "ppl_axis1_b_mu_subject_subject_z": StaticInt(ppl_axis1_b_mu_subject_subject_z), "ppl_first_pop_mu_beta_pop": StaticInt(ppl_first_pop_mu_beta_pop), "ppl_last_pop_mu_beta_pop": StaticInt(ppl_last_pop_mu_beta_pop), "X_mu": np.asarray(X_mu, dtype=np.float64), "subject_level": np.asarray(subject_level, dtype=np.int64), "y": np.asarray(y, dtype=np.float64)}
def model(_entry: str, unconstrained: ArrayLike, **prepared: ArrayLike) -> Any:
"""Shared model computation. The generated entry wrappers select a static output."""
ppl_last_b_mu_subject_subject_z = prepared["ppl_last_b_mu_subject_subject_z"]
ppl_axis1_b_mu_subject_subject_z = prepared["ppl_axis1_b_mu_subject_subject_z"]
ppl_first_pop_mu_beta_pop = prepared["ppl_first_pop_mu_beta_pop"]
ppl_last_pop_mu_beta_pop = prepared["ppl_last_pop_mu_beta_pop"]
X_mu = prepared["X_mu"]
subject_level = prepared["subject_level"]
y = prepared["y"]
unconstrained = jnp.asarray(unconstrained)
X_mu = jnp.asarray(X_mu)
subject_level = jnp.asarray(subject_level)
y = jnp.asarray(y)
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
u_argument = unconstrained[0]
constrain_2 = jnp.exp(u_argument)
plate_argument = unconstrained[1:2]
def b_mu_subject_subject_tau_cell(ppl_cell_b_mu_subject_subject_tau):
constrain_3 = jnp.exp(ppl_cell_b_mu_subject_subject_tau)
return constrain_3
b_mu_subject_subject_tau = (jnp.zeros(plate_argument.shape[:1], dtype=jnp.float64) if 0 in plate_argument.shape[:1] else jax.vmap(b_mu_subject_subject_tau_cell, in_axes=(0,))(plate_argument))
if _entry in ("log_density", "log_jacobian"):
plate_argument_2 = unconstrained[1:2]
def ppl_ljcells_b_mu_subject_subject_tau_cell(ppl_cell_b_mu_subject_subject_tau):
return ppl_cell_b_mu_subject_subject_tau
ppl_ljcells_b_mu_subject_subject_tau = (jnp.zeros(plate_argument_2.shape[:1], dtype=jnp.float64) if 0 in plate_argument_2.shape[:1] else jax.vmap(ppl_ljcells_b_mu_subject_subject_tau_cell, in_axes=(0,))(plate_argument_2))
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
pop_mu_beta_pop = unconstrained[ppl_first_pop_mu_beta_pop - 1:ppl_last_pop_mu_beta_pop]
if _entry in ("log_density", "log_prior", "log_likelihood"):
pop_mu = brm_population_effects(
X=(X_mu if _entry in ("log_density", "log_likelihood") else None),
beta_pop=(pop_mu_beta_pop if _entry in ("log_density", "log_prior", "log_likelihood") else None),
outputs=tuple(
name for name, needed in (
("ppl_prior_beta_pop", ("log_density", "log_prior")),
("ppl_pw_prior_beta_pop", ("log_density", "log_prior")),
("value", ("log_density", "log_likelihood")),
)
if _entry in needed
),
)
if _entry in ("log_density", "log_prior"):
ppl_prior_sigma_log_scale = np.log(0.3)
logpdf = jax.lax.cond(constrain_2 < 0, lambda: -jnp.inf, lambda: -ppl_prior_sigma_log_scale - constrain_2 / 0.3)
if _entry in ("log_density", "log_jacobian"):
u_argument_2 = unconstrained[0]
plate_fold = jnp.sum(ppl_ljcells_b_mu_subject_subject_tau)
log_jacobian_2 = u_argument_2 + plate_fold
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
b_mu_subject_subject = brm_group_effects_density(
ppl_last_z=(ppl_last_b_mu_subject_subject_z if _entry in ("log_density", "log_prior", "log_likelihood", "constrain") else None),
tau=(b_mu_subject_subject_tau if _entry in ("log_density", "log_prior") else None),
unconstrained=(unconstrained if _entry in ("log_density", "log_prior", "log_likelihood", "constrain") else None),
outputs=tuple(
name for name, needed in (
("ppl_arrflat_z", ("log_density", "log_prior", "log_likelihood", "constrain")),
("ppl_prior_tau", ("log_density", "log_prior")),
("ppl_prior_z", ("log_density", "log_prior")),
("ppl_pw_prior_tau", ("log_density", "log_prior")),
("ppl_pw_prior_z", ("log_density", "log_prior")),
)
if _entry in needed
),
)
if _entry in ("log_density", "log_likelihood", "constrain"):
b_mu_subject_subject_z = jnp.reshape(b_mu_subject_subject["ppl_arrflat_z"], (ppl_axis1_b_mu_subject_subject_z, 1), order="F")
if _entry in ("log_density", "log_prior"):
prior = logpdf + b_mu_subject_subject["ppl_prior_tau"] + b_mu_subject_subject["ppl_prior_z"] + pop_mu["ppl_prior_beta_pop"]
if _entry in ("log_density", "log_likelihood"):
b_mu_subject_subject_2 = brm_group_effects(
tau=(b_mu_subject_subject_tau if _entry in ("log_density", "log_likelihood") else None),
z=(b_mu_subject_subject_z if _entry in ("log_density", "log_likelihood") else None),
outputs=tuple(
name for name, needed in (
("value", ("log_density", "log_likelihood")),
)
if _entry in needed
),
)
ppl_column_b_mu_subject_subject_1 = b_mu_subject_subject_2["value"][:, 0]
plate_argument_3 = ppl_column_b_mu_subject_subject_1[subject_level - 1]
def ppl_offset_mu_cell(pop_mu_2, value):
plate_value = pop_mu_2 + value
return plate_value
ppl_offset_mu = (jnp.zeros(pop_mu["value"].shape[:1], dtype=jnp.float64) if 0 in pop_mu["value"].shape[:1] and plate_argument_3.shape[:1] == pop_mu["value"].shape[:1] else jax.vmap(ppl_offset_mu_cell, in_axes=(0, 0))(pop_mu["value"], plate_argument_3))
def ppl_pw_y_resp_cell(y_2, mu, sigma):
def then_arm():
log_scale = jnp.log(sigma)
standardized = (y_2 - mu) / jnp.where(jnp.logical_and(sigma == 0, y_2 == mu), 1.0, sigma)
standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * standardized ** 2
return standard_logpdf - jnp.where(jnp.logical_and(sigma == 0, y_2 != mu), 0.0, log_scale)
ppl_density = jax.lax.cond(sigma > 0, then_arm, lambda: -jnp.inf)
return ppl_density
ppl_pw_y_resp = (jnp.zeros(y.shape[:1], dtype=jnp.float64) if 0 in y.shape[:1] and ppl_offset_mu.shape[:1] == y.shape[:1] else jax.vmap(ppl_pw_y_resp_cell, in_axes=(0, 0, None))(y, ppl_offset_mu, constrain_2))
ppl_lik_y_resp = jnp.sum(ppl_pw_y_resp)
if _entry in ("log_density",):
posterior = prior + ppl_lik_y_resp + log_jacobian_2
if not (unconstrained.size == ppl_last_pop_mu_beta_pop):
raise ValueError("[layout] packed length ≠ layout total: a packed point holds the coordinates of the binding whose layout packed it")
if _entry == "log_density":
return jnp.asarray(posterior, dtype=jnp.float64)
if _entry == "log_prior":
return jnp.asarray(prior, dtype=jnp.float64)
if _entry == "log_likelihood":
return jnp.asarray(ppl_lik_y_resp, dtype=jnp.float64)
if _entry == "log_jacobian":
return jnp.asarray(log_jacobian_2, dtype=jnp.float64)
if _entry == "constrain":
return {"sigma": jnp.asarray(constrain_2, dtype=jnp.float64), "b_mu__subject_subject": {"tau": jnp.asarray(b_mu_subject_subject_tau), "z": jnp.asarray(b_mu_subject_subject_z)}, "pop_mu": {"beta_pop": jnp.asarray(pop_mu_beta_pop)}}
def log_density(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log density a sampler targets at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`.
The sum of `log_prior`, `log_likelihood` and `log_jacobian`.
"""
return model("log_density", unconstrained, **prepared)
def log_prior(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log prior density of the constrained parameters at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`."""
return model("log_prior", unconstrained, **prepared)
def log_likelihood(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log likelihood of the observations at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`."""
return model("log_likelihood", unconstrained, **prepared)
def log_jacobian(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log Jacobian of the constraining transforms at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`."""
return model("log_jacobian", unconstrained, **prepared)
def constrain(unconstrained: ArrayLike, **prepared: ArrayLike) -> dict:
"""The constrained value of each parameter, and of each requested value, at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`. Returns a dict, a submodel's values nested under its name:
- `sigma`
- `b_mu__subject_subject.tau`
- `b_mu__subject_subject.z`
- `pop_mu.beta_pop`
"""
return model("constrain", unconstrained, **prepared)
def dimension(prepared: dict) -> int:
"""The length of `unconstrained` for the data `prepared` (what `prepare_data` returned)."""
return int(prepared["ppl_last_pop_mu_beta_pop"])
def parameters(prepared: dict) -> dict:
"""Each parameter's 0-based `start`/`stop` in `unconstrained`, its transform and dimensions,
for the data `prepared` (what `prepare_data` returned)."""
return {"sigma": {"start": 0, "stop": 1, "transform": "exp", "dims": ()}, "b_mu__subject_subject.tau": {"start": 1, "stop": 2, "transform": "exp", "dims": (1,)}, "b_mu__subject_subject.z": {"start": 2, "stop": int(prepared["ppl_last_b_mu_subject_subject_z"]), "transform": "identity", "dims": (int(prepared["ppl_axis1_b_mu_subject_subject_z"]), 1)}, "pop_mu.beta_pop": {"start": int(prepared["ppl_first_pop_mu_beta_pop"]) - 1, "stop": int(prepared["ppl_last_pop_mu_beta_pop"]), "transform": "identity", "dims": (2,)}}Compare opens with the BRM declaration, StanBlocks model and RKPPL model. Stan source and the JAX module are available from the same tabs on every page. The generated panes come from the bound model during the documentation build; an unsupported backend shows its diagnostic in its tab.
using BayesianRegressionModels, ReactiveKernels, ReactiveKernelsPPL
model = Main.BRMDocsComparisons.example_module(:BackendGuide).model
sb = SBBRMI(model; total_groups=())
rk = RKBRMI(model)
(columns=data_columns(model), priors=priors_of(model),
stan_characters=length(stan_code(sb)))(columns = [:x, :subject], priors = effect(mu, Intercept) ~ Normal(0, 1) effect(mu, x) ~ Normal(0, 0.5) sd(mu, subject) ~ Exponential(0.5), stan_characters = 2604)
rk_logdensity_problem provides the LogDensityProblems interface. Choose an AD backend when constructing it; the sampler then consumes that interface. stan_instantiate compiles the Stan density through BridgeStan. Neither lowering call alone runs MCMC. The adaptive-centering guide explains coordinate choices.
Replay and outputs
Keep the prepared model with its fit. reprocess binds new rows while retaining fitted factor levels, centering and scaling constants, group structure and basis information. Rebuilding from an unbound formula can change those constants and therefore change the meaning of a posterior draw.
Use declared output paths when reading predictions or latent quantities. brm_outputs and brm_output expose a Stan descriptor's output inventory. RK's rk_draw_values and rk_draw_tree evaluate requested quantities from model-coordinate draws. A latent field, a linear predictor and a predictive response are different outputs; adding observation noise belongs to prediction.
Descriptions and inspection
brm_descriptor supplies a Stan-backed description of the prepared model. brm_description converts that inventory into equations, component prose and effective priors. Check complete and diagnostics before treating the result as a complete scientific description.
using BayesianRegressionModels
model = Main.BRMDocsComparisons.example_module(:BackendGuide).model
description = brm_description(brm_descriptor(SBBRMI(model; total_groups=())))
@assert description.complete
(complete=description.complete, components=length(description.components),
priors=length(description.priors), diagnostics=description.diagnostics)(complete = true, components = 9, priors = 5, diagnostics = ())
Pass labels for scientific meanings, symbols and units; names alone do not establish them. description_texts(:de) selects German throughout the generated prose. Presentation metadata does not change model identity, data or inference caches. Custom description hooks and inventory fields are documented in the API; the description protocol retains the detailed extension and rendering contracts.
With HTMXObjects loaded, brm_model_view displays source, roles, ranks and documentation as one semantic tree. An unbound builder shows source and inputs; a bound model supplies data shapes; an explicitly prepared backend can add parameter dimensions. Inspection never fits a model or evaluates a custom helper to guess its shape. Unknown dimensions remain unknown. Component source and declaration docstrings are retained under their logical call paths. The view supports HTML, Markdown and text; HTMXObjects can also export it to a PDF.
Python/JAX export
Export the RK program together with its bound plan. The generated module owns its data preparation and unconstrained-coordinate layout. Keep the bound inputs with it; the Python source alone does not contain the data.
using BayesianRegressionModels, ReactiveKernels, ReactiveKernelsPPL
model = Main.BRMDocsComparisons.example_module(:BackendGuide).model
rk = RKBRMI(model)
source = jax_source(rk.model, rk_bound_plan(rk))
inputs = rk_bound_data(rk, source)
path = joinpath(mktempdir(), "model.py")
write(path, source)
@assert occursin("def log_density", read(path, String))
(source_bytes=filesize(path), input_names=sort!(collect(keys(inputs)); by=string))(source_bytes = 22498, input_names = [:subject, :subject_fit, :x, :y])
The accessor returns exactly the module's DATA inputs, including scalar constants by their authored names. In Python, call prepare_data(**inputs), then log_density with an unconstrained position. JAX can differentiate and compile that density. A Julia callable needs a supported translation; inspect the generated UNTRANSLATED report before using an export. Compare values and gradients at common positions before comparing fits.
The JAX example performs that parity check and fits the exported model with NumPyro, with reproduction instructions for both runtimes.