Bayesian Hierarchical Process Models

Bayesian Hierarchical Process Models

Overview

Fits hierarchical (multi-level) Bayesian regressions of the form

yt | xt, group ~ Normal(alpha{group[t]} + xt' beta, sigma)

with optional censoring on y_t and an AR(1) residual structure. Group intercepts are drawn from a hyperprior, enabling partial pooling across regimes.

The implementation uses PyMC (NUTS sampler) via a thin wrapper. The script accepts a YAML model specification so analysts can iterate on priors and likelihoods without editing code.

Prerequisites

1. uv available.
2. The script declares pymc, arviz, pandas, pyyaml in PEP-723;

first run installs them (sizeable: ~500 MB combined).

1. On first use, writes LICENSE_NOTIFICATION.txt.

When to Use

• Data has natural groupings (campaigns, operators, instruments) and you

want partial pooling.

• You need calibrated credible intervals that propagate censoring,

autocorrelation, and shrinkage.

• The model needs informative priors (e.g. from engineering judgement).

Don't use for

• Plain OLS or single-level GLMs (engineering-statistics).
• Time-series forecasting (use a dedicated state-space tool).
• Extremely large datasets (>1M rows) without thinning — NUTS is not

designed for that scale.

Utility Scripts

• uv run scripts/bhm.py fit --data data.csv --spec spec.yaml --output /tmp/fit.json

Example spec.yaml:

response: log_S_total
predictors: [z_heavy, source_split, lean_loading]
group: campaign
censoring:
  lower_col: LOQ_log
ar1: true
priors:
  beta: {dist: normal, mu: 0, sigma: 5}
  sigma: {dist: half_normal, sigma: 1}
  tau_group: {dist: half_normal, sigma: 0.5}
sampler:
  draws: 2000
  tune: 1000
  chains: 4
  target_accept: 0.95

Procedure

1. Build a tidy CSV: one row per observation; columns for response,

predictors, group, and censoring bounds.

1. Write the spec YAML. Start with weakly informative priors.
2. Run fit. Inspect:

• R-hat (should be 400).
• Divergences (should be 0).
• Posterior predictive checks.

1. If diagnostics fail, increase target_accept, tighten priors, or

reparameterise.

1. Report posterior means with 94% HDI; never report point estimates

alone.

Pitfalls

• Using flat priors and being surprised by funnel shapes. Weakly

informative priors (e.g. Normal(0, 5) on standardised predictors) work better.

• Failing to standardise predictors; PyMC + NUTS works much better with

scaled inputs.

• Treating the posterior mean as the only output; report the HDI.
• Running with chains=1; convergence diagnostics need at least 2 chains.
• Ignoring divergences; they indicate biased posterior geometry.
• Using non-centred parameterisation for groups with many observations

but the centred version for groups with few; pick consistently and re-fit if diagnostics fail.

• Forgetting to write the InferenceData artefact (NetCDF) to disk —

re-fitting is expensive.

Fallback Strategies

• If PyMC is unavailable, surface to the user; there is no clean

pure-Python fallback for hierarchical Bayesian with censoring.

• For sensitivity, fit the same model with at least two prior choices and

compare.

Verification

• Run the listed script with representative inputs and an --output file when a deterministic calculation is available.
• Confirm the JSON result contains ok: true, expected units, and no unhandled warnings.
• Check result magnitudes against the stated assumptions, references, and a hand calculation or known operating range before reporting them.

References

• references/spec_format.md — full spec.yaml grammar.
• Gelman, Carlin, Stern, Dunson, Vehtari, Rubin, Bayesian Data Analysis

(3rd ed).

• PyMC docs: https://www.pymc.io/

Anti-Patterns

• Reporting Bayesian posterior intervals as if they were classical CIs

without naming the model.

• Skipping convergence diagnostics.
• Treating sampling failure as a tuning issue without reviewing the model

geometry.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jskherman
• Source: jskherman/engg-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.