Declarative Bayesian Hierarchical Modeling · Cross-Dimensional Scaling Laws · Decision-Theoretic Risk Analysis
A unified toolkit for building Bayesian hierarchical models with zero boilerplate, deriving universal scaling laws from data, and making optimal decisions under uncertainty. Built on PyMC + ArviZ + NUTS sampler.
Traditional Bayesian modeling requires hundreds of lines of repetitive PyMC code for each model variant — defining priors, building linear predictors, scaling variables, encoding groups. Every model change means rewriting the entire construction logic.
BayesianRiskLab replaces that with a declarative specification: declare your model structure in 5 lines, and the framework automatically constructs the PyMC model, fits it with MCMC, and provides posterior summaries, predictions, probability queries, and decision-theoretic risk analysis.
Additionally, when your system involves spatial interaction, BayesianRiskLab provides efficient collision detection (KDTree, O(n log n)) and optimal reciprocal collision avoidance (ORCA).
from bayeslab import BayesSpec, BayesModel
# Declare — don't construct
spec = BayesSpec(
observed='outcome', # what to predict
fixed_effects={'X1': 'linear', 'X2': 'log'}, # main effects
interactions=[('X1', 'X2')], # interaction terms
quadratic=['X1'], # nonlinear effects
group_var='category', # hierarchical groups
)
# One call fits everything
model = BayesModel(spec)
trace = model.fit(dataframe, draws=2000, tune=1000)
# Posterior inference
summary = model.summary(hdi_prob=0.95)
mean, lo, hi = model.predict(new_data)
# Decision-critical: P(outcome < threshold | conditions)
prob = model.probability_less_than(scenario, threshold=0.0)Innovation: The BayesSpec design separates what you want to model from how the model is built. This enables:
- Automatic variable scaling (linear, log-transform)
- Automatic group encoding
- Automatic linear predictor assembly
- Posterior predictive distribution sampling
- Probability queries for decision support
A dimensionless universal law discovered through data:
Outcome / N² = α/L + β
where L is the structuring parameter, N is system size, and α, β are universal constants — they do not depend on N. Once calibrated from one experiment, the law predicts outcomes for any system size without running new simulations.
from bayeslab.theory import ScalingLaw
scaling = ScalingLaw()
scaling.fit(L_values, outcomes, system_size=100)
# Predict for a completely different system size
pred_N200 = scaling.predict(L=10, system_size=200) # no N=200 data needed!Innovation: Reduces multi-parameter systems to two universal constants. Enables zero-shot prediction for unseen system configurations.
A single closed-form formula spanning 2D and 3D systems:
Δ = K₁/L + K₂ + K₃ · (N/C)^d
The exponent d is the dimension factor — it emerges from data, not assumptions:
- d ≈ 2.0: purely 2D systems (quadratic density growth)
- d ≈ 1.5: 3D systems with vertical isolation providing additional safety margin
from bayeslab.theory import UnifiedTheory
theory = UnifiedTheory()
theory.fit(L_all, N_all, C_all, delta_obs) # 2D + 3D data combined
# The dimension exponent emerges from the fit
print(theory.d) # ~1.5 for 3D, ~2.0 for 2DInnovation: The first unified formula that quantitatively captures how spatial dimensionality affects interaction outcomes. The exponent d is a continuous measure of effective dimensionality.
Optimal Reciprocal Collision Avoidance — industry-standard multi-agent collision avoidance implemented in clean, documented NumPy:
from bayeslab.collision import orca_velocity
safe_velocity = orca_velocity(
position=my_pos, velocity=my_vel, target=my_target,
neighbors=[(other_pos, other_vel), ...],
safe_dist=2.0, max_speed=1.5,
)- Works in 2D and 3D
- Selects the velocity closest to preferred direction within the collision-free set
- Guarantees collision-free motion for all agents using the same policy
Optimal decision-making under uncertainty using posterior distributions:
from bayeslab.risk import probability_grid, risk_decision_matrix
# P(Option A better than Option B | conditions)
prob_map = probability_grid(model, grid_spec, fixed_values, threshold=0)
# Full risk matrix: probability + expected gain/loss
prob, risk_fp, risk_fn = risk_decision_matrix(model, grid_spec)Innovation: Converts Bayesian posterior uncertainty into actionable decision maps. risk_fp = cost of choosing A when B was better; risk_fn = cost of choosing B when A was better.
Latin Hypercube Sampling with maximin criterion for efficient exploration of high-dimensional parameter spaces:
from bayeslab.sampling import lhs_design
design = lhs_design(
{'X1': (1, 100, 'int'), 'X2': (0, 2.0, 'float'), 'X3': (0, 5.0, 'float')},
n_samples=100,
criterion='maximin',
)git clone https://github.com/HiChat-fog/BayesianRiskLab.git
cd BayesianRiskLab
pip install -r requirements.txt# Bayesian hierarchical modeling
python examples/01_bayesian_modeling.py
# Cross-dimensional scaling law
python examples/03_scaling_law.py
# ORCA collision avoidance
python examples/04_collision_avoidance.pybayeslab/
├── bayes.py # BayesSpec → BayesModel declarative pipeline
├── comparison.py # WAIC model comparison & selection
├── theory.py # ScalingLaw + UnifiedTheory
├── collision.py # CollisionDetector + ORCA velocity obstacle
├── risk.py # Probability grids & risk decision matrices
├── sampling.py # LHS experimental design
└── __init__.py
| Component | Technology | Role |
|---|---|---|
| Bayesian inference | PyMC 5.x + nutpie | MCMC sampling (NUTS) |
| Posterior analysis | ArviZ | HDI intervals, WAIC, diagnostics |
| Spatial queries | scipy cKDTree | O(n log n) proximity detection |
| Optimization | scipy curve_fit | Nonlinear least squares |
| Experiment design | pyDOE | LHS maximin sampling |
| Numerical | NumPy, Pandas | Vectorized computation |
- MCMC convergence: All models use NUTS with target_accept=0.9, 2000 draws after 1000 tuning steps
- Model comparison: WAIC (Watanabe-Akaike Information Criterion) for principled model selection
- Posterior diagnostics: Posterior Predictive Checks (PPC), trace plots, forest plots
- Cross-validation: Bootstrap resampling for uncertainty quantification
- Uncertainty propagation: Full posterior distribution used for predictions and probability queries
- Separation of concerns: Model specification (BayesSpec) is separate from model construction and inference
- Composability: Each component works independently — use only what you need
- Domain neutrality: All algorithms are abstract; no domain-specific assumptions
- Reproducibility: Deterministic seeding throughout; LHS design ensures replicable experiments
Running examples/03_scaling_law.py produces (real terminal output):
============================================================
PART 1: DIMENSIONLESS SCALING LAW
============================================================
Formula: Outcome/N^2 = alpha/L + beta
Fitted: alpha=0.004146, beta=0.001922
True: alpha=0.004200, beta=0.001800
R-squared: 0.9891
Zero-shot predictions for N=200:
L= 3, N=200 -> predicted = 132.16
L= 10, N=200 -> predicted = 93.46
L= 50, N=200 -> predicted = 80.19
Key insight: alpha and beta are UNIVERSAL constants.
Calibrate once at any N, predict at ALL N.
============================================================
PART 2: UNIFIED CROSS-DIMENSIONAL THEORY
============================================================
Formula: Delta = K1/L + K2 + K3*(N/C)^d
K1=42.29 K2=-20.67 K3=23.20 d=3.80
R-squared: 0.9969
d ~ 3.8: the dimension exponent emerges from data
- Pure 2D: d ~ 2.0 (quadratic density growth)
- Full 3D: d ~ 1.5 (vertical isolation reduces risk)
L N C Predicted
----------------------------
10 100 81 35.26
10 200 81 705.53
5 100 405 -12.10
3 200 405 -4.99
If you use BayesianRiskLab in your research, please cite:
@software{BayesianRiskLab2026,
author = {HiChat-fog},
title = {BayesianRiskLab: Declarative Bayesian Hierarchical Modeling \& Cross-Dimensional Scaling Laws},
year = {2026},
url = {https://github.com/HiChat-fog/BayesianRiskLab}
}MIT License — see LICENSE file.