unxts.interop.numpyro 2.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- unxts_interop_numpyro-2.2.0/.gitignore +169 -0
- unxts_interop_numpyro-2.2.0/LICENSE +29 -0
- unxts_interop_numpyro-2.2.0/PKG-INFO +63 -0
- unxts_interop_numpyro-2.2.0/README.md +36 -0
- unxts_interop_numpyro-2.2.0/docs/concepts/handler-order.md +32 -0
- unxts_interop_numpyro-2.2.0/docs/concepts/index.md +15 -0
- unxts_interop_numpyro-2.2.0/docs/concepts/sites.md +33 -0
- unxts_interop_numpyro-2.2.0/docs/concepts/unit-systems.md +27 -0
- unxts_interop_numpyro-2.2.0/docs/guides/fit-with-svi.md +79 -0
- unxts_interop_numpyro-2.2.0/docs/guides/give-a-site-units.md +68 -0
- unxts_interop_numpyro-2.2.0/docs/guides/index.md +25 -0
- unxts_interop_numpyro-2.2.0/docs/guides/mask-and-subsample.md +55 -0
- unxts_interop_numpyro-2.2.0/docs/guides/place-handlers.md +75 -0
- unxts_interop_numpyro-2.2.0/docs/guides/run-mcmc.md +78 -0
- unxts_interop_numpyro-2.2.0/docs/guides/troubleshooting.md +77 -0
- unxts_interop_numpyro-2.2.0/docs/guides/use-jnp-code.md +52 -0
- unxts_interop_numpyro-2.2.0/docs/guides/use-scan-and-cond.md +85 -0
- unxts_interop_numpyro-2.2.0/docs/index.md +76 -0
- unxts_interop_numpyro-2.2.0/docs/reference/api.md +15 -0
- unxts_interop_numpyro-2.2.0/docs/reference/behaviour.md +154 -0
- unxts_interop_numpyro-2.2.0/docs/reference/errors.md +149 -0
- unxts_interop_numpyro-2.2.0/docs/reference/glossary.md +34 -0
- unxts_interop_numpyro-2.2.0/docs/reference/unit-rules.md +79 -0
- unxts_interop_numpyro-2.2.0/docs/tutorial-fit-mean-and-width.md +101 -0
- unxts_interop_numpyro-2.2.0/pyproject.toml +80 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/__init__.py +14 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/__init__.py +3 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/handler.py +684 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/patches.py +106 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/rules.py +302 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/samples.py +49 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_version.py +24 -0
- unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/py.typed +0 -0
- unxts_interop_numpyro-2.2.0/tests/conftest.py +26 -0
- unxts_interop_numpyro-2.2.0/tests/integration/test_inference.py +541 -0
- unxts_interop_numpyro-2.2.0/tests/smoke/test_public_api.py +12 -0
- unxts_interop_numpyro-2.2.0/tests/unit/test_attach_units.py +72 -0
- unxts_interop_numpyro-2.2.0/tests/unit/test_other_sites.py +316 -0
- unxts_interop_numpyro-2.2.0/tests/unit/test_outer_values.py +213 -0
- unxts_interop_numpyro-2.2.0/tests/unit/test_patches.py +124 -0
- unxts_interop_numpyro-2.2.0/tests/unit/test_rules.py +188 -0
- unxts_interop_numpyro-2.2.0/tests/unit/test_sample_sites.py +814 -0
- unxts_interop_numpyro-2.2.0/tests/unit/test_validation.py +152 -0
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# -----------------------------------------------
|
|
2
|
+
# Project-Specific
|
|
3
|
+
|
|
4
|
+
# Version files
|
|
5
|
+
_version.py
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
# -----------------------------------------------
|
|
9
|
+
# General
|
|
10
|
+
|
|
11
|
+
# Byte-compiled / optimized / DLL files
|
|
12
|
+
__pycache__/
|
|
13
|
+
*.py[cod]
|
|
14
|
+
*$py.class
|
|
15
|
+
|
|
16
|
+
# C extensions
|
|
17
|
+
*.so
|
|
18
|
+
|
|
19
|
+
# Distribution / packaging
|
|
20
|
+
.Python
|
|
21
|
+
build/
|
|
22
|
+
develop-eggs/
|
|
23
|
+
dist/
|
|
24
|
+
downloads/
|
|
25
|
+
eggs/
|
|
26
|
+
.eggs/
|
|
27
|
+
lib/
|
|
28
|
+
lib64/
|
|
29
|
+
parts/
|
|
30
|
+
sdist/
|
|
31
|
+
var/
|
|
32
|
+
wheels/
|
|
33
|
+
share/python-wheels/
|
|
34
|
+
*.egg-info/
|
|
35
|
+
.installed.cfg
|
|
36
|
+
*.egg
|
|
37
|
+
MANIFEST
|
|
38
|
+
|
|
39
|
+
# PyInstaller
|
|
40
|
+
# Usually these files are written by a python script from a template
|
|
41
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
42
|
+
*.manifest
|
|
43
|
+
*.spec
|
|
44
|
+
|
|
45
|
+
# Installer logs
|
|
46
|
+
pip-log.txt
|
|
47
|
+
pip-delete-this-directory.txt
|
|
48
|
+
|
|
49
|
+
# Unit test / coverage reports
|
|
50
|
+
htmlcov/
|
|
51
|
+
.tox/
|
|
52
|
+
.nox/
|
|
53
|
+
.coverage
|
|
54
|
+
.coverage.*
|
|
55
|
+
.cache
|
|
56
|
+
nosetests.xml
|
|
57
|
+
coverage.xml
|
|
58
|
+
*.cover
|
|
59
|
+
*.py,cover
|
|
60
|
+
.hypothesis/
|
|
61
|
+
.pytest_cache/
|
|
62
|
+
cover/
|
|
63
|
+
|
|
64
|
+
# Translations
|
|
65
|
+
*.mo
|
|
66
|
+
*.pot
|
|
67
|
+
|
|
68
|
+
# Django stuff:
|
|
69
|
+
*.log
|
|
70
|
+
local_settings.py
|
|
71
|
+
db.sqlite3
|
|
72
|
+
db.sqlite3-journal
|
|
73
|
+
|
|
74
|
+
# Flask stuff:
|
|
75
|
+
instance/
|
|
76
|
+
.webassets-cache
|
|
77
|
+
|
|
78
|
+
# Scrapy stuff:
|
|
79
|
+
.scrapy
|
|
80
|
+
|
|
81
|
+
# Sphinx documentation
|
|
82
|
+
docs/_build/
|
|
83
|
+
docs/how-to/optimize-performance.ipynb
|
|
84
|
+
|
|
85
|
+
# PyBuilder
|
|
86
|
+
.pybuilder/
|
|
87
|
+
target/
|
|
88
|
+
|
|
89
|
+
# Jupyter Notebook
|
|
90
|
+
.ipynb_checkpoints
|
|
91
|
+
|
|
92
|
+
# IPython
|
|
93
|
+
profile_default/
|
|
94
|
+
ipython_config.py
|
|
95
|
+
|
|
96
|
+
# pyenv
|
|
97
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
98
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
99
|
+
# .python-version
|
|
100
|
+
|
|
101
|
+
# pipenv
|
|
102
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
103
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
104
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
105
|
+
# install all needed dependencies.
|
|
106
|
+
#Pipfile.lock
|
|
107
|
+
|
|
108
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow
|
|
109
|
+
__pypackages__/
|
|
110
|
+
|
|
111
|
+
# Celery stuff
|
|
112
|
+
celerybeat-schedule
|
|
113
|
+
celerybeat.pid
|
|
114
|
+
|
|
115
|
+
# SageMath parsed files
|
|
116
|
+
*.sage.py
|
|
117
|
+
|
|
118
|
+
# Environments
|
|
119
|
+
.env
|
|
120
|
+
.venv
|
|
121
|
+
env/
|
|
122
|
+
venv/
|
|
123
|
+
ENV/
|
|
124
|
+
env.bak/
|
|
125
|
+
venv.bak/
|
|
126
|
+
|
|
127
|
+
# Spyder project settings
|
|
128
|
+
.spyderproject
|
|
129
|
+
.spyproject
|
|
130
|
+
|
|
131
|
+
# Rope project settings
|
|
132
|
+
.ropeproject
|
|
133
|
+
|
|
134
|
+
# mkdocs documentation
|
|
135
|
+
/site
|
|
136
|
+
|
|
137
|
+
# mypy
|
|
138
|
+
.mypy_cache/
|
|
139
|
+
.dmypy.json
|
|
140
|
+
dmypy.json
|
|
141
|
+
|
|
142
|
+
# Pyre type checker
|
|
143
|
+
.pyre/
|
|
144
|
+
|
|
145
|
+
# pytype static type analyzer
|
|
146
|
+
.pytype/
|
|
147
|
+
|
|
148
|
+
# Cython debug symbols
|
|
149
|
+
cython_debug/
|
|
150
|
+
|
|
151
|
+
# ruff
|
|
152
|
+
.ruff_cache/
|
|
153
|
+
|
|
154
|
+
# OS specific stuff
|
|
155
|
+
.DS_Store
|
|
156
|
+
.DS_Store?
|
|
157
|
+
._*
|
|
158
|
+
.Spotlight-V100
|
|
159
|
+
.Trashes
|
|
160
|
+
ehthumbs.db
|
|
161
|
+
Thumbs.db
|
|
162
|
+
|
|
163
|
+
# Common editor files
|
|
164
|
+
*~
|
|
165
|
+
*.swp
|
|
166
|
+
/.codspeed
|
|
167
|
+
|
|
168
|
+
# graphify knowledge graph (generated; `nox -s graph`)
|
|
169
|
+
/graphify-out/
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023, Nathaniel Starkman.
|
|
4
|
+
All rights reserved.
|
|
5
|
+
|
|
6
|
+
Redistribution and use in source and binary forms, with or without
|
|
7
|
+
modification, are permitted provided that the following conditions are met:
|
|
8
|
+
|
|
9
|
+
* Redistributions of source code must retain the above copyright notice, this
|
|
10
|
+
list of conditions and the following disclaimer.
|
|
11
|
+
|
|
12
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
|
13
|
+
this list of conditions and the following disclaimer in the documentation
|
|
14
|
+
and/or other materials provided with the distribution.
|
|
15
|
+
|
|
16
|
+
* Neither the name of the copyright holder nor the names of its
|
|
17
|
+
contributors may be used to endorse or promote products derived from
|
|
18
|
+
this software without specific prior written permission.
|
|
19
|
+
|
|
20
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
21
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
22
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
23
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
24
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
25
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
26
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
27
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
28
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
29
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: unxts.interop.numpyro
|
|
3
|
+
Version: 2.2.0
|
|
4
|
+
Summary: NumPyro integration for unxt (canonical: unxts.interop.numpyro)
|
|
5
|
+
Project-URL: Bug Tracker, https://github.com/GalacticDynamics/unxt/issues
|
|
6
|
+
Project-URL: Homepage, https://github.com/GalacticDynamics/unxt
|
|
7
|
+
Author-email: GalacticDynamics <nstarman@users.noreply.github.com>, Nathaniel Starkman <nstarman@users.noreply.github.com>
|
|
8
|
+
License-Expression: BSD-3-Clause
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Requires-Dist: numpyro>=0.22.0
|
|
24
|
+
Requires-Dist: plum-dispatch>=2.7.0
|
|
25
|
+
Requires-Dist: unxt>=2.1.0
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# unxts.interop.numpyro
|
|
29
|
+
|
|
30
|
+
NumPyro integration for [unxt](https://github.com/GalacticDynamics/unxt).
|
|
31
|
+
|
|
32
|
+
The `unitful` handler lets NumPyro models take `unxt` quantities. It converts them to plain numbers in a unit system you choose before NumPyro sees them. The model gets its sampled values back as quantities, and `attach_units` puts the units on the posterior samples.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install unxts.interop.numpyro
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Usage
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
import jax
|
|
44
|
+
import numpyro
|
|
45
|
+
import numpyro.distributions as dist
|
|
46
|
+
import unxt as u
|
|
47
|
+
from numpyro.infer import MCMC, NUTS
|
|
48
|
+
from unxts.interop.numpyro import attach_units, unitful
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def model(x=None):
|
|
52
|
+
m = numpyro.sample("m", dist.Normal(u.Q(0.0, "kpc"), u.Q(3.0, "kpc")))
|
|
53
|
+
s = numpyro.sample("s", dist.HalfNormal(u.Q(1.0, "kpc")))
|
|
54
|
+
with numpyro.plate("n", 200):
|
|
55
|
+
numpyro.sample("x", dist.Normal(m, s), obs=x)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
x = u.Q(1.0 + 0.2 * jax.random.normal(jax.random.PRNGKey(1), (200,)), "kpc")
|
|
59
|
+
M = unitful(model, u.unitsystems.galactic)
|
|
60
|
+
mcmc = MCMC(NUTS(M), num_warmup=200, num_samples=200, progress_bar=False)
|
|
61
|
+
mcmc.run(jax.random.PRNGKey(0), x)
|
|
62
|
+
samples = attach_units(mcmc.get_samples(), M) # samples["m"] is a Quantity in kpc
|
|
63
|
+
```
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# unxts.interop.numpyro
|
|
2
|
+
|
|
3
|
+
NumPyro integration for [unxt](https://github.com/GalacticDynamics/unxt).
|
|
4
|
+
|
|
5
|
+
The `unitful` handler lets NumPyro models take `unxt` quantities. It converts them to plain numbers in a unit system you choose before NumPyro sees them. The model gets its sampled values back as quantities, and `attach_units` puts the units on the posterior samples.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install unxts.interop.numpyro
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
import jax
|
|
17
|
+
import numpyro
|
|
18
|
+
import numpyro.distributions as dist
|
|
19
|
+
import unxt as u
|
|
20
|
+
from numpyro.infer import MCMC, NUTS
|
|
21
|
+
from unxts.interop.numpyro import attach_units, unitful
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def model(x=None):
|
|
25
|
+
m = numpyro.sample("m", dist.Normal(u.Q(0.0, "kpc"), u.Q(3.0, "kpc")))
|
|
26
|
+
s = numpyro.sample("s", dist.HalfNormal(u.Q(1.0, "kpc")))
|
|
27
|
+
with numpyro.plate("n", 200):
|
|
28
|
+
numpyro.sample("x", dist.Normal(m, s), obs=x)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
x = u.Q(1.0 + 0.2 * jax.random.normal(jax.random.PRNGKey(1), (200,)), "kpc")
|
|
32
|
+
M = unitful(model, u.unitsystems.galactic)
|
|
33
|
+
mcmc = MCMC(NUTS(M), num_warmup=200, num_samples=200, progress_bar=False)
|
|
34
|
+
mcmc.run(jax.random.PRNGKey(0), x)
|
|
35
|
+
samples = attach_units(mcmc.get_samples(), M) # samples["m"] is a Quantity in kpc
|
|
36
|
+
```
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Handler order
|
|
2
|
+
|
|
3
|
+
NumPyro passes each site's message through a stack of handlers. The message goes from the innermost handler, nearest the model, to the outermost. The results then come back from the outermost handler inwards. `unitful` strips the units on the way out and wraps the value on the way back. Handlers inside `unitful` therefore see quantities on the way out. Handlers outside it see {term}`bare values <bare value>`.
|
|
4
|
+
|
|
5
|
+
## What each handler needs
|
|
6
|
+
|
|
7
|
+
That one fact decides where each handler goes.
|
|
8
|
+
|
|
9
|
+
- `reparam` rebuilds a distribution from its parameters with plain arithmetic. It needs bare numbers, so it goes outside `unitful`.
|
|
10
|
+
- `condition` and `substitute` set a site's value. Inside `unitful`, `unitful` strips the value like any other, so it must be a `Quantity` when the site has a dimension. Outside, the site is already bare, so a bare number in the unit of `usys` also works.
|
|
11
|
+
- `do` sends a copy of the site through the stack a second time. Outside `unitful`, that copy has already been stripped. `unitful` refuses to strip it twice, so `do` goes inside.
|
|
12
|
+
- `lift` turns a `param` site into a sample site with a prior. Outside `unitful`, this happens after `unitful` has handled the site as a `param`. The prior's parameters are never stripped. NumPyro then cannot score the prior unless its parameters are bare.
|
|
13
|
+
- `trace` records each message on the way back. Inside `unitful`, it would record the stripped distribution next to the rewrapped value, which do not match. It goes outside.
|
|
14
|
+
- `block` hides its sites from every handler outside it. Inside `unitful`, it hides them from `unitful` too, so their parameters are never stripped. It goes outside, or around sites with bare parameters only.
|
|
15
|
+
|
|
16
|
+
A `Quantity` set by a handler outside `unitful` still reaches NumPyro as a bare value. `unitful` places an extra step at the outer end of the stack, which strips it.
|
|
17
|
+
|
|
18
|
+
## Guides and replay
|
|
19
|
+
|
|
20
|
+
SVI runs a guide, then {term}`replays <replay>` the guide's sampled values into the model. The replayed values are bare. The model's handler reads them in its own unit system. The guide must therefore produce them in the same unit system.
|
|
21
|
+
|
|
22
|
+
Suppose the guide's handler used parsecs and the model's used kiloparsecs. Every replayed value would then be wrong by a factor of 1000, and NumPyro would raise no error. `unitful` checks the unit of each replayed site and raises `UnitfulError` instead. A guide handler built as `unitful(guide, M.usys)` shares the model's unit system by construction.
|
|
23
|
+
|
|
24
|
+
## Two handlers on one model
|
|
25
|
+
|
|
26
|
+
A `unitful` inside another `unitful` strips the sites first. The outer handler then sees only bare values and records no units. With a different unit system, nothing converts between the two. One `unitful` per model avoids both problems.
|
|
27
|
+
|
|
28
|
+
## Related pages
|
|
29
|
+
|
|
30
|
+
- {doc}`../guides/place-handlers` shows where to put each handler.
|
|
31
|
+
- {doc}`../reference/behaviour` has the full handler table.
|
|
32
|
+
- {doc}`../guides/fit-with-svi` shows how to build a guide's handler.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Concepts
|
|
2
|
+
|
|
3
|
+
These pages explain how `unitful` connects a model written in units to NumPyro, which computes on plain numbers. They contain no code to run.
|
|
4
|
+
|
|
5
|
+
- {doc}`sites` explains how `unitful` strips and wraps the units at each sample site, and where the units go after a fit.
|
|
6
|
+
- {doc}`unit-systems` explains why `unitful` needs a unit system, and how it changes the log density.
|
|
7
|
+
- {doc}`handler-order` explains why some handlers go inside `unitful` and others outside.
|
|
8
|
+
|
|
9
|
+
```{toctree}
|
|
10
|
+
:hidden:
|
|
11
|
+
|
|
12
|
+
sites
|
|
13
|
+
unit-systems
|
|
14
|
+
handler-order
|
|
15
|
+
```
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Units at a sample site
|
|
2
|
+
|
|
3
|
+
NumPyro computes on plain arrays. Its distributions take logarithms of their scales, its samplers move plain numbers, and its traces store them. None of these steps expects a value with a unit. `unitful` keeps the units in the model and the plain numbers in NumPyro, and it does the exchange at each {term}`sample site`.
|
|
4
|
+
|
|
5
|
+
## Stripping and wrapping
|
|
6
|
+
|
|
7
|
+
A model calls `numpyro.sample` with a distribution and, for an {term}`observed site`, a value. NumPyro passes this call to each active handler as a message. `unitful` reads the message before NumPyro samples or scores it.
|
|
8
|
+
|
|
9
|
+
At the site, `unitful` finds the site's dimension from its distribution. The {term}`unit rule` of the distribution's family names the {term}`carrying parameters <carrying parameter>`, and their dimension is the site's. The unit system then gives the unit of that dimension, the {term}`site unit`.
|
|
10
|
+
|
|
11
|
+
`unitful` strips every `Quantity` in the message to a {term}`bare value`. Values and carrying parameters with power 1 are stripped in the site unit. A carrying parameter with power −1, such as a rate, is stripped in its inverse. A shape parameter is dimensionless, so it becomes a plain number. NumPyro samples and scores those bare values. Afterwards `unitful` wraps the sampled value in the site unit and returns it to the model. With `rewrap=False`, the model gets the bare value instead.
|
|
12
|
+
|
|
13
|
+
```{admonition} In plain words
|
|
14
|
+
Every distribution gets its numbers in one agreed unit per dimension, and the model gets its answers back with units attached.
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Why not transform the whole model
|
|
18
|
+
|
|
19
|
+
JAX can run a function on quantities if `quax.quaxify` wraps it. Wrapping a whole NumPyro model that way does not work. NumPyro's handlers keep their state outside the function that JAX transforms. A `trace` would then record values from inside the transform, and the handlers would see values without their units.
|
|
20
|
+
|
|
21
|
+
`unitful` avoids the problem by acting at the edge of each site. The model between sites still computes on quantities. `quaxify` stays useful there, on helper functions written in plain `jax.numpy`. The {doc}`../guides/use-jnp-code` guide shows how.
|
|
22
|
+
|
|
23
|
+
## Where the units go after a fit
|
|
24
|
+
|
|
25
|
+
MCMC and SVI collect the values in NumPyro's trace. Those are the bare values NumPyro worked with, so the posterior samples have no units. A handler cannot change what MCMC and SVI store.
|
|
26
|
+
|
|
27
|
+
Instead, `unitful` records the site unit of every site it runs. `attach_units` reads that record and wraps each array in its site unit. The record is the only link between an array and its unit. A bare array cannot say which unit system produced it, so `attach_units` cannot detect the wrong handler.
|
|
28
|
+
|
|
29
|
+
## Related pages
|
|
30
|
+
|
|
31
|
+
- {doc}`unit-systems` explains why the unit system matters.
|
|
32
|
+
- {doc}`../reference/unit-rules` lists the carrying parameters of each family.
|
|
33
|
+
- {doc}`../reference/behaviour` lists what `unitful` does at each kind of site.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Unit systems
|
|
2
|
+
|
|
3
|
+
A `Quantity` becomes a number only once a unit is chosen. The same length is 1 in kiloparsecs and about 3.1 × 10¹⁹ in metres. `unitful` takes that choice from its unit system argument, `usys`, which names one unit for each dimension.
|
|
4
|
+
|
|
5
|
+
## The choice changes the log density
|
|
6
|
+
|
|
7
|
+
A probability density over a length has the units of one over that length. Expressing the same data in another unit rescales the density by the conversion factor. Its logarithm shifts by a constant.
|
|
8
|
+
|
|
9
|
+
The constant does not change the posterior, because it does not depend on the parameters. It does change every reported log density. A log-likelihood value therefore compares only with another computed under the same unit system. {doc}`../reference/behaviour` shows the shift between kiloparsecs and metres.
|
|
10
|
+
|
|
11
|
+
`usys` is a required argument for this reason. The model's code then states the unit of every log density it reports. The units of the incoming data do not decide it.
|
|
12
|
+
|
|
13
|
+
## Bare numbers are read in the unit system
|
|
14
|
+
|
|
15
|
+
Some numbers reach a site that has a dimension, but carry no unit themselves. A handler outside `unitful` can set such a site to a bare value. A family with no unit rule has bare parameters, and a `units=` entry gives its site a dimension. `unitful` reads these numbers in the unit of `usys`. A site with no dimension has no unit, so its numbers stay plain.
|
|
16
|
+
|
|
17
|
+
This is why a `units=` entry must name the dimension, or the `usys` unit itself. Under the `galactic` unit system, bare parameters are read in kiloparsecs. An entry of `"pc"` would claim parsecs for numbers that are really kiloparsecs, so `unitful` rejects it.
|
|
18
|
+
|
|
19
|
+
## One exception: `VonMises`
|
|
20
|
+
|
|
21
|
+
NumPyro defines the `VonMises` density on radians. `unitful` therefore strips and wraps a `VonMises` site in radians, whatever angle unit `usys` uses. The site's log density is then the one NumPyro defines.
|
|
22
|
+
|
|
23
|
+
## Related pages
|
|
24
|
+
|
|
25
|
+
- {doc}`sites` explains how `unitful` strips and wraps each site.
|
|
26
|
+
- {doc}`handler-order` explains where a bare value can come from.
|
|
27
|
+
- {doc}`../guides/give-a-site-units` shows how to use `units=`.
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Fit a model with SVI
|
|
2
|
+
|
|
3
|
+
Stochastic variational inference (SVI) fits a guide to the wrapped model. The guide can be an autoguide or one you write. Either way, `attach_units` puts the units back on the results.
|
|
4
|
+
|
|
5
|
+
The examples use this model:
|
|
6
|
+
|
|
7
|
+
```python
|
|
8
|
+
>>> import jax
|
|
9
|
+
>>> import numpyro
|
|
10
|
+
>>> import numpyro.distributions as dist
|
|
11
|
+
>>> from numpyro.infer import SVI, Predictive, Trace_ELBO
|
|
12
|
+
>>> from numpyro.infer.autoguide import AutoNormal
|
|
13
|
+
>>> from numpyro.optim import Adam
|
|
14
|
+
>>> import unxt as u
|
|
15
|
+
>>> from unxts.interop.numpyro import attach_units, unitful
|
|
16
|
+
|
|
17
|
+
>>> def model():
|
|
18
|
+
... m = numpyro.sample("m", dist.Normal(u.Q(0.0, "kpc"), u.Q(3.0, "kpc")))
|
|
19
|
+
... s = numpyro.sample("s", dist.HalfNormal(u.Q(1.0, "kpc")))
|
|
20
|
+
... numpyro.sample("x", dist.Normal(m, s), obs=u.Q([1.0, 1.2, 0.9], "kpc"))
|
|
21
|
+
|
|
22
|
+
>>> M = unitful(model, u.unitsystems.galactic)
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Use an autoguide
|
|
27
|
+
|
|
28
|
+
Build the autoguide from the wrapped model:
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
>>> svi = SVI(M, AutoNormal(M), Adam(0.01), Trace_ELBO())
|
|
32
|
+
>>> res = svi.run(jax.random.PRNGKey(0), 100, progress_bar=False)
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Write your own guide
|
|
37
|
+
|
|
38
|
+
Write the guide with `Quantity` parameters. Wrap it in its own `unitful`, built from the model's unit system, `M.usys`:
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
>>> positive = dist.constraints.positive
|
|
42
|
+
|
|
43
|
+
>>> def guide():
|
|
44
|
+
... loc = numpyro.param("m_loc", u.Q(1.0, "kpc"))
|
|
45
|
+
... scale = numpyro.param("m_scale", u.Q(0.1, "kpc"), constraint=positive)
|
|
46
|
+
... numpyro.sample("m", dist.Normal(loc, scale))
|
|
47
|
+
... s_map = numpyro.param("s_map", u.Q(0.2, "kpc"), constraint=positive)
|
|
48
|
+
... numpyro.sample("s", dist.Delta(s_map))
|
|
49
|
+
|
|
50
|
+
>>> G = unitful(guide, M.usys)
|
|
51
|
+
>>> svi = SVI(M, G, Adam(0.01), Trace_ELBO())
|
|
52
|
+
>>> res = svi.run(jax.random.PRNGKey(0), 100, progress_bar=False)
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The two handlers now share one unit system. SVI passes {term}`bare values <bare value>` between them, and both read those values in the same units.
|
|
57
|
+
|
|
58
|
+
If a `param` constraint has `Quantity` bounds, give the init value as a `Quantity` too.
|
|
59
|
+
|
|
60
|
+
## Read the results with units
|
|
61
|
+
|
|
62
|
+
Pass `attach_units` the handler that ran the sites. The guide's handler ran the fitted parameters:
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
>>> attach_units(svi.get_params(res.state), G)["m_loc"].unit
|
|
66
|
+
Unit("kpc")
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`Predictive(G, ...)` runs the guide, so its samples go with the guide's handler too:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
>>> post = Predictive(G, params=res.params, num_samples=10)(jax.random.PRNGKey(1))
|
|
74
|
+
>>> attach_units(post, G)["m"].unit
|
|
75
|
+
Unit("kpc")
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`attach_units` cannot tell which handler produced the samples. The wrong handler gives wrong units, with no error. {doc}`../reference/errors` lists the errors that a mismatched guide raises during the fit.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Give units to a site with no unit rule
|
|
2
|
+
|
|
3
|
+
Some distributions cannot carry a unit in their parameters. A `LogNormal` of a length is one: its `loc` and `scale` are logarithms. For such a site, name its dimension with `units=`. {doc}`../reference/unit-rules` lists the families that have a {term}`unit rule`.
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
>>> import numpyro
|
|
7
|
+
>>> import numpyro.distributions as dist
|
|
8
|
+
>>> from numpyro import handlers
|
|
9
|
+
>>> import unxt as u
|
|
10
|
+
>>> from unxts.interop.numpyro import unitful
|
|
11
|
+
|
|
12
|
+
>>> galactic = u.unitsystems.galactic
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Name the site's dimension
|
|
17
|
+
|
|
18
|
+
Write the distribution with bare parameters in the unit of `usys`. Pass the site's dimension in `units=`:
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
>>> def model():
|
|
22
|
+
... return numpyro.sample("r", dist.LogNormal(0.0, 1.0))
|
|
23
|
+
|
|
24
|
+
>>> r = handlers.seed(unitful(model, galactic, units={"r": "length"}), 0)()
|
|
25
|
+
>>> r.unit
|
|
26
|
+
Unit("kpc")
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The value comes back in kpc, the `galactic` unit of length. The bare `loc` and `scale` describe the logarithm of the value in kpc.
|
|
31
|
+
|
|
32
|
+
Instead of the dimension, you can pass the `usys` unit itself, `units={"r": "kpc"}`. Any other unit of that dimension raises:
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
>>> unitful(model, galactic, units={"r": "pc"})
|
|
36
|
+
Traceback (most recent call last):
|
|
37
|
+
...
|
|
38
|
+
unxts.interop.numpyro.UnitfulError: Site 'r': units= gives pc, but bare parameters are read in the unit of usys; pass units={'r': 'kpc'}.
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Name the site as `unitful` sees it
|
|
43
|
+
|
|
44
|
+
If a `scope` inside `unitful` adds a prefix, include the prefix in the key.
|
|
45
|
+
|
|
46
|
+
If the `scope` is outside `unitful`, leave the prefix out. For `handlers.scope(unitful(model, usys), "a")`, write `units={"r": ...}`, not `"a/r"`.
|
|
47
|
+
|
|
48
|
+
If the site is behind an `if`, the key raises `UnitfulError` until a call reaches the site.
|
|
49
|
+
|
|
50
|
+
## Use a censored distribution
|
|
51
|
+
|
|
52
|
+
Give it a bare base distribution, and pass `units=` for the site:
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
>>> import jax.numpy as jnp
|
|
56
|
+
|
|
57
|
+
>>> def censored():
|
|
58
|
+
... mask = jnp.array([False, True])
|
|
59
|
+
... d = dist.LeftCensoredDistribution(dist.Normal(0.0, 1.0), censored=mask)
|
|
60
|
+
... numpyro.sample("x", d, obs=u.Q([0.5, 0.0], "kpc"))
|
|
61
|
+
|
|
62
|
+
>>> tr = handlers.trace(unitful(censored, galactic, units={"x": "kpc"})).get_trace()
|
|
63
|
+
>>> tr["x"]["value"]
|
|
64
|
+
Array([0.5, 0. ], dtype=float32)
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The same steps work for `MixtureGeneral`, `ImproperUniform`, `Pareto`, and a `TransformedDistribution` with a `ComposeTransform`.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Guides
|
|
2
|
+
|
|
3
|
+
Each guide covers one task. The {doc}`tutorial <../tutorial-fit-mean-and-width>` shows a whole fit, and the {doc}`concepts <../concepts/index>` explain why `unitful` works as it does.
|
|
4
|
+
|
|
5
|
+
A fit with `unitful` has four steps:
|
|
6
|
+
|
|
7
|
+
1. **Write the model in units.** Give distributions `Quantity` parameters and pass `Quantity` data. If a family has no unit rule, name its dimension ({doc}`give-a-site-units`). For computations between sites, see {doc}`use-jnp-code`. For loops and branches, see {doc}`use-scan-and-cond`. For partial data, see {doc}`mask-and-subsample`.
|
|
8
|
+
2. **Wrap it and add handlers.** Wrap the model in `unitful` with a unit system. Then put each other handler on the right side of it ({doc}`place-handlers`).
|
|
9
|
+
3. **Run inference.** Use MCMC ({doc}`run-mcmc`) or SVI ({doc}`fit-with-svi`).
|
|
10
|
+
4. **Read the results.** Pass the samples and the handler to `attach_units` ({doc}`run-mcmc`, {doc}`fit-with-svi`).
|
|
11
|
+
|
|
12
|
+
{doc}`troubleshooting` maps each error and symptom to its fix.
|
|
13
|
+
|
|
14
|
+
```{toctree}
|
|
15
|
+
:maxdepth: 1
|
|
16
|
+
|
|
17
|
+
give-a-site-units
|
|
18
|
+
use-jnp-code
|
|
19
|
+
use-scan-and-cond
|
|
20
|
+
mask-and-subsample
|
|
21
|
+
place-handlers
|
|
22
|
+
run-mcmc
|
|
23
|
+
fit-with-svi
|
|
24
|
+
troubleshooting
|
|
25
|
+
```
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Mask or subsample observations
|
|
2
|
+
|
|
3
|
+
A model can observe part of a `Quantity` data set, through an `obs_mask=` or a subsampled plate. Each needs one change from plain NumPyro.
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
>>> import jax.numpy as jnp
|
|
7
|
+
>>> import numpyro
|
|
8
|
+
>>> import numpyro.distributions as dist
|
|
9
|
+
>>> from numpyro import handlers
|
|
10
|
+
>>> from numpyro.infer.util import log_density
|
|
11
|
+
>>> import unxt as u
|
|
12
|
+
>>> from unxts.interop.numpyro import unitful
|
|
13
|
+
|
|
14
|
+
>>> galactic = u.unitsystems.galactic
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Mask observations
|
|
19
|
+
|
|
20
|
+
Pass `rewrap=False`, so the model gets bare numbers in the unit of `usys`. Wrap the latent value in a `Quantity` where the distribution needs it:
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
>>> def masked(x):
|
|
24
|
+
... m = numpyro.sample("m", dist.Normal(u.Q(0.0, "kpc"), u.Q(3.0, "kpc")))
|
|
25
|
+
... mask = jnp.array([True, False, True])
|
|
26
|
+
... d = dist.Normal(u.Q(m, "kpc"), u.Q(1.0, "kpc"))
|
|
27
|
+
... numpyro.sample("x", d, obs=x, obs_mask=mask)
|
|
28
|
+
|
|
29
|
+
>>> x = u.Q(jnp.array([1.0, 1.2, 0.9]), "kpc")
|
|
30
|
+
>>> M = unitful(masked, galactic, rewrap=False)
|
|
31
|
+
>>> p = {"m": jnp.asarray(1.0), "x_unobserved": jnp.zeros(3)}
|
|
32
|
+
>>> logp, _ = log_density(M, (x,), {}, p)
|
|
33
|
+
>>> round(float(logp), 1)
|
|
34
|
+
-5.3
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
NumPyro splits the site into `x_observed` and `x_unobserved`. Use those names in `units=` and in `M.site_units`.
|
|
39
|
+
|
|
40
|
+
## Subsample observations
|
|
41
|
+
|
|
42
|
+
`numpyro.subsample` does not accept a `Quantity`. Index the data with the plate's indices instead:
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
>>> def sub_model(x):
|
|
46
|
+
... m = numpyro.sample("m", dist.Normal(u.Q(0.0, "kpc"), u.Q(3.0, "kpc")))
|
|
47
|
+
... with numpyro.plate("n", 100, subsample_size=10) as idx:
|
|
48
|
+
... numpyro.sample("x", dist.Normal(m, u.Q(1.0, "kpc")), obs=x[idx])
|
|
49
|
+
|
|
50
|
+
>>> x = u.Q(jnp.linspace(0.0, 2.0, 100), "kpc")
|
|
51
|
+
>>> tr = handlers.trace(handlers.seed(unitful(sub_model, galactic), 0)).get_trace(x)
|
|
52
|
+
>>> tr["x"]["value"].shape
|
|
53
|
+
(10,)
|
|
54
|
+
|
|
55
|
+
```
|