Add introduction section to Transformations API page to document role of Transforms

[mkusnetsov]

Description

This PR adds an introduction section to the Transformations API page to:

• explain the principal purpose of transforms
• warn that most users don't need to play with these and that most attempts to do so don't do what users tend to think
• provide some guidance on when tweaking transforms may be appropriate and what other options user have when wanting to deal with transformed random variables

In addition this PR:

• removes a seemingly incorrect deprecation comment next to the ordered transform (I think it was accidentally left over from when univariate_ordered was deprecated)
• removes mention of SumsTo1, which is being deprecated
• organises instance and class names in the autosummary to
  1. alphebtize them, and
  2. add missing class names for the included instances

This PR assumes that the issue #5674 is closed (via PR #7207) to avoid extensive (and somewhat non-intuitive to casual user) guidance that will shortly be outdated

Related Issue

• Closes Document the role of transforms #7040
• Related to Ordered transform incompatible with constrained space transforms (ZeroSum, Simplex, etc.) #6975, Implement default_transform and transform argument for distributions #5674, Deprecate SumTo1 Transform #7009

Checklist

• Checked that the pre-commit linting/style checks pass
• Included tests that prove the fix is effective or that the new feature works
• Added necessary documentation (docstrings and/or example notebooks)
• If you are a pro: each commit corresponds to a relevant logical change

Type of change

• New feature / enhancement
• Bug fix
• Documentation
• Maintenance
• Other (please specify):

---

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

[welcome]

]
💖 Thanks for opening this pull request! 💖 The PyMC community really appreciates your time and effort to contribute to the project. Please make sure you have read our Contributing Guidelines and filled in our pull request template to the best of your ability.

[ricardoV94]

This explanation is absolutely incredible!

[ricardoV94]

Just a small suggestion, as you mentioned we will have both transform and default_transform after: #7207

All you said about default_transform is correct. When users want to add other constraints but not modify the default one, they should probably use the transform kwarg. Under the hood, we will build a ChainTransform, that applies the user provided transform on top of the default one.

[mkusnetsov]

Thanks, @ricardoV94! That's a good point - I pushed some changes to clarify transform kwarg as distinct from default_transform.

But I might be doing something wrong? Although I can see the commits and the changes, the preview documentation is still showing the original version, not the revised one... (I know it takes a while to re-build but it seems to be saying "Read the Docs build succeeded!")

[ricardoV94]

But I might be doing something wrong? Although I can see the commits and the changes, the preview documentation is still showing the original version, not the revised one... (I know it takes a while to re-build but it seems to be saying "Read the Docs build succeeded!")

It takes some time for the preview to update. I think it's correct now? https://pymcio--7232.org.readthedocs.build/projects/docs/en/7232/api/distributions/transforms.html

[ricardoV94]

I think this is perfect as is. I would just wait for the related PR to be merged, so that our docs are not "ahead of time"

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.30%. Comparing base (4f6831e) to head (f29112f).
Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7232   +/-   ##
=======================================
  Coverage   92.30%   92.30%           
=======================================
  Files         100      100           
  Lines       16895    16895           
=======================================
  Hits        15595    15595           
  Misses       1300     1300           

Files	Coverage Δ
pymc/distributions/transforms.py	98.47% <ø> (ø)

[mkusnetsov]

Thank you for the kind words! It is correct now, yes. Will know that it takes a while, in the future. And yes - it absolutely makes sense to wait for the other PR.

I left some open questions on the underlying issue. Are any of them worth pursuing either in a separate issue or a discussion? Just checking because I assume once that issue is closed they might get lost.

[OriolAbril]

I review docs related PRs quite sparsely if I have time and after seeing this one I wanted to add my praise too at use of rST, both at syntax level and conceptual level 😄 📚

Also, in case someone wonders, the fact that references to pymc.sample, pymc.sample_prior_predictive... are not (yet) rendered as links in the rtd preview is an issue with how those are documented, once that is fixed all cross-references here will work

[welcome]

]
Congrats on merging your first pull request! 🎉 We here at PyMC are proud of you! 💖 Thank you so much for your contribution 🎁

[ricardoV94]

Thanks a ton @mkusnetsov, don't hesitate in opening issues/PRs for other areas you find documentation to be lacking