Partial pooling
Construct a repeated submodel and check its conditional posterior against a closed-form calculation. The data are the public eight-schools treatment-effect estimates used in hierarchical-model examples: one estimated effect and its reported standard error for each school. Effects and standard errors are in score points. The source file contains those published aggregates explicitly. For a source implementation, see the RStan getting-started example. The calculation here fixes the population mean and standard deviation as scenario inputs. It does not estimate their posterior distribution.
Model
Each school has a latent treatment effect. The sampling model treats the reported estimate as normal around that effect, with the reported standard error known. The population model is also normal. Fixing its mean and standard deviation lets us isolate the effect of measurement uncertainty on shrinkage and validate the compiled likelihood without a sampling algorithm.
The inner model describes one school and returns its latent effect. The outer model applies that submodel across aligned estimates and standard errors with plate. Each invocation receives its own observed estimate and uncertainty; the population inputs are shared. The returned effects form the outer model's parameter array. The generated Stan program makes this repeated structure visible, including the data, parameter dimensions and density contributions.
using StanBlocks
# Published eight-schools treatment-effect estimates and their standard errors.
school_data = (;
effect = [28.0, 8.0, -3.0, 7.0, -1.0, 1.0, 18.0, 12.0],
standard_error = [15.0, 10.0, 16.0, 11.0, 9.0, 11.0, 10.0, 18.0],
population_mean = 0.0,
population_sd = 10.0,
)
const school_effect = @slic begin
theta ~ normal(population_mean, population_sd)
effect ~ normal(theta, standard_error)
return theta
end
const schools = @slic begin
theta ~ plate(effect, standard_error; outer=(length(effect),)) do estimate, uncertainty
theta_i ~ school_effect(; effect=estimate, standard_error=uncertainty,
population_mean, population_sd)
theta_i
end
end
model = schools(; school_data...)Generated Stan
functions {
// Return the normalized log probability for a single observation.
real normal_lpdfs(
real args1,
real args2,
real args3
) {
return normal_lpdf(args1 | args2, args3);
}
}
data {
int effect_n;
vector[effect_n] effect;
real population_mean;
real population_sd;
int standard_error_n;
vector[standard_error_n] standard_error;
}
transformed data {
}
parameters {
vector[num_elements(effect)] theta_theta_i_theta;
}
transformed parameters {
}
model {
for(plate_i__pl_1 in 1:num_elements(effect)) {
theta_theta_i_theta[plate_i__pl_1] ~ normal(population_mean, population_sd);
effect[plate_i__pl_1] ~ normal(theta_theta_i_theta[plate_i__pl_1], standard_error[plate_i__pl_1]);
}
}
generated quantities {
vector[num_elements(effect)] theta_theta_i;
vector[num_elements(effect)] theta;
vector[effect_n] effect_gen;
for(plate_i__pl_1 in 1:num_elements(effect)) {
effect_gen[plate_i__pl_1] = normal_rng(theta_theta_i_theta[plate_i__pl_1], standard_error[plate_i__pl_1]);
theta_theta_i[plate_i__pl_1] = theta_theta_i_theta[plate_i__pl_1];
theta[plate_i__pl_1] = theta_theta_i[plate_i__pl_1];
}
}A school with an imprecise estimate contributes less information about its latent effect. Its conditional posterior is consequently influenced more by the fixed population distribution. This is a consequence of the probability model, not a separate adjustment applied to fitted values. The composition guide explains submodel inputs and returns; the array guide explains repeated models and their parameter representation.
The assumptions are substantive. Reported standard errors are treated as known, school estimates are conditionally independent, and the population scale represents variation in true effects rather than measurement noise. Normal sampling distributions can be reasonable for estimated effects even when individual outcomes are not normally distributed. Their adequacy depends on how those estimates and standard errors were obtained.
Conditional calculation
For each school, posterior precision is the sum of observation precision and population precision. Posterior variance is its reciprocal. The conditional mean is that variance multiplied by the sum of the observation and population means weighted by their respective precisions. With the fixed population mean used here, it can also be read as the observed estimate multiplied by its data weight. The remaining weight belongs to the population mean.
The build evaluates these expressions from the data in the model file. It also compiles the Stan model and compares its log density with an independent sum of normal log densities. The table therefore shows a calculation associated with the executed model rather than hand-entered illustrative results.
| School | Observed effect (points) | SE (points) | Data weight | Conditional mean (points) | Conditional SD (points) |
|---|---|---|---|---|---|
| 1 | 28.0 | 15.0 | 0.308 | 8.615 | 8.321 |
| 2 | 8.0 | 10.0 | 0.5 | 4.0 | 7.071 |
| 3 | -3.0 | 16.0 | 0.281 | -0.843 | 8.48 |
| 4 | 7.0 | 11.0 | 0.452 | 3.167 | 7.399 |
| 5 | -1.0 | 9.0 | 0.552 | -0.552 | 6.69 |
| 6 | 1.0 | 11.0 | 0.452 | 0.452 | 7.399 |
| 7 | 18.0 | 10.0 | 0.5 | 9.0 | 7.071 |
| 8 | 12.0 | 18.0 | 0.236 | 2.83 | 8.742 |
Read across a row to connect observation uncertainty with the conditional estimate. The data weight is dimensionless. The observed effect, its standard error, the conditional mean and conditional standard deviation all retain score-point units. Comparing weights across rows shows why observations with similar effects can undergo different amounts of shrinkage.
These conditional distributions are independent across schools because both population parameters are fixed. If the population parameters were inferred jointly, their uncertainty would couple the school effects. A full hierarchical analysis would average over that uncertainty, so its intervals generally would not equal the conditional intervals on this page. Fixing a population scale for demonstration should not be mistaken for estimating that scale from the school data.
Checks
The density comparison evaluates distinct parameter vectors, including the conditional mean and a displacement scaled by the conditional standard deviations. Stan may discard constants that do not depend on parameters. Accordingly, the check compares changes in log density, allowing one shared additive constant. A mismatch would expose a problem in the repeated model, its observation binding or the analytic reference calculation.
| Check | Result |
|---|---|
| Stan − reference density range | 0 |
| All weights between zero and one | true |
| All conditional SDs below observation SEs | true |
The weight and uncertainty checks are consequences of combining two normal information sources with positive, finite variances. They help detect an inverted precision, a mismatched data column or another mistake in the calculation. They are algebraic and implementation checks. They do not assess the empirical suitability of a normal population distribution for these schools.
No chain diagnostics are appropriate here: no chain is run. The exact conditional formulas remove Monte Carlo error, but they do not remove model uncertainty or uncertainty about the inputs that were held fixed. The build receipt in the reproduction footer identifies the source used for this calculation. No fitted draws or numerical summaries need to be committed.
Shrinkage
The figure places the observed estimates beside the conditional posterior means and their central intervals. Every interval uses the same posterior probability level, computed from the normal quantile function during the build. The common point scale lets the displacement toward the population mean be compared across schools.
The orange markers represent noisy estimates, while the blue markers represent conditional means for latent effects. Their displacement is expected under the model and is not evidence that the original estimates were biased. The blue intervals quantify uncertainty about latent effects conditional on the population inputs. They are not prediction intervals for a new reported estimate; a future estimate would also include its sampling uncertainty.
A new school can be represented by the same submodel with its own estimate and standard error. A school without an observed estimate instead requires a prediction view that leaves the corresponding outcome unconditioned. The prediction guide describes that distinction and why marking an entire input is different from withholding selected observations. Changing the population inputs is also a useful sensitivity calculation, but each scenario must be interpreted conditionally rather than pooled into an unlabeled set of fitted results.
Reproduce
Build calculation; no fitted parameters or cached draws. Source SHA-256: 6749cbc611c21bc9b04d769879e02426870ec9890e84133c07e05e088dfdbc49. Numerical receipt.
The shell command below reproduces this result from the repository root. It runs the documentation examples and regenerates the figure.
julia --project=docs docs/make.jl