docs: consolidate the getting-started cluster — quickstart, learning ladder, archive

[AlexanderFengler]

The flagship PR of the docs-overhaul Phase 2: six pages re-teaching the same simulate → define → sample → PPC workflow become a four-rung learning ladder plus an archive. No unique content is lost — everything unique was extracted first.

• Quickstart (Option B): getting_started.ipynb slimmed from 41 cells / 4 model fits to an 18-cell, single-fit 15-minute quickstart, re-executed fresh, ending in a posterior predictive check (hssm.plotting.plot_predictive) and an explicit next-steps ladder. 2.1 MB → 0.7 MB.
• New how-to: Specify priors and fix parameters (how_to/specify_priors.ipynb) — the prior-syntax walkthrough extracted from the old getting-started (include dicts, hssm.Param, hssm.Prior, bounds, fixing, shortcut syntax, regression-coefficient priors), re-executed fresh.
• New how-to: Compare and interpret models (how_to/compare_models.ipynb) — seeded from workshop 1's az.compare passage (a top demand gap); adds the interpretation guidance the workshop never had (elpd_diff vs. dse, weights, Pareto-k caveats). Stored outputs inherited from the workshop run; sampler progress spam trimmed; skipped in notebook CI like its source was.
• Archive section: the three 2025 workshop notebooks move to docs/archive/ with event-snapshot banners crediting the original authors; redirects cover the old URLs; docs/archive/ is excluded from notebook CI and docs-build execution.
• Merges before retirement: workshop 2's EDA framing question absorbed into the scientific-workflow tutorial's EDA intro; workshop 1's comparison passage → the new how-to; pymc_to_hssm archived intact (its PyMC-contrast intro is recorded for the low-level cluster consolidation).
• Learning ladder in nav: Quickstart → The HSSM tutorial (main_tutorial, retitled) → Hierarchical modeling → A complete scientific workflow; new "How-to guides" section.
• mkdocs build --strict green; quickstart + priors how-to re-executed end-to-end with zero errors.

Closes #1164

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a model-comparison guide covering competing hierarchical models, posterior summaries, ELPD, model weights, uncertainty, and diagnostic cautions.
  • Added exploratory data analysis guidance to the scientific workflow tutorial.

• Documentation

  • Reorganized navigation into Quickstart, tutorials, how-to guides, and an archive.
  • Added archival notices and updated links for workshop materials.
  • Refreshed introductory documentation and tutorial titles and links.

• Tests

  • Updated notebook checks to exclude archived content and use the model-comparison notebook in validation.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[coderabbitai]

Warning

Review limit reached

@AlexanderFengler, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 6 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c00fab25-b525-415b-a111-f7cee7039b71

📥 Commits

Reviewing files that changed from the base of the PR and between f603485 and b2bc80c.

📒 Files selected for processing (2)

• docs/archive/pymc_to_hssm.ipynb
• docs/how_to/compare_models.ipynb

📝 Walkthrough

Walkthrough

The documentation is reorganized around current tutorials, archived workshop snapshots, and a new model-comparison how-to. Navigation and redirects are updated. Notebook checks exclude archived notebooks and the computationally heavy comparison notebook.

Changes

Documentation consolidation

