Expose `hypergeometric_2F1` and `hypergeometric_3F2`

[spinkney]

These functions are in stan-math from from the PRs stan-dev/math#2792 and stan-dev/math#2797.

Let's expose them.

There is demand on the forums
https://discourse.mc-stan.org/t/gaussian-hypergeometric-function-for-exact-distribution-of-a-correlation/30606/3
https://discourse.mc-stan.org/t/hypergeometric-functions/252
https://discourse.mc-stan.org/t/confluent-hypergeometric-functions-to-estimate-population-size-and-detection-probability-from-spatially-replicated-counts/28758 (1F1 but still...)

[WardBrian]

Exposing these should be easy if you can provide the list of supported signatures

[spinkney]

@andrjohns, I don't see a rev version of hypergeometric_3F2 so we probably shouldn't expose that now. I also see that hypergeometric_pFq has a comment about not being exposed to users but I think it could be useful. What are your thoughts on that?

At the end, I believe we just have hypergeometric_2F1 which is quite a useful function.

A couple of questions for @andrjohns:

• Does this function accept complex arguments? Mathematically, it is able but not sure that is built out.
• We do not have apply_* to for vectorization so the signatures for hypergeometric_2F1 are
  a real or int
b real or int
c real or int
z real or int
• We need to handle the following restrictions in the function to reject and document this

a	arbitrary
b	Must be greater 0
c	Must be greater than b if |z| < 1, and c > b + a if z = 1
z	|z| <= 1

[WardBrian]

More forum requests: https://discourse.mc-stan.org/t/how-to-use-stan-hypergeometric-2f1-in-stan/33840

[ChrisHIV]

+1 motivation: the 2F_1 plays a core role in cluster trials. Say that individuals within a given cluster have a probability p for some outcome (e.g. disease), scaled by a factor t if they receive some treatment (e.g. vaccination), with p being Beta distributed between clusters. The marginal probability for getting the outcome in r_t out of n_t treated individuals and in r_u out of n_u untreated individuals is
\int_{p=0}^1 Binom(r_t | n_t, p t) Binom(r_u | n_u, p) Beta(p | alpha, beta) dp
which is proportional to 2F1(...; t).

[ChrisHIV]

Sorry for being dim Brian: I don't understand how to implement your suggestion here, which links to here, which refers to https://mc-stan.org/math/ more generally. I think I just need to put your user_header.hpp somewhere on my system (where?) and then compile my stan model manually (instead of my usual rstan::stan_model() command).
Exposure within Stan would be very useful regardless as I'd like to include this within an r package for others to use, which I doubt is possible with the manual headers approach.

[WardBrian]

Hi Chris -- the instructions there were for a cmdstan user. RStan does support the same functionality with a few of the details changed https://mc-stan.org/rstan/articles/external.html

[WardBrian]

@andrjohns could you answer @spinkney's questions on the supported signatures for these functions?

[andrjohns]

@andrjohns could you answer @spinkney's questions on the supported signatures for these functions?

Can do!

Now that this Math PR has landed, pretty much all of the existing hypergeometric functions are ready to go (hypergeometric_3F2 also delegates to hypergeometric_pFq for autodiff types IIRC):

• hypergeometric_1F0(real, real)
• hypergeometric_2F1(real, real, real, real)
• hypergeometric_3F2(vector, vector, real)
• hypergeometric_pFq(vector, vector, real)

All of the functions have convergence checking like the rules mentioned above (the Math library already had dedicated check_2F1_converges and check_3F2_converges functions)

I also want to get back to the hypergeometric_1F1 and log_hypergeometric_1F1 functions at some point

[WardBrian]

@andrjohns is the hypergeometric_1F0 function intentionally spelled with a lower-case f in the math source code?

I also can't find any rev code for hypergeometric_3F2, and I am having trouble getting several of the others to compile when generated by the compiler -- I suspect they may be missing a template bound or something and it's using the wrong overload. For example, testing hypergeometric_2F1(real, real, real, real) with all data is yielding

stan/lib/stan_math/stan/math/rev/fun/hypergeometric_2F1.hpp:41:27: error: cannot convert ‘stan::math::var_value<double>’ to ‘stan::return_type_t<double, double, double, double>’ {aka ‘double’} in return

[andrjohns]

@andrjohns is the hypergeometric_1F0 function intentionally spelled with a lower-case f in the math source code?

Ack, no it's not - I'll get that fixed!

I also can't find any rev code for hypergeometric_3F2

That should just be delegating to hypergeometric_pFq

For example, testing hypergeometric_2F1(real, real, real, real) with all data is yielding

Oh bizarre, when you say 'all data' does that mean all doubles? Since that signature should be covered by the prim tests

[andrjohns]

It looks like the mix tests for hypergeometric_2F1 aren't using the AD framework and there aren't any rev tests. Odd.

I'll add tests and see if anything breaks

[andrjohns]

mix tests for hypergeometric_2F1 with the AD testing framework all compile without issue for me