Teaching with bayesgrove

Use bayesgrove’s decision log to review students’ modeling choices and their reasons. Blocking obligations require students to record a review before downstream computation can proceed.

Assignment

Students submit two files:

1. A report from bg_export_report(handle, format = "html"), containing the graph diagram and decision history.
2. A project bundle from bg_bundle(handle), containing the records used to verify the report.

Open the bundle to compare its decision and summary logs with the report:

utils::untar("student-submission.tar.gz", exdir = "check")
handle <- bg_open("check/project")

bg_status(handle) # blocked? then obligations were left unresolved
bg_next_actions(handle) # prints outstanding obligations as a checklist
bg_export_report(handle, format = "md") # regenerate and diff against the submitted report

Grading checklist

Use the obligations and their evidence to assess the analysis.

Obligation (pack)	Evidence behind it	Rubric item
review_computation_validity	hmc_diagnostics summary with warning/error severity	Every sampler warning has a recorded computation_review decision whose rationale names the diagnostic (divergences, R-hat, ESS, E-BFMI).
Prior rationale (prior pack)	Prior/prior-predictive nodes	Every prior choice has a decision with a substantive rationale, not “default”.
Prior/posterior predictive review	prior_predictive_check, posterior_predictive_check summaries	PPC results interpreted, not just produced; extreme p-values acknowledged.
Calibration review (SBC pack)	sbc_result, loo_pit_calibration summaries	Calibration checked where the assignment requires it; miscalibration discussed.
review_fit_criticism	Branch-scoped diagnostic problems	Revisions use branches that retain the earlier model and record its criticism.
compare_candidate_branches / accept_or_reject_branch	comparison_results, stacking_weights summaries	A comparison supports the final model choice, and a branch-disposition decision cites it.

Check the logs for missing reviews and incomplete rationales:

• Every summary in workflow/summaries.jsonl with severity warning/error should be referenced (via its node or evidence field) by some decision in decisions/decisions.jsonl.
• Sort decisions by rationale length to find one-word answers for closer review.

Course setup tips

• Have students start from bg_init() + bg_use_cmdstanr() + bg_use_default_workflow() so the baseline review pack is active from the first fit. Stricter packs (prior rationale, SBC review) can be introduced per assignment via bg_use_workflow_packs().
• Use bg_add_gate() to add checkpoints to a template project, such as a gate before a hierarchical model asking “justify the pooling structure”. These differ from obligations raised by diagnostic evidence (see ?bayesgrove-concepts for the gates-vs-obligations table).
• The REPL (bg_repl()) shows the obligation checklist interactively and explain <n> prints its reason and literature references. Use these to explain checks such as divergence diagnostics.
• Plots are one call per node: bg_plot(handle, node_id) renders PPC density overlays, LOO-PIT ECDFs, SBC rank histograms, and trace plots for flagged fits.

Assess the reasoning

The log records decisions, timestamps, and evidence references. The instructor must assess whether each rationale, such as “heavier tails to absorb outliers”, is justified for the data.