Doc string terminology for unnamed distributions created via .dist()

[cluhmann]

When updating the docstrings for pm.AR() distribution class (#6080), it became clear that we have no clean, unified way to refer to the "unnamed distribution" arguments taken by some distributions (e.g., time series, pm.Mixture, etc.). @ricardoV94 suggested adopting something like the "tensor_like" nomenclature used elsewhere. This issue is intended to start discussion about whether that's a good idea and, if so, what a good term might be. While we're at it, we might try and figure out if there are any other argument types that we might want to name.

[ricardoV94]

Just to be clear it has to be a distribution that has jot being registered in the model, which is therefore created with the .dist API.

The reason I called it unnamed is because that's the other characteristics change in signature. Variables registered in the model always require a name as the first argument, those via .dist do not.

If anyone can come with an intuitive succinct term, that would be really great.

[fonnesbeck]

When teaching I sometimes refer to them as "raw" distributions.

But really, one should just call them "distributions" and anything named should be a "random variable" (since that's what they are, and the distribution is an attribute). Might be too late to enforce that sort of terminology, however.

Just calling it a "dist" is another natural choice.

[OriolAbril]

The keyword to use is already defined and in use. It is Distribution. What should be discussed is where does its link point to.

It currently points to the api section for distributions but it could as well be a term in the glossary

[ricardoV94]

Perhaps a term in the glossary which then points to the API section for distributions?

[cluhmann]

Yeah, I think the linking is confusing as it is right now, because it seems to imply that objects with types that match any of the classes listed on the distributions documentation page would be valid arguments.

[OriolAbril]

I think it is also important to note that this only indicates the valid types. It doesn't mean that all the objects of such types are valid. To put a simpler example, the description for sigma says tensor_like of float and -1 matches that type but it is not a valid argument. Yet, this information is not on the type section but on the parameter description.

[cluhmann]

I actually hadn't realized that the types didn't differ. In the end, calling it a distribution, potentially having a glossary, and having informative error messages (in those places .dist() is required) will help provide some guardrails when someone tries to feed a named/registered variable when an unnamed variable is expected.

[ricardoV94]

informative error messages (in those places .dist() is required) will help provide some guardrails when someone tries to feed a named/registered variable when an unnamed variable is expected.

We have those. We call check_dist_not_registered or something.

[OriolAbril]

logging in the discussion that there is now an "unnamed distribution" term in the glossary: https://www.pymc.io/projects/docs/en/stable/glossary.html#term-unnamed_distribution