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 scr/multivariate/mvhypergeom.jl that implements MvHypergeom as a subtype of DiscreteMultivariateDistribution.
• The file scr/samplers/mvhypergeom.jl that implements sampling.
• A test file test/multivariate/mvherpgeom.jl.

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, for 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

Attention: Patch coverage is 97.84946% with 2 lines in your changes missing coverage. Please review.

Project coverage is 86.38%. Comparing base (d666acb) to head (91d9da5).

Files with missing lines	Patch %	Lines
src/samplers/mvhypergeometric.jl	92.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1963      +/-   ##
==========================================
+ Coverage   86.26%   86.38%   +0.12%     
==========================================
  Files         146      148       +2     
  Lines        8765     8858      +93     
==========================================
+ Hits         7561     7652      +91     
- Misses       1204     1206       +2     

☔ 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.