# Fast evaluation of multivariate normal distributions
This package provides a fast way to evaluate the pdf and cdf of a standardized multivariate normal distribution. Currently, it only contains code for the bivariate normal distribution.
The implementation in this package is based on the following references:
1. Drezner, Zvi, and George O. Wesolowsky. "On the computation of the bivariate normal integral." Journal of Statistical Computation and Simulation 35.1-2 (1990): 101-107.
2. Genz, Alan, and Frank Bretz. "Computation of multivariate normal and t probabilities." Lecture Notes in Statistics 195 (2009)
Simply put, the method comes down to an interpolation specifically tailored to the multivariate normal distribution.
Although it is an approximation, the method is near to exact and fast.
The implementation in Scipy is based on the same methodology, see [here](https://github.com/scipy/scipy/blob/v1.13.0/scipy/stats/mvndst.f) and [here](https://github.com/scipy/scipy/blob/v1.13.0/scipy/stats/_qmvnt.py.
With scalar input, the speed is comparable to the Scipy implementation.
The Scipy implemantation, however, is slow for vector valued input. This packages containes a vectorized implementation which is signficantly faster albeit still slower than a native C implementation such as the one in the [approxcdf](https://github.com/david-cortes/approxcdf) package.
The advantage of this package is that it is pure Python and does not require any (build) dependencies.
Rough findings for speed improvements compared to the Scipy implementation.
| Module | Correlation | Speed improvement single | Speed improvement vectorized
| --- | --- | --- | --- |
| fastnorm | abs < 0.925 | >1000 x faster than Scipy | 10 x faster than Scipy|
| approxcdf | abs < 0.925 | >1000 x faster than Scipy| 10 x faster than Scipy|
| fastnorm | abs > 0.925 | >1000 x faster than Scipy| 3 x faster than Scipy|
| approxcdf | abs > 0.925 | >1000 x faster than Scipy| 10 x faster than Scipy|
These finds are based on an average of 100 runs and can be reproduced by running the `example.py` script.
## Basic example
```python
import fastnorm as fn
correl = 0.5
x=[1,1]
fn.bivar_norm_pdf(x, correl)
fn.bivar_norm_cdf(x, correl)
x=[[1,1],[2,2]]
fn.bivar_norm_pdf(x, correl)
fn.bivar_norm_cdf(x, correl)
```
## Installation
To install from PyPI:
```bash
pip install fastnorm
```
To install the latest development version from github:
```bash
pip install git+https://github.com/mvds314/fastnorm.git
```
## Development
For development purposes, clone the repo:
```bash
git clone https://github.com/mvds314/fastnorm.git
```
Then navigate to the folder containing `setup.py` and run
```bash
pip install -e .
```
to install the package in edit mode.
Run unittests with `pytest`.
## Roadmap
- Add support for the trivariate and quadrivariate normal distribution.
- Add support for the higher dimensional normal distribution.
- Maybe extend to the multivariate t-distribution.
## Related software
- [approxcdf](https://github.com/david-cortes/approxcdf)
- [Matlab implementations](https://www.math.wsu.edu/faculty/genz/software/software.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/mvds314/fastnorm",
"name": "fastnorm",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "statistics",
"author": "Martin van der Schans",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6b/15/daaa5c954e594b4f85274834ccbd9a27cd64a1388df39f186a6e28a42d51/fastnorm-24.4.2.tar.gz",
"platform": null,
"description": "# Fast evaluation of multivariate normal distributions\n\nThis package provides a fast way to evaluate the pdf and cdf of a standardized multivariate normal distribution. Currently, it only contains code for the bivariate normal distribution.\n\nThe implementation in this package is based on the following references:\n\n1. Drezner, Zvi, and George O. Wesolowsky. \"On the computation of the bivariate normal integral.\" Journal of Statistical Computation and Simulation 35.1-2 (1990): 101-107.\n2. Genz, Alan, and Frank Bretz. \"Computation of multivariate normal and t probabilities.\" Lecture Notes in Statistics 195 (2009)\n\nSimply put, the method comes down to an interpolation specifically tailored to the multivariate normal distribution.\nAlthough it is an approximation, the method is near to exact and fast.\nThe implementation in Scipy is based on the same methodology, see [here](https://github.com/scipy/scipy/blob/v1.13.0/scipy/stats/mvndst.f) and [here](https://github.com/scipy/scipy/blob/v1.13.0/scipy/stats/_qmvnt.py.\n\nWith scalar input, the speed is comparable to the Scipy implementation.\nThe Scipy implemantation, however, is slow for vector valued input. This packages containes a vectorized implementation which is signficantly faster albeit still slower than a native C implementation such as the one in the [approxcdf](https://github.com/david-cortes/approxcdf) package.\nThe advantage of this package is that it is pure Python and does not require any (build) dependencies.\n\nRough findings for speed improvements compared to the Scipy implementation.\n| Module | Correlation | Speed improvement single | Speed improvement vectorized\n| --- | --- | --- | --- |\n| fastnorm | abs < 0.925 | >1000 x faster than Scipy | 10 x faster than Scipy|\n| approxcdf | abs < 0.925 | >1000 x faster than Scipy| 10 x faster than Scipy|\n| fastnorm | abs > 0.925 | >1000 x faster than Scipy| 3 x faster than Scipy|\n| approxcdf | abs > 0.925 | >1000 x faster than Scipy| 10 x faster than Scipy|\n\nThese finds are based on an average of 100 runs and can be reproduced by running the `example.py` script.\n\n## Basic example\n\n```python\nimport fastnorm as fn\ncorrel = 0.5\n\nx=[1,1]\nfn.bivar_norm_pdf(x, correl)\nfn.bivar_norm_cdf(x, correl)\n\nx=[[1,1],[2,2]]\nfn.bivar_norm_pdf(x, correl)\nfn.bivar_norm_cdf(x, correl)\n```\n\n## Installation\n\nTo install from PyPI:\n\n```bash\npip install fastnorm\n```\n\nTo install the latest development version from github:\n\n```bash\npip install git+https://github.com/mvds314/fastnorm.git\n```\n\n## Development\n\nFor development purposes, clone the repo:\n\n```bash\ngit clone https://github.com/mvds314/fastnorm.git\n```\n\nThen navigate to the folder containing `setup.py` and run\n\n```bash\npip install -e .\n```\n\nto install the package in edit mode.\n\nRun unittests with `pytest`.\n\n## Roadmap\n\n- Add support for the trivariate and quadrivariate normal distribution.\n- Add support for the higher dimensional normal distribution.\n- Maybe extend to the multivariate t-distribution.\n\n## Related software\n\n- [approxcdf](https://github.com/david-cortes/approxcdf)\n- [Matlab implementations](https://www.math.wsu.edu/faculty/genz/software/software.html)\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Fast evaluation of multivariate normal distribution",
"version": "24.4.2",
"project_urls": {
"Homepage": "https://github.com/mvds314/fastnorm"
},
"split_keywords": [
"statistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b18378fcd76ab95aa0bc446034394dfb33d89aa7fefa2d497486fc6fbd6c05ce",
"md5": "895f60f154039dbe1bcb2dde336c5f41",
"sha256": "7214067a15cf1ec939f2af1739cee2d4d8174f9af4634101e9e8f299b9816e4e"
},
"downloads": -1,
"filename": "fastnorm-24.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "895f60f154039dbe1bcb2dde336c5f41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8242,
"upload_time": "2024-04-28T15:15:13",
"upload_time_iso_8601": "2024-04-28T15:15:13.186619Z",
"url": "https://files.pythonhosted.org/packages/b1/83/78fcd76ab95aa0bc446034394dfb33d89aa7fefa2d497486fc6fbd6c05ce/fastnorm-24.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6b15daaa5c954e594b4f85274834ccbd9a27cd64a1388df39f186a6e28a42d51",
"md5": "ff432d2336aabdd9144c97f550c1acda",
"sha256": "187c62a5e3a75ab902304046d1331e7a79e477223b18a88e78f27e2a69027673"
},
"downloads": -1,
"filename": "fastnorm-24.4.2.tar.gz",
"has_sig": false,
"md5_digest": "ff432d2336aabdd9144c97f550c1acda",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7424,
"upload_time": "2024-04-28T15:15:14",
"upload_time_iso_8601": "2024-04-28T15:15:14.163781Z",
"url": "https://files.pythonhosted.org/packages/6b/15/daaa5c954e594b4f85274834ccbd9a27cd64a1388df39f186a6e28a42d51/fastnorm-24.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-28 15:15:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mvds314",
"github_project": "fastnorm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fastnorm"
}
JSON
