ENH: stats: add noncentral hypergeometric distributions (Fisher's and Wallenius')

.gitignore

@@ -270,6 +270,8 @@ scipy/stats/mvnmodule.c
 scipy/stats/statlibmodule.c
 scipy/stats/vonmises_cython.c
 scipy/stats/_stats.c
+scipy/stats/biasedurn.cxx
+scipy/stats/biasedurn.pyx
 scipy/stats/_sobol.c
 scipy/version.py
 scipy/special/_exprel.c

doc/source/dev/contributor/adding_new/new_stats_distribution.rst.inc

@@ -73,6 +73,10 @@ Implementation
    list in
    `scipy/stats/_distr_params.py <https://github.com/scipy/scipy/blob/master/scipy/stats/_distr_params.py#L5>`_.
    These shape parameters are used both for testing and automatic documentation generation.
+#. Add the name and an _invalid_ set of example shape parameters to the
+   list in ``invdistcont``, also in
+   `_distr_params.py <https://github.com/scipy/scipy/blob/master/scipy/stats/_distr_params.py>`_.
+   These shape parameters are also used for testing.
 #. Add a ``TestSquirrel`` class and any specific tests to
    `scipy/stats/tests/test_distributions.py <https://github.com/scipy/scipy/blob/master/scipy/stats/tests/test_distributions.py>`_.
 #. Run and pass(!) the tests.
@@ -94,4 +98,4 @@ References
 .. [JKB] Johnson, Kotz, and Balakrishnan, "Continuous Univariate Distributions, Volume 1", Second Edition, John Wiley and Sons,
            p. 173 (1994).
 
-.. _WikipediaDistributions: https://en.wikipedia.org/wiki/List_of_probability_distributions
+.. _WikipediaDistributions: https://en.wikipedia.org/wiki/List_of_probability_distributions

doc/source/tutorial/stats.rst

@@ -100,8 +100,7 @@ introspection:
     >>> print('number of continuous distributions: %d' % len(dist_continu))
     number of continuous distributions: 102
     >>> print('number of discrete distributions:   %d' % len(dist_discrete))
-    number of discrete distributions:   17
-
+    number of discrete distributions:   19
 
 Common methods
 ^^^^^^^^^^^^^^

doc/source/tutorial/stats/discrete.rst

@@ -264,6 +264,8 @@ Discrete Distributions in `scipy.stats`
    discrete_geom
    discrete_nbinom
    discrete_hypergeom
+   discrete_nchypergeom_fisher
+   discrete_nchypergeom_wallenius
    discrete_nhypergeom
    discrete_zipf
    discrete_zipfian

doc/source/tutorial/stats/discrete_nchypergeom_fisher.rst

@@ -0,0 +1,52 @@
+
+.. _discrete-nchypergeom-fisher:
+
+Fisher's Noncentral Hypergeometric Distribution
+===============================================
+
+A random variable has Fisher's Noncentral Hypergeometric distribution with
+parameters
+
+:math:`M \in {\mathbb N}`,
+:math:`n \in [0, M]`,
+:math:`N \in [0, M]`,
+:math:`\omega > 0`,
+
+if its probability mass function is given by
+
+.. math::
+
+    p(x; M, n, N, \omega) = \frac{\binom{n}{x}\binom{M - n}{N-x}\omega^x}{P_0},
+
+for
+:math:`x \in [x_l, x_u]`,
+where
+:math:`x_l = \max(0, N - (M - n))`,
+:math:`x_u = \min(N, n)`,
+
+.. math::
+
+    P_k = \sum_{y=x_l}^{x_u} \binom{n}{y} \binom{M - n}{N-y} \omega^y y^k,
+
+and the binomial coefficients are
+
+.. math::
+
+    \binom{n}{k} \equiv \frac{n!}{k! (n - k)!}.
+
+Other functions of this distribution are
+
+.. math::
+   :nowrap:
+
+    \begin{eqnarray*}
+    \mu & = & \frac{P_0}{P_1},\\
+    \mu_{2} & = & \frac{P_2}{P_0} - \left(\frac{P_1}{P_0}\right)^2,\\
+    \end{eqnarray*}
+
+References
+----------
+-  Agner Fog, "Biased Urn Theory", https://cran.r-project.org/web/packages/BiasedUrn/vignettes/UrnTheory.pdf
+-  "Fisher's noncentral hypergeometric distribution", Wikipedia, https://en.wikipedia.org/wiki/Fisher's_noncentral_hypergeometric_distribution
+
+Implementation: `scipy.stats.nchypergeom_fisher`

