Add PyMC-centric examples to commonly used `pm.math` functions

[ricardoV94]

Would be nice to add code-block examples that show how to use frequent pm.math functions with simple PyMC models in the docstrings:

• switch
• stack
• softmax
• ...

[ricardoV94]

CC @OriolAbril

[chritter]

I see that the math submodule is described by https://docs.pymc.io/en/v3/api/math.html. Functions such as pm.switch are not appearing in the submodule documentation because they are imported from aesara.tensor and hence there is no docstring where examples with PyMC models could be added. Could you provide advice on in which place you would like to see the examples?

General examples of the switch are in https://aesara.readthedocs.io/en/latest/library/tensor/basic.html.

[OriolAbril]

@chritter you are looking at the old docs. The math module is now correctly rendered in https://docs.pymc.io/en/latest/api/math.html. You can click on each function and see the complete docstrings imported from aesara. The goal of this issue is to add examples of using these functions within pymc. The switch for example is often used to break symmetries in models and there should be an example of this in the docstring (or a link to pymc examples of this).

I am also adding the sphinx label, because this will only be beginner friendly if you are already familiar with both sphinx and numpydoc.

[iykat]

Hi, this is my first time contributing to the pymc library. I am writing to experience my interest to work on this issue.

[rag9704]

@ricardoV94 , where to add examples?

[ricardoV94]

@ricardoV94 , where to add examples?

In here: https://github.com/pymc-devs/pymc/blob/main/docs/source/api/math.rst

[HarshvirSandhu]

@ricardoV94 @OriolAbril Is this still open? I'd like to work on this. Please let me know which pm.math functions have to be added