Add multivariate hypergeometric distribution

[Michael-Howes]

Overview

This pull requests adds the multivariate hypergeometric distribution. This is a generalization of the hypergeometric distribution. It includes:

• The file src/multivariate/mvhypergeometric.jl that implements MvHypergeometric as a subtype of DiscreteMultivariateDistribution.
• The file src/samplers/mvhypergeometric.jl that implements sampling.
• A test file test/multivariate/mvhypergeometric.jl.
• The documentation file docs/src/multivariate.md is also updated.

Motivation

The multivariate hypergeometric distribution is an important distribution in statistics for testing independence in contingency tables. It is implemented in the numpy and scipy Python packages but currently it is not supported in Distributions.jl.

Implementation details

The type MvHypergeometric is created as a subtype of DiscreteMultivariateDistribution. Functions for the mean, variance and covariance matrix are implemented. Evaluation of the log pdf and sampling are also implemented. Sampling is implemented in the file scr/samplers/mvhypergeom.jl. The procedure is analogous to sampling from a multinomial distribution. The entries are sampled sequentially from univariate hypergeometric distributions.

Testing

Tests are include in test/multivariate/mvherpgeom.jl. The statistics, pdf and sampling are all tested. The pdf is also compared to the pdf of the hypergeometric distribution. Specifically, the marginal and conditional distributions of the multivariate hypergeometric are univariate hypergeometric (as used in the sampling).

Dependencies

No new dependencies are added.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.46%. Comparing base (0421b18) to head (afe12d1).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1963      +/-   ##
==========================================
+ Coverage   86.36%   86.46%   +0.10%     
==========================================
  Files         146      147       +1     
  Lines        8786     8852      +66     
==========================================
+ Hits         7588     7654      +66     
  Misses       1198     1198              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[devmotion]

Julia docstrings should contain the type or function signature in the first line, indented by four spaces.

Generally, could you make this docstring consistent with docstrings of other existing distribution types?

[Michael-Howes]

I've added the function signature. The doc string is based on the multinomial distribution docstring. Is there a different distribution I should be following?

https://github.com/JuliaStats/Distributions.jl/blob/0421b1890c49417de993b255f6b177a1cb93fca3/src/multivariate/multinomial.jl

[Michael-Howes]

@devmotion Thank you for the review. I have resolved most of them but left two open (one about documentation, another about computing the covariance matrix). The PR is ready for a second round of review. Thanks again.