{"id":17880464,"url":"https://github.com/nstarman/mvgkde","last_synced_at":"2025-09-03T21:31:43.974Z","repository":{"id":259340923,"uuid":"877496787","full_name":"nstarman/mvgkde","owner":"nstarman","description":"MultiVariate Gaussian Kernel Density Estimation","archived":false,"fork":false,"pushed_at":"2024-10-24T03:52:18.000Z","size":327,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-24T15:59:37.416Z","etag":null,"topics":["kernel-density-estimation","multivariate-analysis"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mvgkde/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nstarman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-23T18:44:56.000Z","updated_at":"2024-10-24T05:39:30.000Z","dependencies_parsed_at":"2024-10-28T12:30:29.878Z","dependency_job_id":null,"html_url":"https://github.com/nstarman/mvgkde","commit_stats":null,"previous_names":["nstarman/mvgkde"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstarman%2Fmvgkde","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstarman%2Fmvgkde/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstarman%2Fmvgkde/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstarman%2Fmvgkde/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nstarman","download_url":"https://codeload.github.com/nstarman/mvgkde/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231823565,"owners_count":18431948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kernel-density-estimation","multivariate-analysis"],"created_at":"2024-10-28T12:14:36.747Z","updated_at":"2024-12-30T22:18:58.803Z","avatar_url":"https://github.com/nstarman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align='center'\u003e \u003ccode\u003emvgkde\u003c/code\u003e \u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eMultiVariate Gaussian Kernel Density Estimator in JAX.\u003c/h3\u003e\n\nThis is a micro-package, containing the single class `MultiVarGaussianKDE` (and\nhelper function `gaussian_kde`) to estimate the probability density function of\na multivariate dataset using a Gaussian kernel. This package modifies the\n`jax.scipy.stats.gaussian_kde` class (which is based on the\n`scipy.stats.gaussian_kde` class), but allows for full control over the\ncovariance matrix of the kernel, even per-dimension bandwidths. See the\nDocumentation below for more information.\n\n## Installation\n\n[![PyPI version][pypi-version]][pypi-link]\n[![PyPI platforms][pypi-platforms]][pypi-link]\n\n```bash\npip install mvgkde\n```\n\n## Documentation\n\n[![Actions Status][actions-badge]][actions-link]\n\nFor these examples we will use the following imports:\n\n```python\nimport jax.numpy as jnp\nimport jax.random as jr\nimport matplotlib.pyplot as plt\nimport numpy as np\n\nfrom mvgkde import MultiVariateGaussianKDE, gaussian_kde  # This package\n```\n\nAnd we will generate a dataset to work with:\n\n```python\nkey = jr.key(0)\ndataset = jr.normal(key, (2, 1000))\n```\n\nLastly we will define a plotting function:\n\n```python\n# Create a grid of points\n(xmin, ymin) = dataset.min(axis=1)\n(xmax, ymax) = dataset.max(axis=1)\nX, Y = np.mgrid[xmin:xmax:100j, ymin:ymax:100j]\npositions = np.vstack([X.ravel(), Y.ravel()])\n\n\ndef plot_kde(kde: MultiVariateGaussianKDE) -\u003e plt.Figure:\n    # Evaluate the KDE on the grid\n    Z = np.reshape(kde(positions).T, X.shape)\n\n    # Plot the results\n    fig, ax = plt.subplots()\n    ax.imshow(np.rot90(Z), cmap=plt.cm.gist_earth_r, extent=[xmin, xmax, ymin, ymax])\n    ax.plot(dataset[0], dataset[1], \"k.\", markersize=2)\n    ax.set(\n        title=\"2D Kernel Density Estimation using JAX\",\n        xlabel=\"X-axis\",\n        xlim=[xmin, xmax],\n        ylabel=\"Y-axis\",\n        ylim=[ymin, ymax],\n    )\n\n    return fig\n```\n\nHere's an example that can be done with `jax.scipy.stats.gaussian_kde`:\n\n```python\nkde = gaussian_kde(dataset, bw_method=\"scott\")\n\nfig = plot_kde(kde)\nplt.show()\n```\n\n![Scotts Rule](https://raw.githubusercontent.com/nstarman/mvgkde/main/docs/bw_scott.png)\n\nHere's an example with a per-dimension bandwidth. This is not possible with the\n`jax.scipy.stats.gaussian_kde`:\n\n```python\nkde = gaussian_kde(dataset, bw_method=jnp.array([0.15, 1.3]))\n\nfig = plot_kde(kde)\nplt.show()\n```\n\n![Per-Dimension Bandwidth](https://raw.githubusercontent.com/nstarman/mvgkde/main/docs/bw_perdim.png)\n\nLastly, here's an example with 2D bandwidth matrix:\n\n```python\nbw = jnp.array([[0.15, 3], [3, 1.3]])\nkde = gaussian_kde(dataset, bw_method=bw)\n\nfig = plot_kde(kde)\nplt.show()\n```\n\n![2D Bandwidth Matrix](https://raw.githubusercontent.com/nstarman/mvgkde/main/docs/bw_matrix.png)\n\nThe previous examples are using the convenience function `gaussian_kde`. This\nactually just calls the constructor method\n`MultiVariateGaussianKDE.from_bandwidth`. This function allows for customixing\nthe bandwidth factor on the data-driven covariance matrix, but does not allow\nfor specifying the covariance matrix directly. To do that, you can call the\n`MultiVariateGaussianKDE` constructor directly, or the `from_covariance`\nconstructor method. To illustrate the difference between modifying the bandwidth\nand setting the full covariance matrix, consider the following example:\n\n```python\nkde = MultiVariateGaussianKDE.from_covariance(\n    dataset,\n    jnp.array([[0.15, 0.1], [0.1, 1.3]]),\n)\n\nfig = plot_kde(kde)\nplt.show()\n```\n\n![Covariance Matrix](https://raw.githubusercontent.com/nstarman/mvgkde/main/docs/cov.png)\n\n## Acknowledgments\n\nThis package modifies code from [JAX](https://github.com/google/jax), which is\nlicensed under the Apache License 2.0.\n\n[actions-badge]: https://github.com/nstarman/mvgkde/workflows/CI/badge.svg\n[actions-link]: https://github.com/nstarman/mvgkde/actions\n[pypi-link]: https://pypi.org/project/mvgkde/\n[pypi-platforms]: https://img.shields.io/pypi/pyversions/mvgkde\n[pypi-version]: https://img.shields.io/pypi/v/mvgkde\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnstarman%2Fmvgkde","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnstarman%2Fmvgkde","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnstarman%2Fmvgkde/lists"}