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.
Files changed (43) hide show
  1. unxts_interop_numpyro-2.2.0/.gitignore +169 -0
  2. unxts_interop_numpyro-2.2.0/LICENSE +29 -0
  3. unxts_interop_numpyro-2.2.0/PKG-INFO +63 -0
  4. unxts_interop_numpyro-2.2.0/README.md +36 -0
  5. unxts_interop_numpyro-2.2.0/docs/concepts/handler-order.md +32 -0
  6. unxts_interop_numpyro-2.2.0/docs/concepts/index.md +15 -0
  7. unxts_interop_numpyro-2.2.0/docs/concepts/sites.md +33 -0
  8. unxts_interop_numpyro-2.2.0/docs/concepts/unit-systems.md +27 -0
  9. unxts_interop_numpyro-2.2.0/docs/guides/fit-with-svi.md +79 -0
  10. unxts_interop_numpyro-2.2.0/docs/guides/give-a-site-units.md +68 -0
  11. unxts_interop_numpyro-2.2.0/docs/guides/index.md +25 -0
  12. unxts_interop_numpyro-2.2.0/docs/guides/mask-and-subsample.md +55 -0
  13. unxts_interop_numpyro-2.2.0/docs/guides/place-handlers.md +75 -0
  14. unxts_interop_numpyro-2.2.0/docs/guides/run-mcmc.md +78 -0
  15. unxts_interop_numpyro-2.2.0/docs/guides/troubleshooting.md +77 -0
  16. unxts_interop_numpyro-2.2.0/docs/guides/use-jnp-code.md +52 -0
  17. unxts_interop_numpyro-2.2.0/docs/guides/use-scan-and-cond.md +85 -0
  18. unxts_interop_numpyro-2.2.0/docs/index.md +76 -0
  19. unxts_interop_numpyro-2.2.0/docs/reference/api.md +15 -0
  20. unxts_interop_numpyro-2.2.0/docs/reference/behaviour.md +154 -0
  21. unxts_interop_numpyro-2.2.0/docs/reference/errors.md +149 -0
  22. unxts_interop_numpyro-2.2.0/docs/reference/glossary.md +34 -0
  23. unxts_interop_numpyro-2.2.0/docs/reference/unit-rules.md +79 -0
  24. unxts_interop_numpyro-2.2.0/docs/tutorial-fit-mean-and-width.md +101 -0
  25. unxts_interop_numpyro-2.2.0/pyproject.toml +80 -0
  26. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/__init__.py +14 -0
  27. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/__init__.py +3 -0
  28. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/handler.py +684 -0
  29. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/patches.py +106 -0
  30. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/rules.py +302 -0
  31. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_src/samples.py +49 -0
  32. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/_version.py +24 -0
  33. unxts_interop_numpyro-2.2.0/src/unxts/interop/numpyro/py.typed +0 -0
  34. unxts_interop_numpyro-2.2.0/tests/conftest.py +26 -0
  35. unxts_interop_numpyro-2.2.0/tests/integration/test_inference.py +541 -0
  36. unxts_interop_numpyro-2.2.0/tests/smoke/test_public_api.py +12 -0
  37. unxts_interop_numpyro-2.2.0/tests/unit/test_attach_units.py +72 -0
  38. unxts_interop_numpyro-2.2.0/tests/unit/test_other_sites.py +316 -0
  39. unxts_interop_numpyro-2.2.0/tests/unit/test_outer_values.py +213 -0
  40. unxts_interop_numpyro-2.2.0/tests/unit/test_patches.py +124 -0
  41. unxts_interop_numpyro-2.2.0/tests/unit/test_rules.py +188 -0
  42. unxts_interop_numpyro-2.2.0/tests/unit/test_sample_sites.py +814 -0
  43. 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
+ ```