Layer / File(s)	Summary
Current learning documentation docs/index.md, docs/tutorials/main_tutorial.ipynb, docs/tutorials/scientific_workflow_hssm.ipynb, docs/tutorials/ddm_hierarchical_tutorial.ipynb	Current tutorial labels, introductory links, EDA guidance, and archive references are updated.
Archive navigation and snapshots docs/archive/*.ipynb, docs/archive/pymc_to_hssm/network_config.yaml, mkdocs.yml	Workshop notebooks receive archive notices. Navigation, redirects, ignored paths, and archived network configuration are updated.
Model-comparison how-to and execution docs/how_to/compare_models.ipynb, .github/workflows/check_notebooks.yml, mkdocs.yml	A model-comparison notebook adds hierarchical DDM simulation, competing fits, sampling, and az.compare interpretation. Notebook discovery and execution exclusions are updated.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• lnccbrown/HSSM#1143: Updates notebook discovery, skip handling, and sharded execution.
• lnccbrown/HSSM#1155: Adds related documentation redirect and validation configuration.
• lnccbrown/HSSM#1004: Modifies the hierarchical tutorial and documentation navigation.

Suggested reviewers: digicosmos86

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR addresses archival, model comparison, tutorial, navigation, and redirect work, but the summary lacks the required quickstart and priors how-to changes.	Add the 15-minute quickstart and the “How to specify priors and fix parameters” how-to, then verify all linked navigation and redirect requirements.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation consolidation, learning ladder, quickstart, and archive changes.
Out of Scope Changes check	✅ Passed	The reviewed changes support the documentation consolidation objectives and show no unrelated code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 1164-getting-started-consolidation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

docs/how_to/compare_models.ipynb (2)

83-92: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Fix the matplotlib alias and the conflicting backend calls.

Line 83 binds the top-level matplotlib package to the name plt. The conventional meaning of plt is matplotlib.pyplot. The cell runs because matplotlib.use exists, but any reader who copies this setup and then calls plt.subplots() gets an AttributeError.

Line 91 selects the Agg backend, and line 92 then switches to the inline backend. The Agg call has no effect.

♻️ Proposed setup cell

 # Import modules
 import arviz as az
 import jax
-import matplotlib as plt
 import pytensor
 
 import hssm
 
 pytensor.config.floatX = "float32"
 jax.config.update("jax_enable_x64", False)
 
-plt.use("Agg")
 %matplotlib inline
 %config InlineBackend.figure_format='retina'
-
-# hssm.set_floatX("float32")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/how_to/compare_models.ipynb` around lines 83 - 92, Update the notebook
setup imports to bind pyplot as plt, and remove the conflicting
matplotlib.use("Agg") call so the existing %matplotlib inline directive is the
sole backend selection. Preserve the remaining imports and configuration
statements.

---

397-419: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remove the commented-out simulation code.

Lines 397-419 hold about 23 lines of disabled code from the workshop notebook. The active list comprehension at lines 422-428 already builds the dataset. This is a new curated how-to, not an archived snapshot, so the dead code adds noise for readers.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/how_to/compare_models.ipynb` around lines 397 - 419, Remove the
commented-out simulate_participant3 examples for dataset2_participant1 through
dataset2_participant16, including the surrounding severity and diagnosis
headings. Keep the active dataset-building list comprehension unchanged.

mkdocs.yml (1)

103-105: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Use internal targets for the notebook redirects.

Set each target to its corresponding archive/*.ipynb source path. Keep the old tutorials/*.md keys because mkdocs-redirects requires markdown-shaped redirect keys; .ipynb keys trigger a warning. Internal targets keep previews and fork builds self-contained.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@mkdocs.yml` around lines 103 - 105, Update the three notebook redirect values
for tutorials/hssm_tutorial_workshop_1.md,
tutorials/hssm_tutorial_workshop_2.md, and tutorials/pymc_to_hssm.md to their
corresponding internal archive/*.ipynb source paths. Preserve the existing
tutorials/*.md keys because mkdocs-redirects requires markdown-shaped redirect
keys.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/archive/pymc_to_hssm.ipynb`:
- Line 43: Update both download URLs in cell 5 of the pymc_to_hssm notebook from
the removed docs/tutorials/pymc_to_hssm/ path to docs/archive/pymc_to_hssm/,
preserving the rest of the links and notebook content.

In `@docs/how_to/compare_models.ipynb`:
- Around line 312-317: Add deterministic random seeding to simulate_participant3
before its np.random.normal calls, ensuring repeated notebook executions
generate the same dataset, model fits, and ELPD values referenced in the
narrative.

---

Nitpick comments:
In `@docs/how_to/compare_models.ipynb`:
- Around line 83-92: Update the notebook setup imports to bind pyplot as plt,
and remove the conflicting matplotlib.use("Agg") call so the existing
%matplotlib inline directive is the sole backend selection. Preserve the
remaining imports and configuration statements.
- Around line 397-419: Remove the commented-out simulate_participant3 examples
for dataset2_participant1 through dataset2_participant16, including the
surrounding severity and diagnosis headings. Keep the active dataset-building
list comprehension unchanged.

In `@mkdocs.yml`:
- Around line 103-105: Update the three notebook redirect values for
tutorials/hssm_tutorial_workshop_1.md, tutorials/hssm_tutorial_workshop_2.md,
and tutorials/pymc_to_hssm.md to their corresponding internal archive/*.ipynb
source paths. Preserve the existing tutorials/*.md keys because mkdocs-redirects
requires markdown-shaped redirect keys.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d36c3646-29cb-4128-9a34-33d52003c605

📥 Commits

Reviewing files that changed from the base of the PR and between e9865d6 and f603485.

⛔ Files ignored due to path filters (31)

• docs/archive/hssm_tutorial_workshop_1/ssm_overview.png is excluded by !**/*.png
• docs/archive/hssm_tutorial_workshop_2/Choice_Learning.csv is excluded by !**/*.csv
• docs/archive/hssm_tutorial_workshop_2/HDDM_results.png is excluded by !**/*.png
• docs/archive/hssm_tutorial_workshop_2/Palmer_etal_2024.PNG is excluded by !**/*.png
• docs/archive/hssm_tutorial_workshop_2/behavioral_task.png is excluded by !**/*.png
• docs/archive/hssm_tutorial_workshop_2/choiceRatios.png is excluded by !**/*.png
• docs/archive/hssm_tutorial_workshop_2/ddm_schematic.png is excluded by !**/*.png
• docs/archive/hssm_tutorial_workshop_2/latencies.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/example_network/lan/ddm/a227477e683411f0abcd6ae25f443f62_lan_ddm_network_config.pickle is excluded by !**/*.pickle
• docs/archive/pymc_to_hssm/example_network/lan/ddm/ddm_lan_a227477e683411f0abcd6ae25f443f62_data_details.pickle is excluded by !**/*.pickle
• docs/archive/pymc_to_hssm/example_network/lan/ddm/ddm_lan_a227477e683411f0abcd6ae25f443f62_train_config.pickle is excluded by !**/*.pickle
• docs/archive/pymc_to_hssm/example_network/lan/ddm/ddm_lan_a227477e683411f0abcd6ae25f443f62_training_history.csv is excluded by !**/*.csv
• docs/archive/pymc_to_hssm/images/ANGLE_with_params_pic.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/DDM_with_params_pic.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/Experiment.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/HSSM_logo.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/HSSM_logo_old.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/Race_3.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/basic_lan_pic.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/network_hssm_pymc.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/network_onnx.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/onnx_logo.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/playground.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/pymc_logo.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/race_with_difficulty.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/rv_to_hssm.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/simulation_to_network.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/images/zeus_sampler.png is excluded by !**/*.png
• docs/archive/pymc_to_hssm/mathpsych_workshop_2025_data/mathpsych_2025_full.parquet is excluded by !**/*.parquet
• docs/archive/pymc_to_hssm/mathpsych_workshop_2025_data/mathpsych_2025_modeling.parquet is excluded by !**/*.parquet
• docs/archive/pymc_to_hssm/mathpsych_workshop_2025_data/mathpsych_2025_parameters.pkl is excluded by !**/*.pkl

