Add example of topological posterior predictive checks with persistent homology

[gsidoine]

Addresses #880

This PR adds a new example notebook demonstrating topological posterior predictive checks for PyMC models.

The notebook shows how persistent-homology summaries can be used as posterior predictive discrepancy statistics when the relevant model failure concerns global shape rather than only marginal moments, variance, or autocorrelation.

The example uses a synthetic seasonal time series and compares two PyMC models:

1. A Gaussian model fitted to a delay-coordinate embedding of the time series.
2. A Fourier seasonal model fitted to the original time series.

Both models are evaluated using ordinary posterior predictive checks and topological posterior predictive checks computed on delay embeddings of posterior predictive samples.

The main workflow illustrated is:

ordinary posterior predictive checks pass
→ topological posterior predictive checks detect missing global structure
→ model is revised
→ posterior predictive topology improves

The goal is not to add persistent homology as a PyMC dependency, but to show how users can combine PyMC posterior predictive samples with external topology tools such as ripser for model criticism.

The notebook is currently placed under:

examples/case_studies/topological_posterior_predictive_checks.ipynb

I am happy to move it to another section if maintainers prefer a different location.

• Notebook follows style guide https://docs.pymc.io/en/latest/contributing/jupyter_style.html
• PR description contains a link to the relevant issue:
  • a tracker one for existing notebooks (tracker issues have the "tracker id" label)
  • or a proposal one for new notebooks
• Check the notebook is not excluded from any pre-commit check: https://github.com/pymc-devs/pymc-examples/blob/main/.pre-commit-config.yaml

Helpful links

• https://github.com/pymc-devs/pymc-examples/blob/main/CONTRIBUTING.md

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[gsidoine]

I opened this as a draft PR to get feedback on scope, notebook placement, and dependency handling for ripser.

I am contributing through the GitHub web UI, so I have not yet run the full local pre-commit workflow. However, the Read the Docs preview build for this PR completed successfully, and the notebook now renders after removing the broken widget metadata.

The PR addresses proposal issue #880.

Happy to revise the notebook structure, location, or dependency notes based on maintainer feedback.

[gsidoine]

I have updated the notebook metadata/style elements, added the BibTeX references to examples/references.bib, and linked the Authors section to this PR.

I have not run local pre-commit because I am contributing through the GitHub web UI, but I am happy to address any formatting or style issues that CI or reviewers identify.

[juanitorduz]

I think we can remove the sentence "This is a workflow example, not a proposal to put persistent homology inside the PyMC sampler. "

Reply via ReviewNB

[juanitorduz]

I think it would be good to add some description on what homology is and why it can be useful (no need to define all the machinery, but the intuition). Maybe some diagrams are enough.

For more advanced users, we should add an appendix describing the concept (why homology? What is the boundary operator? How to compute it?)

Reply via ReviewNB

[juanitorduz]

for some of these functions we could add doctrings explaining what they do and why are they useful.

Reply via ReviewNB

[juanitorduz]

Hi @gsidoine, thanks for the notebook!

• Can you please fix the pre-commit errors (see CI)
• Can you re-sun the notebook and push it? We are not seeing the images https://pymcio--881.org.readthedocs.build/projects/examples/en/881/case_studies/topological_posterior_predictive_checks.html

I also left some initial comments :)

[gsidoine]

Thanks again @juanitorduz for the review! :)

I pushed an update addressing the comments:

• removed the flagged sentence,
• added an intuitive explanation of homology and persistence,
• added a small visual-intuition diagram,
• added docstrings to the functions,
• added an appendix with a compact explanation of the boundary-operator view of homology,
• reran the notebook so the figures are included in the committed outputs,
• added the paired MyST file for the notebook,

I also cleaned the warning outputs from the rendered notebook, and the checks are now passed.

[juanitorduz]

Thank you @gsidoine this is a much better version! Can you please fix the notebook format via the pre-commit hook? (If you need help with that, please let me know).

I would also like a second pair of eyes from @maresb :)

[gsidoine]

Thanks again @juanitorduz and apologies for the delay in getting the pre-commit issue resolved.

I ran the pre-commit hook locally on the notebook, paired MyST file, and references file, then committed the generated formatting changes.

The local pre-commit run is now passing for black-jupyter, nbqa-isort, nbqa-pyupgrade, sequential notebook execution, bibtex-tidy, the notebook style checks, and jupytext.

The CI checks on the PR now appear to be passing as well

Let me know if you need any additional amendments on my end :)