| Name | spherediff JSON |
| Version |
1.2.1
JSON |
| download |
| home_page | |
| Summary | Sample from the diffusion kernel on any n-sphere |
| upload_time | 2023-06-05 07:32:11 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
diffusion
hypersphere
sampling
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SphereDiff
## Purpose
The purpose of this package is to sample from the isotropic diffusion kernel
on the surface of an n-dimensional unit sphere, where n is an arbitrary
natural number dimension greater than or equal to 3.
## Installation
### From a repository checkout
```bash
pip install --user .
```
### From PyPI
```bash
pip install --user spherediff
```
## Use
The user may sample from the isotropic Gaussian distribution on the unit
n-sphere using the `sample_spherical_kernel` function, which may be
imported as follows:
```
>> from spherediff.sample import sample_spherical_kernel
```
This function takes three arguments and one additional, optional argument.
The first is n, the dimension of the space in which the n-sphere is embedded.
The second is a numpy array of shape (N, n) consisting of the n-dimensional
unit vectors at which to center the distributions from which the samples are
to be generated. The third is a numpy array of shape (N,) consisting of the
scalar variance parameters of each distribution from which to generate
samples. The fourth is a boolean flag that determines whether sampling should
be done on the full surface of the n-sphere (if False) or on the hemisphere
with reflecting boundary conditions for the diffusion kernel.
Example output from `sample_spherical_kernel` is:
```
>>> import numpy as np
>>> from spherediff.sample import sample_spherical_kernel
>>> np.random.seed(42)
>>> means = np.random.randn(5, 3)
>>> means /= np.linalg.norm(means, axis=1, keepdims=True)
>>> means
array([[ 0.60000205, -0.1670153 , 0.78237039],
[ 0.97717133, -0.15023209, -0.15022156],
[ 0.86889694, 0.42224942, -0.25830898],
[ 0.63675162, -0.5438697 , -0.54658314],
[ 0.09351637, -0.73946664, -0.66666616]])
>>> vars = 0.1 * np.ones(5)
>>> sample_spherical_kernel(3, means, vars)
array([[ 0.30027556, -0.53104481, 0.79235472],
[ 0.91657116, -0.39288942, 0.07439905],
[ 0.81325411, 0.41495422, -0.40795926],
[ 0.39907791, -0.44171124, -0.80350981],
[ 0.16422958, -0.76019121, -0.62860001]])
>>> sample_spherical_kernel(3, means, vars, hemisphere=True)
array([[ 0.92723597, 0.02336567, 0.37374791],
[ 0.99421791, -0.03878944, -0.10013055],
[ 0.15771025, 0.6492883 , -0.74401087],
[ 0.2418101 , -0.41127436, -0.87885225],
[-0.11192408, -0.71437847, -0.69075061]])
```
The user may also compute the score function of the isotropic Gaussian
distribution on the unit n-sphere, defined as the Riemannian gradient
of the logarithm of the probability density. This may be done using the
`score_spherical_kernel` function, which may be imported as follows:
```
from spherediff.score import score_spherical_kernel
```
This function takes four arguments and one additional, optional argument.
The first is n, the dimension of the space in which the n-sphere is embedded.
The second is a numpy array of shape (N, n) consisting of the n-dimensional
unit vectors at which to evaluate the score function. The third is a numpy
array of shape (N, n) consisting of the n-dimensional unit vectors at which
to center the distributions of which the corresponding score functions will
be evaluated. The fourth is a numpy array of shape (N,) consisting of the
scalar variance parameters of each distribution. The fifth is a boolean
flag that determines whether the distributions of interest are supported
on the full surface of the n-sphere (if False) or on the hemisphere with
reflecting boundary conditions for the diffusion kernel.
Example output from `score_spherical_kernel` is:
```
>>> import numpy as np
>>> from spherediff.sample import sample_spherical_kernel
>>> from spherediff.score import score_spherical_kernel
>>> np.random.seed(42)
>>> means = np.random.randn(5, 3)
>>> means /= np.linalg.norm(means, axis=1, keepdims=True)
>>> means
array([[ 0.60000205, -0.1670153 , 0.78237039],
[ 0.97717133, -0.15023209, -0.15022156],
[ 0.86889694, 0.42224942, -0.25830898],
[ 0.63675162, -0.5438697 , -0.54658314],
[ 0.09351637, -0.73946664, -0.66666616]])
>>> vars = 0.1 * np.ones(5)
>>> x = sample_spherical_kernel(3, means, vars)
>>> x
array([[ 0.30027556, -0.53104481, 0.79235472],
[ 0.91657116, -0.39288942, 0.07439905],
[ 0.81325411, 0.41495422, -0.40795926],
[ 0.39907791, -0.44171124, -0.80350981],
[ 0.16422958, -0.76019121, -0.62860001]])
>>> score_spherical_kernel(3, x, means, vars)
array([[ 3.40175815, 3.11417869, 0.79800571],
[ 1.12626049, 2.20918798, -2.20878198],
[ 0.65201631, 0.12437106, 1.42627781],
[ 2.65653386, -1.32241858, 2.04638588],
[-0.69053884, 0.17827374, -0.39600546]])
>>> x = sample_spherical_kernel(3, means, vars, hemisphere=True)
>>> x
array([[ 0.92723597, 0.02336567, 0.37374791],
[ 0.99421791, -0.03878944, -0.10013055],
[ 0.15771025, 0.6492883 , -0.74401087],
[ 0.2418101 , -0.41127436, -0.87885225],
[-0.11192408, -0.71437847, -0.69075061]])
>>> score_spherical_kernel(3, x, means, vars, hemisphere=True)
array([[-1.74036155, -1.77246139, 4.42849462],
[-0.0852985 , -1.00528069, -0.45751298],
[ 2.51709283, 0.09916178, 0.62009298],
[ 4.08775888, -1.8186883 , 1.97580568],
[ 1.8912707 , -0.37819329, 0.08468239]])
```
Raw data
{
"_id": null,
"home_page": "",
"name": "spherediff",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "diffusion,hypersphere,sampling",
"author": "",
"author_email": "Rian Kormos <Rian.Kormos@ucsf.edu>",
"download_url": "https://files.pythonhosted.org/packages/26/cf/7f25cf5bc013d107cf5078738ee048e4008046c2d86708c21827acc6e07c/spherediff-1.2.1.tar.gz",
"platform": null,
"description": "# SphereDiff\n\n## Purpose\n\nThe purpose of this package is to sample from the isotropic diffusion kernel \non the surface of an n-dimensional unit sphere, where n is an arbitrary \nnatural number dimension greater than or equal to 3.\n\n## Installation\n\n### From a repository checkout\n\n```bash\npip install --user .\n```\n\n### From PyPI\n\n```bash\npip install --user spherediff\n```\n\n## Use\n\nThe user may sample from the isotropic Gaussian distribution on the unit \nn-sphere using the `sample_spherical_kernel` function, which may be \nimported as follows:\n\n```\n>> from spherediff.sample import sample_spherical_kernel\n```\n\nThis function takes three arguments and one additional, optional argument. \nThe first is n, the dimension of the space in which the n-sphere is embedded. \nThe second is a numpy array of shape (N, n) consisting of the n-dimensional \nunit vectors at which to center the distributions from which the samples are \nto be generated. The third is a numpy array of shape (N,) consisting of the \nscalar variance parameters of each distribution from which to generate \nsamples. The fourth is a boolean flag that determines whether sampling should \nbe done on the full surface of the n-sphere (if False) or on the hemisphere \nwith reflecting boundary conditions for the diffusion kernel.\n\nExample output from `sample_spherical_kernel` is:\n\n```\n>>> import numpy as np\n>>> from spherediff.sample import sample_spherical_kernel\n>>> np.random.seed(42)\n>>> means = np.random.randn(5, 3)\n>>> means /= np.linalg.norm(means, axis=1, keepdims=True)\n>>> means\narray([[ 0.60000205, -0.1670153 , 0.78237039],\n [ 0.97717133, -0.15023209, -0.15022156],\n [ 0.86889694, 0.42224942, -0.25830898],\n [ 0.63675162, -0.5438697 , -0.54658314],\n [ 0.09351637, -0.73946664, -0.66666616]])\n>>> vars = 0.1 * np.ones(5)\n>>> sample_spherical_kernel(3, means, vars)\narray([[ 0.30027556, -0.53104481, 0.79235472],\n [ 0.91657116, -0.39288942, 0.07439905],\n [ 0.81325411, 0.41495422, -0.40795926],\n [ 0.39907791, -0.44171124, -0.80350981],\n [ 0.16422958, -0.76019121, -0.62860001]])\n>>> sample_spherical_kernel(3, means, vars, hemisphere=True)\narray([[ 0.92723597, 0.02336567, 0.37374791],\n [ 0.99421791, -0.03878944, -0.10013055],\n [ 0.15771025, 0.6492883 , -0.74401087],\n [ 0.2418101 , -0.41127436, -0.87885225],\n [-0.11192408, -0.71437847, -0.69075061]])\n```\n\nThe user may also compute the score function of the isotropic Gaussian \ndistribution on the unit n-sphere, defined as the Riemannian gradient \nof the logarithm of the probability density. This may be done using the \n`score_spherical_kernel` function, which may be imported as follows:\n\n```\nfrom spherediff.score import score_spherical_kernel\n```\n\nThis function takes four arguments and one additional, optional argument. \nThe first is n, the dimension of the space in which the n-sphere is embedded. \nThe second is a numpy array of shape (N, n) consisting of the n-dimensional \nunit vectors at which to evaluate the score function. The third is a numpy \narray of shape (N, n) consisting of the n-dimensional unit vectors at which \nto center the distributions of which the corresponding score functions will \nbe evaluated. The fourth is a numpy array of shape (N,) consisting of the \nscalar variance parameters of each distribution. The fifth is a boolean \nflag that determines whether the distributions of interest are supported \non the full surface of the n-sphere (if False) or on the hemisphere with \nreflecting boundary conditions for the diffusion kernel.\n\nExample output from `score_spherical_kernel` is:\n\n```\n>>> import numpy as np\n>>> from spherediff.sample import sample_spherical_kernel\n>>> from spherediff.score import score_spherical_kernel\n>>> np.random.seed(42)\n>>> means = np.random.randn(5, 3)\n>>> means /= np.linalg.norm(means, axis=1, keepdims=True)\n>>> means\narray([[ 0.60000205, -0.1670153 , 0.78237039],\n [ 0.97717133, -0.15023209, -0.15022156],\n [ 0.86889694, 0.42224942, -0.25830898],\n [ 0.63675162, -0.5438697 , -0.54658314],\n [ 0.09351637, -0.73946664, -0.66666616]])\n>>> vars = 0.1 * np.ones(5)\n>>> x = sample_spherical_kernel(3, means, vars)\n>>> x\narray([[ 0.30027556, -0.53104481, 0.79235472],\n [ 0.91657116, -0.39288942, 0.07439905],\n [ 0.81325411, 0.41495422, -0.40795926],\n [ 0.39907791, -0.44171124, -0.80350981],\n [ 0.16422958, -0.76019121, -0.62860001]])\n>>> score_spherical_kernel(3, x, means, vars)\narray([[ 3.40175815, 3.11417869, 0.79800571],\n [ 1.12626049, 2.20918798, -2.20878198],\n [ 0.65201631, 0.12437106, 1.42627781],\n [ 2.65653386, -1.32241858, 2.04638588],\n [-0.69053884, 0.17827374, -0.39600546]])\n>>> x = sample_spherical_kernel(3, means, vars, hemisphere=True)\n>>> x\narray([[ 0.92723597, 0.02336567, 0.37374791],\n [ 0.99421791, -0.03878944, -0.10013055],\n [ 0.15771025, 0.6492883 , -0.74401087],\n [ 0.2418101 , -0.41127436, -0.87885225],\n [-0.11192408, -0.71437847, -0.69075061]])\n>>> score_spherical_kernel(3, x, means, vars, hemisphere=True)\narray([[-1.74036155, -1.77246139, 4.42849462],\n [-0.0852985 , -1.00528069, -0.45751298],\n [ 2.51709283, 0.09916178, 0.62009298],\n [ 4.08775888, -1.8186883 , 1.97580568],\n [ 1.8912707 , -0.37819329, 0.08468239]])\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Sample from the diffusion kernel on any n-sphere",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://github.com/rckormos/SphereDiff"
},
"split_keywords": [
"diffusion",
"hypersphere",
"sampling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "56f7d6b37f49150cea31ecc7c65a8157ff93908a0f888d8a1cac81a2957c58ad",
"md5": "fdd2bf5ed8ea0b0be692e619470745bf",
"sha256": "2703ff1f019f1b4ec7db902bb16c9f81e3056815af99a65f1d901756f31e6a7e"
},
"downloads": -1,
"filename": "spherediff-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fdd2bf5ed8ea0b0be692e619470745bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10359,
"upload_time": "2023-06-05T07:32:10",
"upload_time_iso_8601": "2023-06-05T07:32:10.404006Z",
"url": "https://files.pythonhosted.org/packages/56/f7/d6b37f49150cea31ecc7c65a8157ff93908a0f888d8a1cac81a2957c58ad/spherediff-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "26cf7f25cf5bc013d107cf5078738ee048e4008046c2d86708c21827acc6e07c",
"md5": "64935a39eb5715f1cac61c19a59a4d44",
"sha256": "1af51ad088812ba2839f572ff0761c4f266d68ed34b7a567bc4ced58f93fa130"
},
"downloads": -1,
"filename": "spherediff-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "64935a39eb5715f1cac61c19a59a4d44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10332,
"upload_time": "2023-06-05T07:32:11",
"upload_time_iso_8601": "2023-06-05T07:32:11.827318Z",
"url": "https://files.pythonhosted.org/packages/26/cf/7f25cf5bc013d107cf5078738ee048e4008046c2d86708c21827acc6e07c/spherediff-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-05 07:32:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rckormos",
"github_project": "SphereDiff",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "spherediff"
}