📒 Files selected for processing (19)

• .github/workflows/check_notebooks.yml
• docs/archive/hssm_tutorial_workshop_1.ipynb
• docs/archive/hssm_tutorial_workshop_2.ipynb
• docs/archive/pymc_to_hssm.ipynb
• docs/archive/pymc_to_hssm/example_network/lan/ddm/ddm_lan_a227477e683411f0abcd6ae25f443f62_model.onnx
• docs/archive/pymc_to_hssm/example_network/lan/ddm/ddm_lan_a227477e683411f0abcd6ae25f443f62_train_state_dict.pt
• docs/archive/pymc_to_hssm/mathpsych_workshop_2025_data/ddm_lan.onnx
• docs/archive/pymc_to_hssm/mathpsych_workshop_2025_data/ddm_lan_batch.onnx
• docs/archive/pymc_to_hssm/mathpsych_workshop_2025_data/race_3_no_bias_lan.onnx
• docs/archive/pymc_to_hssm/mathpsych_workshop_2025_data/race_3_no_bias_lan_batch.onnx
• docs/archive/pymc_to_hssm/network_config.yaml
• docs/getting_started/getting_started.ipynb
• docs/how_to/compare_models.ipynb
• docs/how_to/specify_priors.ipynb
• docs/index.md
• docs/tutorials/ddm_hierarchical_tutorial.ipynb
• docs/tutorials/main_tutorial.ipynb
• docs/tutorials/scientific_workflow_hssm.ipynb
• mkdocs.yml