doc/source/tutorial/stats/discrete_nchypergeom_wallenius.rst

@@ -0,0 +1,42 @@
+
+.. _discrete-nchypergeom-wallenius:
+
+Wallenius' Noncentral Hypergeometric Distribution
+=================================================
+
+A random variable has Wallenius' Noncentral Hypergeometric distribution with
+parameters
+
+:math:`M \in {\mathbb N}`,
+:math:`n \in [0, M]`,
+:math:`N \in [0, M]`,
+:math:`\omega > 0`,
+
+if its probability mass function is given by
+
+.. math::
+
+    p(x; N, n, M) = \binom{n}{x} \binom{M - n}{N-x}\int_0^1 \left(1-t^{\omega/D}\right)^x\left(1-t^{1/D}\right)^{N-x} dt
+
+for
+:math:`x \in [x_l, x_u]`,
+where
+:math:`x_l = \max(0, N - (M - n))`,
+:math:`x_u = \min(N, n)`,
+
+.. math::
+
+    D = \omega(n - x) + ((M - n)-(N-x)),
+
+and the binomial coefficients are
+
+.. math::
+
+    \binom{n}{k} \equiv \frac{n!}{k! (n - k)!}.
+
+References
+----------
+-  Agner Fog, "Biased Urn Theory", https://cran.r-project.org/web/packages/BiasedUrn/vignettes/UrnTheory.pdf
+-  "Wallenius' noncentral hypergeometric distribution", Wikipedia, https://en.wikipedia.org/wiki/Wallenius'_noncentral_hypergeometric_distribution
+
+Implementation: `scipy.stats.nchypergeom_wallenius`

scipy/stats/__init__.py

@@ -174,23 +174,25 @@
 .. autosummary::
    :toctree: generated/
 
-   bernoulli         -- Bernoulli
-   betabinom         -- Beta-Binomial
-   binom             -- Binomial
-   boltzmann         -- Boltzmann (Truncated Discrete Exponential)
-   dlaplace          -- Discrete Laplacian
-   geom              -- Geometric
-   hypergeom         -- Hypergeometric
-   logser            -- Logarithmic (Log-Series, Series)
-   nbinom            -- Negative Binomial
-   nhypergeom        -- Negative Hypergeometric
-   planck            -- Planck (Discrete Exponential)
-   poisson           -- Poisson
-   randint           -- Discrete Uniform
-   skellam           -- Skellam
-   yulesimon         -- Yule-Simon
-   zipf              -- Zipf (Zeta)
-   zipfian           -- Zipfian
+   bernoulli                -- Bernoulli
+   betabinom                -- Beta-Binomial
+   binom                    -- Binomial
+   boltzmann                -- Boltzmann (Truncated Discrete Exponential)
+   dlaplace                 -- Discrete Laplacian
+   geom                     -- Geometric
+   hypergeom                -- Hypergeometric
+   logser                   -- Logarithmic (Log-Series, Series)
+   nbinom                   -- Negative Binomial
+   nchypergeom_fisher       -- Fisher's Noncentral Hypergeometric
+   nchypergeom_wallenius    -- Wallenius's Noncentral Hypergeometric
+   nhypergeom               -- Negative Hypergeometric
+   planck                   -- Planck (Discrete Exponential)
+   poisson                  -- Poisson
+   randint                  -- Discrete Uniform
+   skellam                  -- Skellam
+   yulesimon                -- Yule-Simon
+   zipf                     -- Zipf (Zeta)
+   zipfian                  -- Zipfian
 
 An overview of statistical functions is given below.  Many of these functions
 have a similar version in `scipy.stats.mstats` which work for masked arrays.