Adaptive centering
Adapt the coordinates of hierarchical Gaussian effects during warmup while preserving the model's posterior. Different groups, margins and HSGP frequencies can benefit from different amounts of centering.
Coordinates and the posterior
A noncentered scalar effect is b = tau*z, with z ~ Normal(0,1). A centered effect samples b ~ Normal(0,tau) directly. Partial centering uses u = tau^c*z, so b = tau^(1-c)*u. The endpoints c=0 and c=1 are NCP and CP. A coordinate change includes its Jacobian; it does not change the prior or add information.
using Distributions
tau, z = 0.3, 1.2
controls = [0., 0.5, 1.]
logdensities = [logpdf(Normal(0, tau^c), tau^c*z) + c*log(tau) for c in controls]
@assert all(v -> isapprox(v, logpdf(Normal(), z)), logdensities)
collect(zip(controls, logdensities))(0.0, -1.6389385332046729)(0.5, -1.6389385332046729)(1.0, -1.6389385332046729)
Weakly informed groups often suit NCP, while dense measurements can favor CP. Correlation, uncertain scales and unequal group sizes make a single choice less useful. For correlated blocks the partial coordinates use conditional means and scales in a defined ordering, not independent rescaling of each marginal.
An ordinary hierarchy
Eight schools has eight estimated effects, one population location and one between-school scale. The known measurement SDs differ across schools.
Eight schools in conventional coordinates
panes: brm|stanblocks|rkppl|stan|jax:3model = (@brm begin
theta ~ 1 + (1 | schools | school)
y ~ Normal(theta, sigma)
effect(theta, Intercept) ~ Normal(0, 5)
sd(:, schools) ~ Cauchy(0, 5)
end)((; school=collect(1:8), y=[28., 8., -3., 7., -1., 1., 18., 12.],
sigma=[15., 10., 16., 11., 9., 11., 10., 18.]))SBBRMI with data keys = [:n_school, :n_terms_schools_school, :school_idx, :sigma, :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)(cauchy, 0, 5; n = n_terms, lower = 0.0)
end)
emitted @slic body:
begin
b_schools_school ~ ranef_correlated_draws_single_margin_1(; group_idx = school_idx, n_groups = n_school, n_terms = n_terms_schools_school)
X_theta = hcat(rep_vector(1.0, num_elements(school_idx)))
pop_theta ~ _popefs_normal(; X = X_theta, beta_loc = [0], beta_scale = [5])
r_theta_schools_school = b_schools_school[school_idx, 1]
theta = pop_theta + r_theta_schools_school
y ~ normal(theta, 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] .~ restricted.(Cauchy(0, 5), 0.0, Inf)
z[1:length(levels(g)), 1:1] .~ Normal.(0, 1)
return z .* tau[1]
end
begin
school_fit_levels = brm_fit_levels(school_fit)
b_schools_school ~ brm_group_effects(school_fit_levels)
school_level = brm_level_indices(school, school_fit_levels)
ranef_theta_schools_school = b_schools_school[school_level, 1]
theta_Intercept ~ Normal(0.0, 5.0)
theta = theta_Intercept .+ ranef_theta_schools_school
y .~ Normal.(theta, sigma)
endfunctions {
matrix hcat(vector x) {
int n = dims(x)[1];
return to_matrix(x, n, 1);
}
vector normal_lpdfs(
vector obs,
vector loc,
vector scale
) {
return jbroadcasted_normal_lpdfs(obs, loc, scale);
}
vector jbroadcasted_normal_lpdfs(
vector x1,
vector x2,
vector 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), broadcasted_getindex(x3, i));
}
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,
vector 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_schools_school;
int n_school;
int school_idx_n;
array[school_idx_n] int school_idx;
int y_n;
vector[y_n] y;
int sigma_n;
vector[sigma_n] sigma;
}
transformed data {
matrix[num_elements(school_idx), 1] X_theta = hcat(rep_vector(1.0, num_elements(school_idx)));
int pop_theta_n_covariates = 1;
}
parameters {
vector<lower=0.0>[n_terms_schools_school] b_schools_school_tau;
vector[(n_terms_schools_school * n_school)] b_schools_school_z_flat;
vector[pop_theta_n_covariates] pop_theta_beta_pop;
}
transformed parameters {
matrix[n_terms_schools_school, n_school] b_schools_school_z = to_matrix(b_schools_school_z_flat, n_terms_schools_school, n_school);
matrix[n_school, n_terms_schools_school] b_schools_school = ((diag_matrix(b_schools_school_tau) * b_schools_school_z)');
vector[num_elements(school_idx)] pop_theta = (X_theta * pop_theta_beta_pop);
vector[school_idx_n] r_theta_schools_school = b_schools_school[school_idx, 1];
vector[num_elements(school_idx)] theta = (pop_theta + r_theta_schools_school);
}
model {
b_schools_school_tau ~ cauchy(0, 5);
b_schools_school_z_flat ~ std_normal();
pop_theta_beta_pop ~ normal([0]', [5]');
y ~ normal(theta, sigma);
}
generated quantities {
vector[y_n] y_likelihood = normal_lpdfs(y, theta, sigma);
vector[y_n] y_gen = normal_vector_rng(y_n, theta, 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: school, school_fit, sigma, y.
Model documentation:
- `b_schools_school`: 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.
"""
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 = {"school": {"dtype": "int64", "ndim": 1, "ragged": False}, "school_fit": {"dtype": "int64", "ndim": 1, "ragged": False}, "sigma": {"dtype": "float64", "ndim": 1, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}}
INPUTS = ("unconstrained", "ppl_last_b_schools_school_z", "ppl_axis1_b_schools_school_z", "school_level", "y", "sigma", "_ppl_pw_y_resp_lanes_1", "_ppl_pw_y_resp_lanes_2", "_ppl_pw_y_resp_lane_order")
PREPARED = {"ppl_last_b_schools_school_z": {"dtype": "int64", "ndim": 0, "ragged": False}, "ppl_axis1_b_schools_school_z": {"dtype": "int64", "ndim": 0, "ragged": False}, "school_level": {"dtype": "int64", "ndim": 1, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}, "sigma": {"dtype": "float64", "ndim": 1, "ragged": False}, "_ppl_pw_y_resp_lanes_1": {"dtype": "int64", "ndim": 1, "ragged": False}, "_ppl_pw_y_resp_lanes_2": {"dtype": "int64", "ndim": 1, "ragged": False}, "_ppl_pw_y_resp_lane_order": {"dtype": "int64", "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_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(5.0)
standardized = (tau_2 - 0.0) / jnp.where((tau_2 == 0.0 if 5.0 == 0 else False), 1.0, 5.0)
standard_logpdf = -np.log(np.pi) - jnp.log1p(standardized ** 2)
logpdf = standard_logpdf - jnp.where((tau_2 != 0.0 if 5.0 == 0 else False), 0.0, log_scale)
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(school: ArrayLike, school_fit: ArrayLike, sigma: 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)`.
"""
school = np.asarray(school, dtype=np.int64)
school_fit = np.asarray(school_fit, dtype=np.int64)
sigma = np.asarray(sigma, dtype=np.float64)
y = np.asarray(y, dtype=np.float64)
value = _brm_fit_levels_np(school_fit)
school_fit_levels = np.asarray(value, dtype=np.int64)
value_2 = _brm_level_indices_np(school, school_fit_levels)
school_level = np.asarray(value_2, dtype=np.int64)
ppl_axis1_b_schools_school_z = len(_rk_levels_np(school_fit_levels))
ppl_last_b_schools_school_z = 2 + ppl_axis1_b_schools_school_z
def lane_conditions(lane_input_1, lane_input_2):
return (bool(lane_input_2 > 0),)
lane_conditions_2 = np.asarray([lane_conditions(entry, entry_2) for entry, entry_2 in zip(y, sigma)], dtype=bool).reshape((-1, 1))
lanes = np.flatnonzero(lane_conditions_2[:, 0])
lanes_2 = np.flatnonzero(~lane_conditions_2[:, 0])
ppl_pw_y_resp_lanes_1 = lanes
ppl_pw_y_resp_lanes_2 = lanes_2
ppl_pw_y_resp_lane_order = np.argsort(np.concatenate((lanes, lanes_2,)), kind="stable")
return {"ppl_last_b_schools_school_z": StaticInt(ppl_last_b_schools_school_z), "ppl_axis1_b_schools_school_z": StaticInt(ppl_axis1_b_schools_school_z), "school_level": np.asarray(school_level, dtype=np.int64), "y": np.asarray(y, dtype=np.float64), "sigma": np.asarray(sigma, dtype=np.float64), "_ppl_pw_y_resp_lanes_1": np.asarray(ppl_pw_y_resp_lanes_1, dtype=np.int64), "_ppl_pw_y_resp_lanes_2": np.asarray(ppl_pw_y_resp_lanes_2, dtype=np.int64), "_ppl_pw_y_resp_lane_order": np.asarray(ppl_pw_y_resp_lane_order, dtype=np.int64)}
def model(_entry: str, unconstrained: ArrayLike, **prepared: ArrayLike) -> Any:
"""Shared model computation. The generated entry wrappers select a static output."""
ppl_last_b_schools_school_z = prepared["ppl_last_b_schools_school_z"]
ppl_axis1_b_schools_school_z = prepared["ppl_axis1_b_schools_school_z"]
school_level = prepared["school_level"]
y = prepared["y"]
sigma = prepared["sigma"]
_ppl_pw_y_resp_lanes_1 = prepared["_ppl_pw_y_resp_lanes_1"]
_ppl_pw_y_resp_lanes_2 = prepared["_ppl_pw_y_resp_lanes_2"]
_ppl_pw_y_resp_lane_order = prepared["_ppl_pw_y_resp_lane_order"]
unconstrained = jnp.asarray(unconstrained)
school_level = jnp.asarray(school_level)
y = jnp.asarray(y)
sigma = jnp.asarray(sigma)
_ppl_pw_y_resp_lanes_1 = jnp.asarray(_ppl_pw_y_resp_lanes_1)
_ppl_pw_y_resp_lanes_2 = jnp.asarray(_ppl_pw_y_resp_lanes_2)
_ppl_pw_y_resp_lane_order = jnp.asarray(_ppl_pw_y_resp_lane_order)
if _entry in ("log_density", "log_prior", "constrain"):
theta_Intercept = unconstrained[0]
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
ppl_floor_b_schools_school_tau = unconstrained[1:2]
b_schools_school_tau = jnp.exp(ppl_floor_b_schools_school_tau)
if _entry in ("log_density", "log_likelihood"):
prefix_stop = 1
if not (prefix_stop <= unconstrained.size):
raise ValueError("BoundsError: prefix exceeds array length")
ppl_affine_coef_theta = unconstrained[:max(prefix_stop, 0)]
plate_argument = ppl_affine_coef_theta[0]
if _entry in ("log_density", "log_prior"):
ppl_prior_theta_Intercept_log_scale = np.log(5.0)
ppl_prior_theta_Intercept_standardized = (theta_Intercept - 0.0) / jnp.where((theta_Intercept == 0.0 if 5.0 == 0 else False), 1.0, 5.0)
ppl_prior_theta_Intercept_standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * ppl_prior_theta_Intercept_standardized ** 2
logpdf = ppl_prior_theta_Intercept_standard_logpdf - jnp.where((theta_Intercept != 0.0 if 5.0 == 0 else False), 0.0, ppl_prior_theta_Intercept_log_scale)
if _entry in ("log_density", "log_jacobian"):
log_jacobian_2 = jnp.sum(unconstrained[1:2])
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
b_schools_school = brm_group_effects_density(
ppl_last_z=(ppl_last_b_schools_school_z if _entry in ("log_density", "log_prior", "log_likelihood", "constrain") else None),
tau=(b_schools_school_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_schools_school_z = jnp.reshape(b_schools_school["ppl_arrflat_z"], (ppl_axis1_b_schools_school_z, 1), order="F")
if _entry in ("log_density", "log_prior"):
prior = logpdf + b_schools_school["ppl_prior_tau"] + b_schools_school["ppl_prior_z"]
if _entry in ("log_density", "log_likelihood"):
b_schools_school_2 = brm_group_effects(
tau=(b_schools_school_tau if _entry in ("log_density", "log_likelihood") else None),
z=(b_schools_school_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_schools_school_1 = b_schools_school_2["value"][:, 0]
ranef_theta_schools_school = ppl_column_b_schools_school_1[school_level - 1]
def theta_cell(ppl_c1, ppl_offset_theta):
plate_value = ppl_c1 + ppl_offset_theta
return plate_value
theta = (jnp.zeros(ranef_theta_schools_school.shape[:1], dtype=jnp.float64) if 0 in ranef_theta_schools_school.shape[:1] else jax.vmap(theta_cell, in_axes=(None, 0))(plate_argument, ranef_theta_schools_school))
lane_entries = jnp.asarray(y)[_ppl_pw_y_resp_lanes_1]
lane_entries_2 = jnp.asarray(theta)[_ppl_pw_y_resp_lanes_1]
lane_entries_3 = jnp.asarray(sigma)[_ppl_pw_y_resp_lanes_1]
def ppl_pw_y_resp_cell(y_2, theta_2, sigma_2):
log_scale = jnp.log(sigma_2)
standardized = (y_2 - theta_2) / jnp.where(jnp.logical_and(sigma_2 == 0, y_2 == theta_2), 1.0, sigma_2)
standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * standardized ** 2
ppl_density = standard_logpdf - jnp.where(jnp.logical_and(sigma_2 == 0, y_2 != theta_2), 0.0, log_scale)
return ppl_density
plate_part = (jnp.zeros(lane_entries.shape[:1], dtype=jnp.float64) if 0 in lane_entries.shape[:1] and lane_entries_2.shape[:1] == lane_entries.shape[:1] and lane_entries_3.shape[:1] == lane_entries.shape[:1] else jax.vmap(ppl_pw_y_resp_cell, in_axes=(0, 0, 0))(lane_entries, lane_entries_2, lane_entries_3))
lane_entries_4 = jnp.asarray(y)[_ppl_pw_y_resp_lanes_2]
lane_entries_5 = jnp.asarray(theta)[_ppl_pw_y_resp_lanes_2]
lane_entries_6 = jnp.asarray(sigma)[_ppl_pw_y_resp_lanes_2]
def ppl_pw_y_resp_cell_2(y_2, theta_2, sigma_2):
ppl_density = -jnp.inf
return ppl_density
plate_part_2 = (jnp.zeros(lane_entries_4.shape[:1], dtype=jnp.float64) if 0 in lane_entries_4.shape[:1] and lane_entries_5.shape[:1] == lane_entries_4.shape[:1] and lane_entries_6.shape[:1] == lane_entries_4.shape[:1] else jax.vmap(ppl_pw_y_resp_cell_2, in_axes=(0, 0, 0))(lane_entries_4, lane_entries_5, lane_entries_6))
ppl_pw_y_resp = jnp.concatenate((plate_part, plate_part_2,))[_ppl_pw_y_resp_lane_order]
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_b_schools_school_z):
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 {"theta_Intercept": jnp.asarray(theta_Intercept, dtype=jnp.float64), "b_schools_school": {"tau": jnp.asarray(b_schools_school_tau), "z": jnp.asarray(b_schools_school_z)}}
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:
- `theta_Intercept`
- `b_schools_school.tau`
- `b_schools_school.z`
"""
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_b_schools_school_z"])
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 {"theta_Intercept": {"start": 0, "stop": 1, "transform": "identity", "dims": ()}, "b_schools_school.tau": {"start": 1, "stop": 2, "transform": "floored", "dims": (1,)}, "b_schools_school.z": {"start": 2, "stop": int(prepared["ppl_last_b_schools_school_z"]), "transform": "identity", "dims": (int(prepared["ppl_axis1_b_schools_school_z"]), 1)}}SBBRMI defaults to conventional noncentered random effects. centered_groups=(:school,) chooses a fixed centered Stan representation. RK emits noncentered effects; its adaptive wrapper changes the sampler's frame at runtime. Exact-total and S2Z coordinates are separate preparation choices described in the terms reference.
The fitting workflow
For Stan, prepare SBBRMI(model; total_groups=()), instantiate its density with stan_instantiate, then call adaptive_centering_problem(sb, problem, ad_backend). For RK, prepare RKBRMI(model) and rk_logdensity_problem(rk; ad_backend), then pass rk, that problem and the same backend to adaptive_centering_problem. WarmupHMC samples the wrapped problem. Its completion-based workflow runs independent chains; a fit receipt must report any omitted chains.
Inspect adaptive_centering_blocks and adaptive_centering_controls to relate controls to model quantities. adaptive_centering_cells(model) lists every random-effect cell as plain data, in the wrapper's cell order: what it is centred on (population coefficient, factor levels, containing cells), the earlier terms it conditions on, and each block's scales, correlation and mixing. Its docstring states the map those rows define, so code outside BRM can rebuild the wrapper's exact map and Jacobian, for example in another language. The wrapper exposes a grid from zero to one per supported cell. A position loss measures scale variation in candidate frames; a gradient loss measures position–gradient dependence. A pilot-based choice requires a fresh fit, while online adaptation updates during warmup. Compare their full gradient costs, including pilots.
Returned posterior_position draws are in the original model frame. Checkpoint positions may be in the sampler's adapted frame. Keep their frame and control metadata when resuming or auditing a fit; do not feed checkpoint coordinates directly into ordinary prediction.
HSGP frequencies
The same idea applies to HSGP weights: each basis function has a spectral scale determined by its frequency and the GP hyperparameters. Low and high frequencies need not select the same centering.
One control per HSGP weight
panes: brm|stanblocks|rkppl|stan|jax:3model = (@brm begin
mu ~ 1 + hsgp(time; k=8, domain=(-1.5, 1.5))
y ~ Normal(mu, sigma)
effect(mu, Intercept) ~ Normal(0, 1)
sd(mu, hsgp(time)) ~ Exponential(1)
sigma ~ Exponential(0.3)
end)((; time=collect(range(-1, 1; length=9)),
y=[-0.4, -0.5, -0.1, 0.2, 0.6, 0.8, 0.5, 0.2, 0.1]))SBBRMI with data keys = [:PHI_hsgp_time, :omega2_hsgp_time, :rho_lower_hsgp_time, :time, :y]
configured submodels:
_sb_hsgp_configured_1 = Base.merge(BayesianRegressionModels._sb_hsgp, quote
sigma ~ (StanBlocks.builtin.restricted)(exponential, 1.0 ./ 1.0; lower = 0.0)
end)
emitted @slic body:
begin
X_mu = hcat(rep_vector(1.0, num_elements(time)))
pop_mu ~ _popefs_normal(; X = X_mu, beta_loc = [0], beta_scale = [1])
hsgp_time ~ _sb_hsgp_configured_1(; PHI = PHI_hsgp_time, omega2 = omega2_hsgp_time, rho_lower = rho_lower_hsgp_time)
mu = pop_mu + hsgp_time
sigma ~ exponential(1.0 ./ 0.3)
y ~ normal(mu, sigma)
end"""
The Hilbert-space basis of an HSGP term at the rows.
Returns `(PHI, omega2)`: `PHI` holds one column per basis function, the Laplacian
eigenfunctions on the term's interval evaluated at each row's axes, and `omega2`
the matching squared frequencies, which the spectral density reads.
"""
ReactiveKernels.@kernel(brm_hsgp_basis_graph(axis, modes, settings) = begin
B = prod(modes)
center = settings[2]
width = settings[3]
omega2 = ReactiveKernels.plate(1:B) do mode
return ((mode * pi) / (2width)) ^ 2
end
basis_rows = ReactiveKernels.plate(axis) do x
values = ReactiveKernels.plate(1:B) do b
return sin(sqrt(omega2[b]) * ((x - center) + width)) / sqrt(width)
end
return values
end
PHI = if isempty(basis_rows)
zeros(0, B)
else
stack(basis_rows; dims = 1)
end
return (PHI, omega2)
end)
"""
The weight of each HSGP basis function: the square root of the covariance's
spectral density at its frequency, for the marginal scale `sigma` and length
scale `rho`.
"""
ReactiveKernels.@kernel(brm_hsgp_spectral_scales(axis, modes, settings, sigma, rho) = begin
(PHI, omega2) = brm_hsgp_basis_graph(axis, modes, settings)
weights = ReactiveKernels.plate(axes(omega2, 1)) do b
return (sigma * (rho * sqrt(2pi)) ^ (1 / 2)) * exp(-0.25 * (rho ^ 2 * omega2[b]))
end
return weights
end)
"""
An HSGP term's value at each row: the basis `PHI` times the basis weights `scales`
times the standardized coefficients `z`, `PHI * (scales .* z)`.
"""
ReactiveKernels.@kernel(brm_hsgp_spectral_graph(axis, modes, settings, scales, z) = begin
(PHI, omega2) = brm_hsgp_basis_graph(axis, modes, settings)
value = PHI * (scales .* z)
return value
end)
"""
A Hilbert-space Gaussian-process (HSGP) effect.
Draws the length scale `rho_iso`, each truncated below at the floor `rho_floor` the basis resolves, the marginal scale `sigma` and standardized basis
coefficients `beta_raw ~ Normal(0, 1)`. Each basis function is weighted by the
square root of the covariance's spectral density (`spectral_scale`), and the
effect at the rows is the basis times the weighted coefficients.
"""
brm_hsgp_effect(axis, modes, settings, rho_floor) = begin
rho_iso ~ restricted(LogNormal(0.0, 1.0), rho_floor, Inf)
sigma ~ Exponential(1)
beta_raw[1:prod(modes)] .~ Normal.(0, 1)
spectral_scale = brm_hsgp_spectral_scales(axis, modes, settings, sigma, rho_iso)
return brm_hsgp_spectral_graph(axis, modes, settings, spectral_scale, beta_raw)
end
begin
hsgp_time_modes = copy(hsgp_time_modes_fit)
hsgp_time_settings = copy(hsgp_time_settings_fit)
hsgp_time_rho_floor = if hsgp_time_modes[1] == 1
0.0
else
((4 * hsgp_time_settings[3]) / pi) * sqrt(log(100.0) / (hsgp_time_modes[1] ^ 2 - 1))
end
hsgp_time ~ brm_hsgp_effect(time, hsgp_time_modes, hsgp_time_settings, hsgp_time_rho_floor)
mu_Intercept ~ Normal(0.0, 1.0)
mu = mu_Intercept .+ hsgp_time
sigma ~ Exponential(0.3)
y .~ Normal.(mu, sigma)
endfunctions {
matrix hcat(vector x) {
int n = dims(x)[1];
return to_matrix(x, n, 1);
}
vector brm_hsgp_sqrt_spd(
matrix omega2,
real sigma,
vector rho
) {
int m = dims(omega2)[1];
int d = dims(omega2)[2];
if (dims(rho)[1] != d) reject("brm_hsgp_sqrt_spd: dim mismatch — `rho` dim 1 (= ", dims(rho)[1], ") does not match `d` (= ", d, "), inferred from `omega2` dim 2. `d` sizes: `omega2` dim 2 (= ", dims(omega2)[2], "), `rho` dim 1 (= ", dims(rho)[1], ").");
vector[m] rv;
real scale = sigma;
for(axis in 1:d) {
scale *= sqrt((rho[axis] * 2.5066282746310002));
}
for(b in 1:m) {
real exponent = 0.0;
for(axis in 1:d) {
exponent += (rho[axis] * rho[axis] * omega2[b, axis]);
}
rv[b] = (scale * exp((-0.25 * exponent)));
}
return rv;
}
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 time_n;
vector[time_n] time;
int omega2_hsgp_time_m;
int omega2_hsgp_time_n;
real rho_lower_hsgp_time;
matrix[omega2_hsgp_time_m, omega2_hsgp_time_n] omega2_hsgp_time;
int PHI_hsgp_time_m;
int PHI_hsgp_time_n;
matrix[PHI_hsgp_time_m, PHI_hsgp_time_n] PHI_hsgp_time;
int y_n;
vector[y_n] y;
}
transformed data {
matrix[num_elements(time), 1] X_mu = hcat(rep_vector(1.0, num_elements(time)));
int pop_mu_n_covariates = 1;
int hsgp_time_n_basis = omega2_hsgp_time_m;
int hsgp_time_n_axes = omega2_hsgp_time_n;
}
parameters {
vector[pop_mu_n_covariates] pop_mu_beta_pop;
real<lower=rho_lower_hsgp_time> hsgp_time_rho_iso;
real<lower=0.0> hsgp_time_sigma;
vector[hsgp_time_n_basis] hsgp_time_beta_raw;
real<lower=0.0> sigma;
}
transformed parameters {
vector[num_elements(time)] pop_mu = (X_mu * pop_mu_beta_pop);
vector[hsgp_time_n_axes] hsgp_time_rho = rep_vector(hsgp_time_rho_iso, hsgp_time_n_axes);
vector[omega2_hsgp_time_m] hsgp_time_sqrt_spd = brm_hsgp_sqrt_spd(omega2_hsgp_time, hsgp_time_sigma, hsgp_time_rho);
vector[PHI_hsgp_time_m] hsgp_time = (PHI_hsgp_time * (hsgp_time_sqrt_spd .* hsgp_time_beta_raw));
vector[num_elements(time)] mu = (pop_mu + hsgp_time);
}
model {
pop_mu_beta_pop ~ normal([0]', [1]');
hsgp_time_rho_iso ~ lognormal(0.0, 1.0);
hsgp_time_sigma ~ exponential((1.0 ./ 1.0));
hsgp_time_beta_raw ~ std_normal();
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: hsgp_time_modes_fit, hsgp_time_settings_fit, time, y.
Model documentation:
- `hsgp_time`: A Hilbert-space Gaussian-process (HSGP) effect.
Draws the length scale `rho_iso`, each truncated below at the floor `rho_floor` the basis resolves, the marginal scale `sigma` and standardized basis
coefficients `beta_raw ~ Normal(0, 1)`. Each basis function is weighted by the
square root of the covariance's spectral density (`spectral_scale`), and the
effect at the rows is the basis times the weighted coefficients.
"""
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 = {"hsgp_time_modes_fit": {"dtype": "int64", "ndim": 1, "ragged": False}, "hsgp_time_settings_fit": {"dtype": "float64", "ndim": 1, "ragged": False}, "time": {"dtype": "float64", "ndim": 1, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}}
INPUTS = ("unconstrained", "hsgp_time_rho_floor", "ppl_last_hsgp_time_beta_raw", "plate_argument", "hsgp_time_spectral_scale_omega2", "hsgp_time_spectral_scale_PHI", "y", "ppl_axis1_hsgp_time_beta_raw")
PREPARED = {"hsgp_time_rho_floor": {"dtype": "float64", "ndim": 0, "ragged": False}, "ppl_last_hsgp_time_beta_raw": {"dtype": "int64", "ndim": 0, "ragged": False}, "plate_argument": {"dtype": "int64", "ndim": 1, "ragged": False}, "hsgp_time_spectral_scale_omega2": {"dtype": "float64", "ndim": 1, "ragged": False}, "hsgp_time_spectral_scale_PHI": {"dtype": "float64", "ndim": 2, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}, "ppl_axis1_hsgp_time_beta_raw": {"dtype": "int64", "ndim": 0, "ragged": False}}
UNTRANSLATED = {}
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_hsgp_effect(
beta_raw: ArrayLike,
plate_argument: ArrayLike,
rho_iso: ArrayLike,
sigma: ArrayLike,
value_PHI: ArrayLike,
value_omega2: ArrayLike,
*,
outputs: tuple[str, ...],
) -> dict:
"""A Hilbert-space Gaussian-process (HSGP) effect.
Draws the length scale `rho_iso`, each truncated below at the floor `rho_floor` the basis resolves, the marginal scale `sigma` and standardized basis
coefficients `beta_raw ~ Normal(0, 1)`. Each basis function is weighted by the
square root of the covariance's spectral density (`spectral_scale`), and the
effect at the rows is the basis times the weighted coefficients.
"""
results = {}
if any(name in outputs for name in ("spectral_scale", "value")):
def weights_cell(b, sigma_2, rho, omega2):
return_ = sigma_2 * (rho * np.sqrt(2 * np.pi)) ** (1 / 2) * jnp.exp(-0.25 * (rho ** 2 * omega2[b - 1]))
return return_
spectral_scale = (jnp.zeros(plate_argument.shape[:1], dtype=jnp.float64) if 0 in plate_argument.shape[:1] else jax.vmap(weights_cell, in_axes=(0, None, None, None))(plate_argument, sigma, rho_iso, value_omega2))
if any(name in outputs for name in ("value",)):
value = value_PHI @ (spectral_scale * beta_raw)
if any(name in outputs for name in ("ppl_prior_rho_iso", "ppl_prior_rho_iso_logpdf")):
ppl_prior_rho_iso_location = 0.0
ppl_prior_rho_iso_scale = 1.0
ppl_prior_rho_iso_log_scale = np.log(ppl_prior_rho_iso_scale)
if any(name in outputs for name in ("ppl_prior_rho_iso", "ppl_prior_rho_iso_logpdf", "ppl_prior_rho_iso_logpdf_jacobian")):
ppl_prior_rho_iso_logpdf_log_x = jax.lax.cond(rho_iso <= 0, lambda: -jnp.inf, lambda: jnp.log(rho_iso))
if any(name in outputs for name in ("ppl_prior_rho_iso", "ppl_prior_rho_iso_logpdf_jacobian")):
ppl_prior_rho_iso_logpdf_jacobian = jnp.where(rho_iso <= 0, 0.0, ppl_prior_rho_iso_logpdf_log_x)
if any(name in outputs for name in ("ppl_prior_rho_iso", "ppl_prior_rho_iso_logpdf")):
ppl_prior_rho_iso_logpdf_logpdf_logpdf_z = (ppl_prior_rho_iso_logpdf_log_x - ppl_prior_rho_iso_location) / jnp.where((ppl_prior_rho_iso_logpdf_log_x == ppl_prior_rho_iso_location if ppl_prior_rho_iso_scale == 0 else False), 1.0, ppl_prior_rho_iso_scale)
ppl_prior_rho_iso_logpdf_logpdf_standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * ppl_prior_rho_iso_logpdf_logpdf_logpdf_z ** 2
ppl_prior_rho_iso_logpdf = ppl_prior_rho_iso_logpdf_logpdf_standard_logpdf - jnp.where((ppl_prior_rho_iso_logpdf_log_x != ppl_prior_rho_iso_location if ppl_prior_rho_iso_scale == 0 else False), 0.0, ppl_prior_rho_iso_log_scale)
if any(name in outputs for name in ("ppl_prior_rho_iso",)):
ppl_prior_rho_iso = ppl_prior_rho_iso_logpdf - ppl_prior_rho_iso_logpdf_jacobian
if any(name in outputs for name in ("ppl_prior_sigma", "ppl_prior_sigma_log_scale", "ppl_prior_sigma_scale")):
ppl_prior_sigma_scale = 1.0
if any(name in outputs for name in ("ppl_prior_sigma", "ppl_prior_sigma_log_scale")):
ppl_prior_sigma_log_scale = np.log(ppl_prior_sigma_scale)
if any(name in outputs for name in ("ppl_prior_sigma",)):
ppl_prior_sigma = jax.lax.cond(sigma < 0, lambda: -jnp.inf, lambda: -ppl_prior_sigma_log_scale - sigma / ppl_prior_sigma_scale)
if any(name in outputs for name in ("ppl_prior_beta_raw", "ppl_pw_prior_beta_raw")):
def ppl_pw_prior_beta_raw_cell(beta_raw_2):
log_scale = np.log(1.0)
standardized = (beta_raw_2 - 0.0) / jnp.where((beta_raw_2 == 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((beta_raw_2 != 0.0 if 1.0 == 0 else False), 0.0, log_scale)
return logpdf
ppl_pw_prior_beta_raw = (jnp.zeros(beta_raw.shape[:1], dtype=jnp.float64) if 0 in beta_raw.shape[:1] else jax.vmap(ppl_pw_prior_beta_raw_cell, in_axes=(0,))(beta_raw))
if any(name in outputs for name in ("ppl_prior_beta_raw",)):
ppl_prior_beta_raw = jnp.sum(ppl_pw_prior_beta_raw)
if "ppl_prior_beta_raw" in outputs:
results["ppl_prior_beta_raw"] = ppl_prior_beta_raw
if "ppl_prior_rho_iso" in outputs:
results["ppl_prior_rho_iso"] = ppl_prior_rho_iso
if "ppl_prior_sigma" in outputs:
results["ppl_prior_sigma"] = ppl_prior_sigma
if "ppl_pw_prior_beta_raw" in outputs:
results["ppl_pw_prior_beta_raw"] = ppl_pw_prior_beta_raw
if "ppl_prior_rho_iso_logpdf" in outputs:
results["ppl_prior_rho_iso_logpdf"] = ppl_prior_rho_iso_logpdf
if "ppl_prior_rho_iso_logpdf_jacobian" in outputs:
results["ppl_prior_rho_iso_logpdf_jacobian"] = ppl_prior_rho_iso_logpdf_jacobian
if "ppl_prior_sigma_log_scale" in outputs:
results["ppl_prior_sigma_log_scale"] = ppl_prior_sigma_log_scale
if "ppl_prior_sigma_scale" in outputs:
results["ppl_prior_sigma_scale"] = ppl_prior_sigma_scale
if "spectral_scale" in outputs:
results["spectral_scale"] = spectral_scale
if "value" in outputs:
results["value"] = value
return results
def prepare_data(hsgp_time_modes_fit: ArrayLike, hsgp_time_settings_fit: ArrayLike, time: 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)`.
"""
hsgp_time_modes_fit = np.asarray(hsgp_time_modes_fit, dtype=np.int64)
hsgp_time_settings_fit = np.asarray(hsgp_time_settings_fit, dtype=np.float64)
time = np.asarray(time, dtype=np.float64)
y = np.asarray(y, dtype=np.float64)
hsgp_time_modes = np.asarray(hsgp_time_modes_fit.copy(), dtype=np.int64)
hsgp_time_settings = np.asarray(hsgp_time_settings_fit.copy(), dtype=np.float64)
if hsgp_time_modes[0] == 1:
value = 0.0
else:
value = 4 * hsgp_time_settings[2] / 3.141592653589793 * np.sqrt(np.log(100.0) / (hsgp_time_modes[0] ** 2 - 1))
hsgp_time_rho_floor = value
ppl_axis1_hsgp_time_beta_raw = np.prod(hsgp_time_modes)
ppl_last_hsgp_time_beta_raw = 4 + ppl_axis1_hsgp_time_beta_raw
hsgp_time_spectral_scale_B = np.prod(hsgp_time_modes)
hsgp_time_spectral_scale_center = hsgp_time_settings[1]
hsgp_time_spectral_scale_width = hsgp_time_settings[2]
plate_argument = np.arange(1, hsgp_time_spectral_scale_B + 1)
def cell(mode, width):
return_ = (mode * np.pi / (2 * width)) ** 2
return return_
hsgp_time_spectral_scale_omega2 = np.asarray([cell(element, hsgp_time_spectral_scale_width) for element in plate_argument], dtype=np.float64)
def cell_2(x, B, omega2, center, width):
plate_argument_2 = np.arange(1, B + 1)
def cell_3(b, omega2_2, x_2, center_2, width_2):
return_ = np.sin(np.sqrt(omega2_2[b - 1]) * (x_2 - center_2 + width_2)) / np.sqrt(width_2)
return return_
values = np.asarray([cell_3(element_2, omega2, x, center, width) for element_2 in plate_argument_2], dtype=np.float64)
return values
hsgp_time_spectral_scale_basis_rows = [cell_2(element_2, hsgp_time_spectral_scale_B, hsgp_time_spectral_scale_omega2, hsgp_time_spectral_scale_center, hsgp_time_spectral_scale_width) for element_2 in time]
if (len(hsgp_time_spectral_scale_basis_rows) == 0):
value_2 = np.zeros((0, hsgp_time_spectral_scale_B), dtype=np.float64)
else:
value_2 = np.stack(hsgp_time_spectral_scale_basis_rows, axis=0)
hsgp_time_spectral_scale_PHI = value_2
plate_argument_2 = np.arange(1, len(hsgp_time_spectral_scale_omega2) + 1)
return {"hsgp_time_rho_floor": hsgp_time_rho_floor, "ppl_last_hsgp_time_beta_raw": StaticInt(ppl_last_hsgp_time_beta_raw), "plate_argument": np.asarray(plate_argument_2, dtype=np.int64), "hsgp_time_spectral_scale_omega2": np.asarray(hsgp_time_spectral_scale_omega2, dtype=np.float64), "hsgp_time_spectral_scale_PHI": np.asarray(hsgp_time_spectral_scale_PHI, dtype=np.float64), "y": np.asarray(y, dtype=np.float64), "ppl_axis1_hsgp_time_beta_raw": StaticInt(ppl_axis1_hsgp_time_beta_raw)}
def model(_entry: str, unconstrained: ArrayLike, **prepared: ArrayLike) -> Any:
"""Shared model computation. The generated entry wrappers select a static output."""
hsgp_time_rho_floor = prepared["hsgp_time_rho_floor"]
ppl_last_hsgp_time_beta_raw = prepared["ppl_last_hsgp_time_beta_raw"]
plate_argument = prepared["plate_argument"]
hsgp_time_spectral_scale_omega2 = prepared["hsgp_time_spectral_scale_omega2"]
hsgp_time_spectral_scale_PHI = prepared["hsgp_time_spectral_scale_PHI"]
y = prepared["y"]
ppl_axis1_hsgp_time_beta_raw = prepared["ppl_axis1_hsgp_time_beta_raw"]
unconstrained = jnp.asarray(unconstrained)
plate_argument = jnp.asarray(plate_argument)
hsgp_time_spectral_scale_omega2 = jnp.asarray(hsgp_time_spectral_scale_omega2)
hsgp_time_spectral_scale_PHI = jnp.asarray(hsgp_time_spectral_scale_PHI)
y = jnp.asarray(y)
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
ppl_fl_hsgp_time_rho_iso = unconstrained[0]
hsgp_time_rho_iso = jnp.maximum(hsgp_time_rho_floor, 0.0) + jnp.exp(ppl_fl_hsgp_time_rho_iso)
u_argument = unconstrained[1]
constrain_2 = jnp.exp(u_argument)
if _entry in ("log_density", "log_prior", "constrain"):
mu_Intercept = unconstrained[2]
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
u_argument_2 = unconstrained[3]
constrain_3 = jnp.exp(u_argument_2)
hsgp_time_beta_raw = unconstrained[4:ppl_last_hsgp_time_beta_raw]
if _entry in ("log_density", "log_prior", "log_likelihood"):
hsgp_time = brm_hsgp_effect(
beta_raw=(hsgp_time_beta_raw if _entry in ("log_density", "log_prior", "log_likelihood") else None),
plate_argument=(plate_argument if _entry in ("log_density", "log_likelihood") else None),
rho_iso=(hsgp_time_rho_iso if _entry in ("log_density", "log_prior", "log_likelihood") else None),
sigma=(constrain_2 if _entry in ("log_density", "log_prior", "log_likelihood") else None),
value_PHI=(hsgp_time_spectral_scale_PHI if _entry in ("log_density", "log_likelihood") else None),
value_omega2=(hsgp_time_spectral_scale_omega2 if _entry in ("log_density", "log_likelihood") else None),
outputs=tuple(
name for name, needed in (
("ppl_prior_beta_raw", ("log_density", "log_prior")),
("ppl_prior_rho_iso", ("log_density", "log_prior")),
("ppl_prior_sigma", ("log_density", "log_prior")),
("ppl_pw_prior_beta_raw", ("log_density", "log_prior")),
("ppl_prior_rho_iso_logpdf", ("log_density", "log_prior")),
("ppl_prior_rho_iso_logpdf_jacobian", ("log_density", "log_prior")),
("ppl_prior_sigma_log_scale", ("log_density", "log_prior")),
("ppl_prior_sigma_scale", ("log_density", "log_prior")),
("spectral_scale", ("log_density", "log_likelihood")),
("value", ("log_density", "log_likelihood")),
)
if _entry in needed
),
)
if _entry in ("log_density", "log_likelihood"):
ppl_affine_coef_mu = unconstrained[2:3]
mu = ppl_affine_coef_mu[0] + hsgp_time["value"]
def ppl_pw_y_resp_cell(y_2, mu_2, sigma):
def then_arm():
log_scale = jnp.log(sigma)
standardized = (y_2 - mu_2) / jnp.where(jnp.logical_and(sigma == 0, y_2 == mu_2), 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_2), 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 mu.shape[:1] == y.shape[:1] else jax.vmap(ppl_pw_y_resp_cell, in_axes=(0, 0, None))(y, mu, constrain_3))
ppl_lik_y_resp = jnp.sum(ppl_pw_y_resp)
if _entry in ("log_density", "log_prior"):
ppl_prior_mu_Intercept_log_scale = np.log(1.0)
ppl_prior_mu_Intercept_standardized = (mu_Intercept - 0.0) / jnp.where((mu_Intercept == 0.0 if 1.0 == 0 else False), 1.0, 1.0)
ppl_prior_mu_Intercept_standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * ppl_prior_mu_Intercept_standardized ** 2
logpdf = ppl_prior_mu_Intercept_standard_logpdf - jnp.where((mu_Intercept != 0.0 if 1.0 == 0 else False), 0.0, ppl_prior_mu_Intercept_log_scale)
ppl_prior_sigma_log_scale = np.log(0.3)
logpdf_2 = jax.lax.cond(constrain_3 < 0, lambda: -jnp.inf, lambda: -ppl_prior_sigma_log_scale - constrain_3 / 0.3)
prior = hsgp_time["ppl_prior_rho_iso"] + hsgp_time["ppl_prior_sigma"] + logpdf + logpdf_2 + hsgp_time["ppl_prior_beta_raw"]
if _entry in ("log_density", "log_jacobian"):
u_argument_3 = unconstrained[1]
u_argument_4 = unconstrained[3]
log_jacobian_2 = unconstrained[0] + u_argument_3 + u_argument_4
if _entry in ("log_density",):
posterior = prior + ppl_lik_y_resp + log_jacobian_2
if not (unconstrained.size == ppl_last_hsgp_time_beta_raw):
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 {"hsgp_time": {"rho_iso": jnp.asarray(hsgp_time_rho_iso, dtype=jnp.float64), "sigma": jnp.asarray(constrain_2, dtype=jnp.float64), "beta_raw": jnp.asarray(hsgp_time_beta_raw)}, "mu_Intercept": jnp.asarray(mu_Intercept, dtype=jnp.float64), "sigma": jnp.asarray(constrain_3, dtype=jnp.float64)}
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:
- `hsgp_time.rho_iso`
- `hsgp_time.sigma`
- `mu_Intercept`
- `sigma`
- `hsgp_time.beta_raw`
"""
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_hsgp_time_beta_raw"])
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 {"hsgp_time.rho_iso": {"start": 0, "stop": 1, "transform": "floored", "dims": ()}, "hsgp_time.sigma": {"start": 1, "stop": 2, "transform": "exp", "dims": ()}, "mu_Intercept": {"start": 2, "stop": 3, "transform": "identity", "dims": ()}, "sigma": {"start": 3, "stop": 4, "transform": "exp", "dims": ()}, "hsgp_time.beta_raw": {"start": 4, "stop": int(prepared["ppl_last_hsgp_time_beta_raw"]), "transform": "identity", "dims": (int(prepared["ppl_axis1_hsgp_time_beta_raw"]),)}}Stan's adaptive wrapper supports ordinary Gaussian and R2D2 blocks, supported HSGP weights, CAR and S2Z cells. Grouped HSGP weights can use correlated levels and group-specific scales; their conditional ordering is fixed by the fitted levels. ranef_order=:learned applies to supported ordinary correlated blocks. Bounds that depend on other sampled parameters are outside the HSGP adaptive-scale surface. Extremely small spectral scales use a smooth numerical floor; controls observed only on that floor stay noncentered.
RK's wrapper currently covers ordinary Gaussian effects with sampled scales. Bounded or Student-t blocks, known level covariance and stratified group blocks have narrower support. Unsupported field cells pass through in their original frame. Check the prepared block inventory before assuming that every latent quantity adapts. SVI's learned centering optimizes its variational objective; it is a separate procedure, though its controls can initialize supported MCMC adaptation.
What a comparison can establish
The recorded eight-schools study compares fixed coordinates with position and gradient adaptation. The figure uses minimum scientific-quantity bulk ESS per total gradient, relative to NCP; pilot gradients are included. These are historical single-chain runs with 10,000 retained draws per arm, not current runtime benchmarks or evidence of multichain convergence.
{"spec":"{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"_aov\":{\"legendInteraction\":\"highlight\"},\"_aovLegend\":{\"dimmed\":true,\"filtered\":false,\"opacity\":null,\"params\":[\"legend_selection\"],\"transform\":[]},\"config\":{\"axis\":{\"labelLimit\":0},\"header\":{\"labelLimit\":0},\"legend\":{\"labelLimit\":0}},\"data\":{\"values\":[{\"efficiency\":1.0,\"kind\":\"Fixed\",\"method\":\"NCP\"},{\"efficiency\":0.013880253382269784,\"kind\":\"Fixed\",\"method\":\"CP\"},{\"efficiency\":0.5529480196631141,\"kind\":\"Adaptive\",\"method\":\"Post-hoc position\"},{\"efficiency\":0.36369751705932696,\"kind\":\"Adaptive\",\"method\":\"Post-hoc gradient\"},{\"efficiency\":0.8981812165661297,\"kind\":\"Adaptive\",\"method\":\"Online position\"},{\"efficiency\":0.617723646006088,\"kind\":\"Adaptive\",\"method\":\"Online gradient\"}]},\"encoding\":{\"color\":{\"field\":\"kind\",\"scale\":{\"domain\":[\"Fixed\",\"Adaptive\"],\"range\":[\"#2a78d6\",\"#eb6834\"]},\"title\":\"Method\",\"type\":\"nominal\"},\"opacity\":{\"condition\":{\"test\":{\"and\":[{\"or\":[\"!isValid(datum[\\\"kind\\\"])\",{\"empty\":true,\"param\":\"legend_selection\"}]}]},\"value\":1},\"value\":0.15},\"tooltip\":[{\"field\":\"method\",\"type\":\"nominal\"},{\"field\":\"efficiency\",\"type\":\"quantitative\"},{\"field\":\"kind\",\"type\":\"nominal\"}],\"x\":{\"field\":\"method\",\"title\":\"Coordinates\",\"type\":\"nominal\"},\"y\":{\"field\":\"efficiency\",\"scale\":{\"zero\":false},\"title\":\"Relative ESS per total gradient\",\"type\":\"quantitative\"}},\"height\":260,\"mark\":\"bar\",\"params\":[{\"bind\":\"scales\",\"name\":\"grid\",\"select\":{\"encodings\":[\"y\"],\"type\":\"interval\"}},{\"bind\":\"legend\",\"name\":\"legend_selection\",\"select\":{\"fields\":[\"kind\"],\"type\":\"point\"}}],\"width\":540,\"description\":\"Recorded eight-schools efficiency relative to fixed NCP. The denominator includes warmup and any pilot. Each arm retained one chain of 10,000 draws; the research receipt records versions, seeds and diagnostics.\"}","caption":"Recorded eight-schools efficiency relative to fixed NCP. The denominator includes warmup and any pilot. Each arm retained one chain of 10,000 draws; the research receipt records versions, seeds and diagnostics.","alt":"Recorded eight-schools efficiency relative to fixed NCP. The denominator includes warmup and any pilot. Each arm retained one chain of 10,000 draws; the research receipt records versions, seeds and diagnostics."}| Method | Minimum bulk ESS | Divergences | Total gradients |
|---|---|---|---|
| NCP | 4839.400320780729 | 1 | 70276 |
| CP | 166.8721498172109 | 39 | 174583 |
| Post-hoc position | 5380.203333230999 | 0 | 141296 |
| Post-hoc gradient | 3964.5080546891486 | 0 | 158294 |
| Online position | 5350.0713015294195 | 2 | 86499 |
| Online gradient | 4458.254812264295 | 0 | 104806 |
Adaptation does not guarantee greater efficiency. Check divergences, bulk and tail ESS, R-hat across independent chains, and agreement in scientific quantities. Compare the same posterior and count all fitting work. A short pilot that misses a region can select poor coordinates for a later fit.
Reproduce
The research index links the motorcycle, eight-schools, radon, pupil, pupil-scale, air and RBesT protocols, source provenance and scripts. Their figures and draws are regenerated outside the repository; the page reads small recorded summaries. For adaptive fitting in a full model, continue to the Warfarin example.