ENH: stats.unuran: add a higher level API

[tirthasheshpatel]

This adds a higher-level class called GenericGenerator which can be used to
create generators using UNU.RAN's String API. Currently, only strings are allowed
but it can be extended to accept a object containing a UNU.RAN distribution.

One can simply pass a string with the distribution to sample from and create a
generator:

>>> rng = GenericGenerator("normal")
>>> rvs = rng.rvs(100_000)

It is also possible to pass the method and its parameters as keyword arguments.

>>> rng = GenericGenerator("normal", method="tdr", domain=(-5, 5), c=0.,
...                        cpoints=(-4.5, -3.5, -2.5, 0.0, 2.5, 3.5, 4.5))
>>> rvs = rng.rvs(100_000)

It is also possible to change the parameters of the distribution. The below example
creates a samplers for the normal distribution with mean 6 and standard
deviation 4.25:

>>> rng = GenericGenerator("normal(6, 4.25)")

Advanced use case includes passing a custom distribution with methods coded as strings.

>>> rng = GenericGenerator("distr = cont; pdf = 'exp(-0.5 * x^2)'")
>>> rvs = rng.rvs(100_000)

@chrisb83 As you suggested, I have attempted to write a high-level API for UNU.RAN. Does this align with your ideas? In not, feel free to add suggestions or ask for changes. Better name to be decided :)
Also pinging @mckib2 in case you are interested in reviewing this.

[chrisb83]

Hi Tirth,

as we discussed in our meeting yesterday, we do not need to make the UNU.RAN distributions (the ones listed here: http://statmath.wu.ac.at/unuran/doc/unuran.html#Stddist_005fCONT) available in SciPy.

The suggestion would be to allow to access the different generation methods easily, e.g. GenericGenerator(dist, method='tdr', ...). dist is a distribution object that needs to have the required methods like pdf, dpdf etc. ... are all other keyword arguments, maybe there are a few common ones like domain, otherwise we can just put **kwargs.
We can then internally refer to the implemented approaches like TransformedDensityRejection. If we change the API of the sampling methods like TransformedDensityRejection to also accept dist as above, this should be pretty easy (I hope :)

[chrisb83]

typo: o -> of

[chrisb83]

maybe there are a few common ones like domain, otherwise we can just put **kwargs.

I just saw that it exactly what you did :)

[chrisb83]

The more I think about it, maybe we could even keep the access to the UNU.RAN distributions since you already wrote the code. In the end, it is a feature that is easy to use and maybe some users would like to rely on a different implementation, e.g. of the Gamma distribution. I could imagine that the UNU.RAN methods are quite a bit faster than the SciPy ones for large samples. Maybe this is a question we can ask on the mailing list?

[chrisb83]

Hi, this is definitely a nice simple interface that allows users to easily switch between the sampling methods. Let's briefly discuss on Saturday once more if we do not want to keep the code that allows to access the unuran distributions.

[tirthasheshpatel]

That sounds nice! I have been experimenting with a couple of things. So, it would be nice to discuss this once.