# PyMC Extras
This library includes various experimental or otherwise special-purpose extras
for use with [PyMC](https://www.pymc.io) that have been extracted from the
[exoplanet](https://docs.exoplanet.codes) project. It's primary components are
some helper functions for [non-linear optimization](#Optimization) and [some
custom distributions](#Distributions).
## Installation
You'll need a Python installation, and it can often be best to install PyMC
using [`conda`](https://docs.conda.io/en/latest/) so that it can handle all the
details of compiler setup. This step is **optional**, but I would normally
create a clean conda environment for projects that use PyMC:
```bash
# Optional
conda create -n name-of-my-project pymc
conda activate name-of-my-project
```
The easiest way to install this package is using `pip`:
```bash
python -m pip install -U pymc-ext
```
This will also update the dependencies like PyMC, which is probably what you
want because this is only tested on recent versions of that package.
## Optimization
When PyMC added a warning to the `pm.find_MAP` function, we implemented a custom
non-linear optimization framework in `exoplanet` because it is often useful to
be able to optimize (at least) some parameters when initializing the sampler for
many problems in astrophysics (and probably elsewhere). While `pm.find_MAP` no
longer complains, the `pymc_ext.optimize` function is included here for backward
compatibility even though it should have similar behavior to `pm.find_MAP`. To
use this function, you'll do something like the following:
```python
import pymc_ext as pmx
with model:
soln = pmx.optimize(vars=[var1, var2])
soln = pmx.optimize(start=soln, vars=[var3])
```
## Distributions
Most of the custom distributions in this library are there to make working with
periodic parameters (like angles) easier. All of these reparameterizations could
be implemented manually without too much trouble, but it can be useful to have
them in a more compact form. Here is a list of the included distributions and
short descriptions:
- `pmx.unit_disk`: Two dimensional parameters constrained to live within the
unit disk. This will be useful when you have an angle and a magnitude that
must be in the range from zero to one (for example, an eccentricity vector for
a bound orbit). This distribution is constrained such that the sum of squares
along the zeroth axis will always be less than one. Note that the shape of
this distribution must be two in the zeroth axis.
- `pmx.angle`: An angle constrained to be in the range -pi to pi. The actual
sampling is performed in the two-dimensional vector space `(sin(theta), cos(theta))`
so that the sampler doesn't see a discontinuity at pi. As a
technical detail, the performance of this distribution can be affected using
the `regularization` parameter which helps deal with pathological geometries
introduced when this parameter is well/poorly constrained. The default value
(`10.0`) was selected as a reasonable default choice, but you might get better
performance by adjusting this.
It's important to note that these are not `Distribution` _objects_, but rather
functions that will add `Distribution` objects to the model, and return the
reparameterized variable of interest. The ergonomics of this interface are
questionable, but it's easier to maintain this interface than one that
implements custom `Distribution` objects.
## License
Copyright 2020-2022 Dan Foreman-Mackey and contributors.
pymc-ext is free software made available under the MIT License. For details see
the LICENSE file.
Raw data
{
"_id": null,
"home_page": "https://github.com/exoplanet-dev/pymc-ext",
"name": "pymc-ext",
"maintainer": "Daniel Foreman-Mackey",
"docs_url": null,
"requires_python": "",
"maintainer_email": "foreman.mackey@gmail.com",
"keywords": "",
"author": "Daniel Foreman-Mackey",
"author_email": "foreman.mackey@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c0/d4/e133995b71e2f245bb68f8fe3c3275114ee60075a4cf13128f9c45891a67/pymc_ext-1.0.1.tar.gz",
"platform": null,
"description": "# PyMC Extras\n\nThis library includes various experimental or otherwise special-purpose extras\nfor use with [PyMC](https://www.pymc.io) that have been extracted from the\n[exoplanet](https://docs.exoplanet.codes) project. It's primary components are\nsome helper functions for [non-linear optimization](#Optimization) and [some\ncustom distributions](#Distributions).\n\n## Installation\n\nYou'll need a Python installation, and it can often be best to install PyMC\nusing [`conda`](https://docs.conda.io/en/latest/) so that it can handle all the\ndetails of compiler setup. This step is **optional**, but I would normally\ncreate a clean conda environment for projects that use PyMC:\n\n```bash\n# Optional\nconda create -n name-of-my-project pymc\nconda activate name-of-my-project\n```\n\nThe easiest way to install this package is using `pip`:\n\n```bash\npython -m pip install -U pymc-ext\n```\n\nThis will also update the dependencies like PyMC, which is probably what you\nwant because this is only tested on recent versions of that package.\n\n## Optimization\n\nWhen PyMC added a warning to the `pm.find_MAP` function, we implemented a custom\nnon-linear optimization framework in `exoplanet` because it is often useful to\nbe able to optimize (at least) some parameters when initializing the sampler for\nmany problems in astrophysics (and probably elsewhere). While `pm.find_MAP` no\nlonger complains, the `pymc_ext.optimize` function is included here for backward\ncompatibility even though it should have similar behavior to `pm.find_MAP`. To\nuse this function, you'll do something like the following:\n\n```python\nimport pymc_ext as pmx\n\nwith model:\n soln = pmx.optimize(vars=[var1, var2])\n soln = pmx.optimize(start=soln, vars=[var3])\n```\n\n## Distributions\n\nMost of the custom distributions in this library are there to make working with\nperiodic parameters (like angles) easier. All of these reparameterizations could\nbe implemented manually without too much trouble, but it can be useful to have\nthem in a more compact form. Here is a list of the included distributions and\nshort descriptions:\n\n- `pmx.unit_disk`: Two dimensional parameters constrained to live within the\n unit disk. This will be useful when you have an angle and a magnitude that\n must be in the range from zero to one (for example, an eccentricity vector for\n a bound orbit). This distribution is constrained such that the sum of squares\n along the zeroth axis will always be less than one. Note that the shape of\n this distribution must be two in the zeroth axis.\n- `pmx.angle`: An angle constrained to be in the range -pi to pi. The actual\n sampling is performed in the two-dimensional vector space `(sin(theta), cos(theta))`\n so that the sampler doesn't see a discontinuity at pi. As a\n technical detail, the performance of this distribution can be affected using\n the `regularization` parameter which helps deal with pathological geometries\n introduced when this parameter is well/poorly constrained. The default value\n (`10.0`) was selected as a reasonable default choice, but you might get better\n performance by adjusting this.\n\nIt's important to note that these are not `Distribution` _objects_, but rather\nfunctions that will add `Distribution` objects to the model, and return the\nreparameterized variable of interest. The ergonomics of this interface are\nquestionable, but it's easier to maintain this interface than one that\nimplements custom `Distribution` objects.\n\n## License\n\nCopyright 2020-2022 Dan Foreman-Mackey and contributors.\n\npymc-ext is free software made available under the MIT License. For details see\nthe LICENSE file.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PyMC Extras extracted from the",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/exoplanet-dev/pymc-ext"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84fd2a95356ca6916a2378b85c7ec34dffec62581138c2d07d2a538c9723ae73",
"md5": "64935c1e3185ef05fcc49a98d81f09be",
"sha256": "9b4336a022dd9823073c9ffdb41f1a67171b8b0f80435392dd822d3b4d9ce182"
},
"downloads": -1,
"filename": "pymc_ext-1.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "64935c1e3185ef05fcc49a98d81f09be",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 8427,
"upload_time": "2024-03-06T19:13:07",
"upload_time_iso_8601": "2024-03-06T19:13:07.933358Z",
"url": "https://files.pythonhosted.org/packages/84/fd/2a95356ca6916a2378b85c7ec34dffec62581138c2d07d2a538c9723ae73/pymc_ext-1.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0d4e133995b71e2f245bb68f8fe3c3275114ee60075a4cf13128f9c45891a67",
"md5": "d8dc00c171f564fe14aa5838212aaad3",
"sha256": "50c596a7c681308bf300f1b1408fd6d3c89c72692019332ddf293dbc779bcb8c"
},
"downloads": -1,
"filename": "pymc_ext-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d8dc00c171f564fe14aa5838212aaad3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15259,
"upload_time": "2024-03-06T19:13:09",
"upload_time_iso_8601": "2024-03-06T19:13:09.049074Z",
"url": "https://files.pythonhosted.org/packages/c0/d4/e133995b71e2f245bb68f8fe3c3275114ee60075a4cf13128f9c45891a67/pymc_ext-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 19:13:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "exoplanet-dev",
"github_project": "pymc-ext",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymc-ext"
}
JSON
