Add examples explaining advanced applications of sample_posterior_predictive

[ricardoV94]

This is still a draft. I want to add two more examples first about the default ppc and predictions use-cases

Related to #7069

TODO

• Add example about common use for in-sample posterior_predictive
• Add example about common use for predictions
• Add examples on using new models
• Change conclusion about non-dependence on deterministics or fix behavior
• Explain volatility when MutableData changes I think this is itself a mine-field and I would rather change the behavior first

Link to function docs preview: https://pymcio--7014.org.readthedocs.build/projects/docs/en/7014/api/generated/pymc.sampling.forward.sample_posterior_predictive.html

---

📚 Documentation preview 📚: https://pymc--7014.org.readthedocs.build/en/7014/

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.24%. Comparing base (6c6fd13) to head (08fca4e).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7014   +/-   ##
=======================================
  Coverage   92.24%   92.24%           
=======================================
  Files         100      100           
  Lines       16887    16887           
=======================================
  Hits        15577    15577           
  Misses       1310     1310           

Files	Coverage Δ
pymc/sampling/forward.py	95.90% <ø> (ø)

[jessegrabowski]

Last suggestion, getting into the weeds of personal preferences -- I think the API docs would look nicer if you added a title (in bold or italics or w/e) to each of the two examples.

I also think the code in the new section would be easier to follow if you split the model definition plus each function call into a separate code block and wrote your commentary as text instead of code comments.

[ricardoV94]

Last suggestion, getting into the weeds of personal preferences -- I think the API docs would look nicer if you added a title (in bold or italics or w/e) to each of the two examples.

I also think the code in the new section would be easier to follow if you split the model definition plus each function call into a separate code block and wrote your commentary as text instead of code comments.

I agree, even better would be a markdown header, but I don't know if that's supported :D

[jessegrabowski]

I think you can use restructuredtext subsubsection headings, like:

Example 1: Exploring the effect of var_names on outputs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

See here. It's pretty hideous for viewing in an IDE, though.

[ricardoV94]

That worked @jessegrabowski

[OriolAbril]

Given this is called default behaviour, I would make it pm.sample_posterior_predictive(idata) nothing else.

[ricardoV94]

I think this helps understanding how the behavior changes when you start playing with it the kwarg

[AlexAndorra]

Thanks @ricardoV94 , these clarifications are very much welcome!

I want to add two more examples first about the default ppc and predictions use-cases

Seems like default ppc is done and you only need predictions use-case?

[ricardoV94]

I have addressed several review comments:

• Do not call new draws posterior predictive draws, but add a note for the first case where it is equivalent
• Fix the Deterministics example

I also expanded with two new example sections:

• Posterior predictive checks and predictions: Shows the common use case
• Using new models: Shows how you can use a new model with new variables

It's ready for review again. It is also likely I messed up the myst formatting so any help appreciated.

[AlexAndorra]

Love it @ricardoV94 ! Just suggested a few changes, then good to merge

[ricardoV94]

@AlexAndorra thanks for the review and suggestions. I've addressed them

[AlexAndorra]

All good, thanks @ricardoV94 🥳
Just waiting for an answer to solve link formatting -- and took the opportunity to add a nit 😜

[AlexAndorra]

Now that we have to wait for Oriol's answer on the extrernal link before merging, let me add a nit 🙈
I don't think it'll be super clear to all users that z depends on det_xy, because it looks like it only depends on x and y .
If you did this: z = pm.Normal("z", det_xy), that'd probably be clearer. Not a big deal, just my 2 cents

[ricardoV94]

That's what I actually wanted to do! Wonder if the bug comes bug up... xD

[AlexAndorra]

Ah ok! Then that makes more sense

[ricardoV94]

It shows the bug again! I added a separate commit that includes a danger section

[ricardoV94]

Opened an issue: #7183

[ricardoV94]

Things seem to be working. @AlexAndorra wanna do one last pass?

[AlexAndorra]

All good now @ricardoV94 🍾