descriptive error messages for incomplete probability library calls

[bob-carpenter]

Description

Our probability-distribution functions come in familes, e.g., normal_X(), where X can be any of
lpdf, lupdf, cdf, lcdf, lccdf, rng. But not all probability distributions implement each expected probability function. When a user calls foo_X for a probability distribution foo that exists, but foo_X doesn't exist, we should have a more specific message informing them of that so they don't think they've made a typo or waste time looking in the doc.

Motivation

Quoted from @betanalpha's comment stan-dev/design-docs#42 (comment):

Most of the probability libraries in R, Python, Mathematica, etc have a pretty uniform coverage of the exposed representations. One you know the name of a family of distributions you know how to call the corresponding density, CDF, quantile function, rng, etc. At the point the coverage in Stan is pretty uniform, but it’s becoming less and less uniform as more obscure families are added without all of the functionality. If a user is assuming that everything will be uniformly available but gets an error message then can become frustrating assuming that there’s a spelling error or other typo somewhere and not just a non-implemented functionality.

It would be great to add functionality to the compiler to fill in these gaps so that if a user calls for some functionality that has not yet been implemented then they get a precise error message noting that gap and not the default error message noting the the function being requested just doesn’t exist.

[WardBrian]

Is the idea that these enhanced error messages occur for any X when foo_X is requested, or only when X is one of the existing kinds (rng, lpdf, etc)?

Phrased another way, would "normal_weird" warn me that the normal family doesn't support "_weird", or would it just give the current warning about unknown identifier? I think this ends up determining what information we'd need to store to produce these

[nhuurre]

No reason to speculate about unknown suffixes.
All we need is that mk_declarative_sig should record the missing names somewhere. (that includes _lpmf for continuous distributions and _lpdf for discrete ones) (but ignore UnaryVectorized)

stanc3/src/middle/Stan_math_signatures.ml

Lines 141 to 149 in 17dd97b

	let mk_declarative_sig (fnkinds, name, args, mem_pattern) =
	let sfxes = function
	| Lpmf -> ["_lpmf"; "_log"]
	| Lpdf -> ["_lpdf"; "_log"]
	| Rng -> ["_rng"]
	| Cdf -> ["_cdf"; "_cdf_log"; "_lcdf"]
	| Ccdf -> ["_ccdf_log"; "_lccdf"]
	| UnaryVectorized -> [""]
	in

[WardBrian]

I'm not even sure if we'd need that, would

1. Does this function exist (which we do right now)
2. If not, does it have one of the special suffixes
3. If so, report this new error, else report the current error

work?

[nhuurre]

I think it makes sense to distinguish between a totally unknown distribution and "this distribution family is known but the specific suffix is not supported" but it depends on the exact phrasing of the new error message.

[WardBrian]

That's probably better. We just need a list of known families and a list of known suffixes at that point. I don't think we need to explicitly construct the matrix of which suffixes are available for which families however, given those two lists and our existing list of available functions we can very quickly determine whether or not we are in this situation.

roughly

if (is_undefined ident) then
  if (is_known_family (remove_suffix ident)) && (is_known_suffix (get_suffix ident)) then
    (*special error*)
  else
    (* current error *)

I'll have to look but I know we already have a lot of utilities for getting or removing the suffixes in the code

[nhuurre]

I don't think we need to explicitly construct the matrix of which suffixes are available for which families

True enough. It just seems that Stan_math_signatures.ml currently prefers constructing explicit matrices. Issue #324 has been open for quite a while.

[betanalpha]

That's probably better. We just need a list of known families and a list of known suffixes at that point

Yeah, this was the intention of my original suggestion. In psuedo-code something like if ( !implemented(“family_suffix) ) if ( standard(“family_suffix”) ) error(“family_suffix has not yet been implemented”); else error(“The function signature family_suffix does not exist”); // or whatever the current error message is There are many possibilities for expanding on the error message, for example using the request suffix to update to something more readable like “The CDF for the <family> family has not yet been implemented.” The basic suffixes would be lpdf or lpmf, cdf, ccdf, and rng, and then perhaps also qf based on the current design-doc discussion. Fixing lpdf or lpmf based no whether the family is discrete or continuous might be a pain.