priorities 0.1.0__py3-none-any.whl
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.
- priorities/__init__.py +47 -0
- priorities/_composite.py +257 -0
- priorities/_distribution.py +158 -0
- priorities/_records.py +335 -0
- priorities/_transform.py +86 -0
- priorities/_version.py +24 -0
- priorities/testing.py +147 -0
- priorities-0.1.0.dist-info/METADATA +195 -0
- priorities-0.1.0.dist-info/RECORD +11 -0
- priorities-0.1.0.dist-info/WHEEL +4 -0
- priorities-0.1.0.dist-info/licenses/LICENSE +21 -0
priorities/__init__.py
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""Probability distributions as Equinox records.
|
|
2
|
+
|
|
3
|
+
A distribution gives a log density against ``d(value)``, draws, and, where it has one,
|
|
4
|
+
a map to and from the unit cube. The free functions ``to_real``, ``from_real``
|
|
5
|
+
and ``real_log_prob`` add the default transform to unconstrained coordinates.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
try:
|
|
9
|
+
from priorities._version import __version__
|
|
10
|
+
except ImportError: # pragma: no cover - source tree without a generated version file
|
|
11
|
+
try:
|
|
12
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
13
|
+
|
|
14
|
+
__version__ = version("priorities")
|
|
15
|
+
except PackageNotFoundError:
|
|
16
|
+
__version__ = "0.0.0+unknown"
|
|
17
|
+
|
|
18
|
+
from priorities._composite import Mixture, MultivariateNormal, TruncatedDistribution
|
|
19
|
+
from priorities._distribution import AbstractDistribution
|
|
20
|
+
from priorities._records import (
|
|
21
|
+
Beta,
|
|
22
|
+
HalfNormal,
|
|
23
|
+
LogNormal,
|
|
24
|
+
LogUniform,
|
|
25
|
+
Normal,
|
|
26
|
+
Rayleigh,
|
|
27
|
+
Uniform,
|
|
28
|
+
)
|
|
29
|
+
from priorities._transform import from_real, real_log_prob, to_real
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"AbstractDistribution",
|
|
33
|
+
"Beta",
|
|
34
|
+
"HalfNormal",
|
|
35
|
+
"LogNormal",
|
|
36
|
+
"LogUniform",
|
|
37
|
+
"Mixture",
|
|
38
|
+
"MultivariateNormal",
|
|
39
|
+
"Normal",
|
|
40
|
+
"Rayleigh",
|
|
41
|
+
"TruncatedDistribution",
|
|
42
|
+
"Uniform",
|
|
43
|
+
"__version__",
|
|
44
|
+
"from_real",
|
|
45
|
+
"real_log_prob",
|
|
46
|
+
"to_real",
|
|
47
|
+
]
|
priorities/_composite.py
ADDED
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
"""Records built on other distributions or on one event axis."""
|
|
2
|
+
|
|
3
|
+
from typing import ClassVar
|
|
4
|
+
|
|
5
|
+
import equinox as eqx
|
|
6
|
+
import jax
|
|
7
|
+
import jax.numpy as jnp
|
|
8
|
+
from jax import Array
|
|
9
|
+
from jax.scipy.linalg import solve_triangular
|
|
10
|
+
from jax.scipy.special import logsumexp, ndtr, ndtri
|
|
11
|
+
|
|
12
|
+
from priorities._distribution import (
|
|
13
|
+
AbstractDistribution,
|
|
14
|
+
as_float,
|
|
15
|
+
debug_check,
|
|
16
|
+
finish,
|
|
17
|
+
is_valid,
|
|
18
|
+
quantile,
|
|
19
|
+
unit_draws,
|
|
20
|
+
)
|
|
21
|
+
from priorities._records import _LOG_SQRT_2PI
|
|
22
|
+
|
|
23
|
+
_BOUNDS = {
|
|
24
|
+
(False, False): "real",
|
|
25
|
+
(True, False): "lower",
|
|
26
|
+
(False, True): "upper",
|
|
27
|
+
(True, True): "interval",
|
|
28
|
+
}
|
|
29
|
+
_solve_lower = jnp.vectorize(
|
|
30
|
+
lambda cholesky, rhs: solve_triangular(cholesky, rhs, lower=True),
|
|
31
|
+
signature="(d,d),(d)->(d)",
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _optional(x):
|
|
36
|
+
return None if x is None else as_float(x)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class TruncatedDistribution(AbstractDistribution):
|
|
40
|
+
"""A scalar distribution conditioned on ``low <= value <= high``.
|
|
41
|
+
|
|
42
|
+
Which sides are cut is static: a side left as ``None`` is not cut and adds
|
|
43
|
+
no leaf, so the uncut distribution keeps its own gradients and its own draw. The
|
|
44
|
+
support is closed at a finite cut. Cuts far in a tail lose precision,
|
|
45
|
+
because the normalizer is a difference of distribution-function values.
|
|
46
|
+
|
|
47
|
+
A truncated ``Beta`` is not differentiable in the Beta shapes (see
|
|
48
|
+
``Beta``). Taking a gradient with respect to a pytree that holds one
|
|
49
|
+
raises ``ValueError`` even if those gradients are unused, so keep such a
|
|
50
|
+
distribution out of the differentiated partition.
|
|
51
|
+
|
|
52
|
+
Attributes:
|
|
53
|
+
base: Scalar distribution with an inverse CDF.
|
|
54
|
+
low: Lower cut, or ``None``.
|
|
55
|
+
high: Upper cut, or ``None``.
|
|
56
|
+
"""
|
|
57
|
+
|
|
58
|
+
base_dist: AbstractDistribution
|
|
59
|
+
low: Array | None = eqx.field(default=None, converter=_optional)
|
|
60
|
+
high: Array | None = eqx.field(default=None, converter=_optional)
|
|
61
|
+
event_dim: ClassVar[int] = 0
|
|
62
|
+
has_icdf: ClassVar[bool] = True
|
|
63
|
+
|
|
64
|
+
def __check_init__(self):
|
|
65
|
+
if self.base_dist.event_dim != 0 or not self.base_dist.has_icdf:
|
|
66
|
+
raise ValueError(
|
|
67
|
+
"TruncatedDistribution needs a scalar base_dist with an inverse CDF"
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
@property
|
|
71
|
+
def bounds(self) -> str:
|
|
72
|
+
"""Bounded sides of the support: those of the base plus the cuts."""
|
|
73
|
+
lower = self.low is not None or self.base_dist.bounds in ("lower", "interval")
|
|
74
|
+
upper = self.high is not None or self.base_dist.bounds in ("upper", "interval")
|
|
75
|
+
return _BOUNDS[lower, upper]
|
|
76
|
+
|
|
77
|
+
def _mass(self):
|
|
78
|
+
"""Base probability below the lower cut, and between the cuts."""
|
|
79
|
+
below = 0.0 if self.low is None else self.base_dist.cdf(self.low)
|
|
80
|
+
above = 1.0 if self.high is None else self.base_dist.cdf(self.high)
|
|
81
|
+
return below, above - below
|
|
82
|
+
|
|
83
|
+
def support(self):
|
|
84
|
+
low, high = self.base_dist.support()
|
|
85
|
+
low = low if self.low is None else jnp.maximum(low, self.low)
|
|
86
|
+
high = high if self.high is None else jnp.minimum(high, self.high)
|
|
87
|
+
valid = self._mass()[1] > 0
|
|
88
|
+
low, high = (jnp.where(valid, bound, jnp.nan) for bound in (low, high))
|
|
89
|
+
return tuple(jnp.broadcast_arrays(low, high))
|
|
90
|
+
|
|
91
|
+
def log_prob(self, value):
|
|
92
|
+
low, high = self.support()
|
|
93
|
+
out = self.base_dist.log_prob(value) - jnp.log(self._mass()[1])
|
|
94
|
+
return finish(self, out, value, (value >= low) & (value <= high), -jnp.inf)
|
|
95
|
+
|
|
96
|
+
def sample(self, key, sample_shape=()):
|
|
97
|
+
return self.icdf(unit_draws(self, key, sample_shape))
|
|
98
|
+
|
|
99
|
+
def cdf(self, value):
|
|
100
|
+
low, high = self.support()
|
|
101
|
+
below, mass = self._mass()
|
|
102
|
+
out = (self.base_dist.cdf(jnp.clip(value, low, high)) - below) / mass
|
|
103
|
+
out = jnp.where(value >= high, 1.0, jnp.clip(out, 0.0, 1.0))
|
|
104
|
+
return finish(self, out, value)
|
|
105
|
+
|
|
106
|
+
def icdf(self, q):
|
|
107
|
+
below, mass = self._mass()
|
|
108
|
+
base_unit = jnp.clip(below + q * mass, 0.0, 1.0)
|
|
109
|
+
return quantile(self, self.base_dist.icdf(base_unit), q)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class MultivariateNormal(AbstractDistribution):
|
|
113
|
+
"""Normal distribution over one event axis of length ``d``.
|
|
114
|
+
|
|
115
|
+
For an event distribution ``cdf`` and ``icdf`` map to and from the unit
|
|
116
|
+
cube rather than computing the joint distribution function: ``cdf``
|
|
117
|
+
applies the standard normal distribution function to
|
|
118
|
+
``solve(scale_tril, value - loc)``, and ``icdf`` inverts it.
|
|
119
|
+
|
|
120
|
+
Attributes:
|
|
121
|
+
loc: Mean, shape ``(..., d)``.
|
|
122
|
+
scale_tril: Lower-triangular factor of the covariance with a positive
|
|
123
|
+
diagonal, shape ``(..., d, d)``.
|
|
124
|
+
"""
|
|
125
|
+
|
|
126
|
+
loc: Array = eqx.field(converter=as_float)
|
|
127
|
+
scale_tril: Array = eqx.field(converter=as_float)
|
|
128
|
+
event_dim: ClassVar[int] = 1
|
|
129
|
+
bounds: ClassVar[str] = "real"
|
|
130
|
+
has_icdf: ClassVar[bool] = True
|
|
131
|
+
|
|
132
|
+
def __check_init__(self):
|
|
133
|
+
size = self.loc.shape[-1:]
|
|
134
|
+
if self.loc.ndim < 1 or self.scale_tril.shape[-2:] != size + size:
|
|
135
|
+
raise ValueError("loc must be (..., d) and scale_tril (..., d, d)")
|
|
136
|
+
|
|
137
|
+
def _diagonal(self):
|
|
138
|
+
return jnp.diagonal(self.scale_tril, axis1=-2, axis2=-1)
|
|
139
|
+
|
|
140
|
+
def support(self):
|
|
141
|
+
triangular = jnp.all(jnp.triu(self.scale_tril, 1) == 0, (-2, -1))
|
|
142
|
+
valid = triangular & jnp.all(self._diagonal() > 0, -1)
|
|
143
|
+
shape = jnp.broadcast_shapes(self.loc.shape, self.scale_tril.shape[:-1])
|
|
144
|
+
high = jnp.broadcast_to(jnp.where(valid[..., None], jnp.inf, jnp.nan), shape)
|
|
145
|
+
return -high, high
|
|
146
|
+
|
|
147
|
+
def _status(self, arg):
|
|
148
|
+
"""Batch mask: 0 if usable, -inf if invalid, NaN for a NaN input."""
|
|
149
|
+
nan = jnp.isnan(arg).any(-1) | jnp.isnan(self.loc).any(-1)
|
|
150
|
+
nan = nan | jnp.isnan(self.scale_tril).any((-2, -1))
|
|
151
|
+
status = jnp.where(is_valid(self), 0.0, -jnp.inf)
|
|
152
|
+
return jnp.where(nan, jnp.nan, debug_check(self, status))
|
|
153
|
+
|
|
154
|
+
def _mask(self, out, arg):
|
|
155
|
+
return jnp.where(self._status(arg)[..., None] == 0, out, jnp.nan)
|
|
156
|
+
|
|
157
|
+
def _whiten(self, value):
|
|
158
|
+
return _solve_lower(self.scale_tril, value - self.loc)
|
|
159
|
+
|
|
160
|
+
def _color(self, noise):
|
|
161
|
+
return self.loc + jnp.einsum("...ij,...j->...i", self.scale_tril, noise)
|
|
162
|
+
|
|
163
|
+
def log_prob(self, value):
|
|
164
|
+
z = self._whiten(value)
|
|
165
|
+
log_det = jnp.sum(jnp.log(self._diagonal()), -1)
|
|
166
|
+
out = -0.5 * jnp.sum(z**2, -1) - log_det - z.shape[-1] * _LOG_SQRT_2PI
|
|
167
|
+
status = self._status(value)
|
|
168
|
+
return jnp.where(status == 0, out, status)
|
|
169
|
+
|
|
170
|
+
def sample(self, key, sample_shape=()):
|
|
171
|
+
sample_shape = tuple(sample_shape) + self.support()[0].shape
|
|
172
|
+
dtype = jnp.result_type(self.loc, self.scale_tril)
|
|
173
|
+
noise = jax.random.normal(key, sample_shape, dtype)
|
|
174
|
+
return self._mask(self._color(noise), noise)
|
|
175
|
+
|
|
176
|
+
def cdf(self, value):
|
|
177
|
+
return self._mask(ndtr(self._whiten(value)), value)
|
|
178
|
+
|
|
179
|
+
def icdf(self, q):
|
|
180
|
+
inside = jnp.where((q >= 0) & (q <= 1), q, jnp.nan)
|
|
181
|
+
return self._mask(self._color(ndtri(inside)), q)
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
class Mixture(AbstractDistribution):
|
|
185
|
+
"""Weighted mixture of ``K`` distributions of one family.
|
|
186
|
+
|
|
187
|
+
The components are one distribution whose batch has a last axis of length ``K``,
|
|
188
|
+
for example ``Normal(loc, scale)`` with parameters of shape ``(K,)``. A
|
|
189
|
+
scalar mixture has a distribution function (``cdf``) but no quantile,
|
|
190
|
+
so ``has_icdf`` is false and ``icdf`` raises.
|
|
191
|
+
|
|
192
|
+
Attributes:
|
|
193
|
+
mixing_logits: Unnormalized log weights, shape ``(..., K)``. They are
|
|
194
|
+
normalized internally.
|
|
195
|
+
components: Distribution holding the ``K`` components.
|
|
196
|
+
"""
|
|
197
|
+
|
|
198
|
+
mixing_logits: Array = eqx.field(converter=as_float)
|
|
199
|
+
component_distribution: AbstractDistribution
|
|
200
|
+
has_icdf: ClassVar[bool] = False
|
|
201
|
+
|
|
202
|
+
@property
|
|
203
|
+
def event_dim(self) -> int:
|
|
204
|
+
"""Event rank of the components."""
|
|
205
|
+
return self.component_distribution.event_dim
|
|
206
|
+
|
|
207
|
+
@property
|
|
208
|
+
def bounds(self) -> str:
|
|
209
|
+
"""Bounded sides of the components."""
|
|
210
|
+
return self.component_distribution.bounds
|
|
211
|
+
|
|
212
|
+
def _log_mix(self):
|
|
213
|
+
return jax.nn.log_softmax(self.mixing_logits, -1)
|
|
214
|
+
|
|
215
|
+
def _per_component(self, value):
|
|
216
|
+
"""Insert the component axis in front of the event axes."""
|
|
217
|
+
return jnp.expand_dims(value, -1 - self.event_dim)
|
|
218
|
+
|
|
219
|
+
def _over_event(self, mask):
|
|
220
|
+
return mask[..., None] if self.event_dim else mask
|
|
221
|
+
|
|
222
|
+
def support(self):
|
|
223
|
+
low, high = self.component_distribution.support()
|
|
224
|
+
axis = -1 - self.event_dim
|
|
225
|
+
valid = jnp.isfinite(logsumexp(self.mixing_logits, -1))
|
|
226
|
+
valid = self._over_event(valid)
|
|
227
|
+
low = jnp.where(valid, low.min(axis), jnp.nan)
|
|
228
|
+
return low, jnp.where(valid, high.max(axis), jnp.nan)
|
|
229
|
+
|
|
230
|
+
def log_prob(self, value):
|
|
231
|
+
parts = self.component_distribution.log_prob(self._per_component(value))
|
|
232
|
+
terms = self._log_mix() + parts
|
|
233
|
+
some = jnp.any(terms > -jnp.inf, -1) & is_valid(self)
|
|
234
|
+
out = logsumexp(jnp.where(some[..., None], terms, 0.0), -1)
|
|
235
|
+
out = jnp.where(some, debug_check(self, out), -jnp.inf)
|
|
236
|
+
nan = jnp.isnan(parts).any(-1) | jnp.isnan(self.mixing_logits).any(-1)
|
|
237
|
+
return jnp.where(nan, jnp.nan, out)
|
|
238
|
+
|
|
239
|
+
def sample(self, key, sample_shape=()):
|
|
240
|
+
key_index, key_draw = jax.random.split(key)
|
|
241
|
+
draws = self.component_distribution.sample(key_draw, sample_shape)
|
|
242
|
+
lead = draws.shape[: draws.ndim - 1 - self.event_dim]
|
|
243
|
+
index = jax.random.categorical(key_index, self.mixing_logits, shape=lead)
|
|
244
|
+
index = self._over_event(index[..., None])
|
|
245
|
+
out = jnp.take_along_axis(draws, index, -1 - self.event_dim)
|
|
246
|
+
out = out.squeeze(-1 - self.event_dim)
|
|
247
|
+
return jnp.where(self._over_event(is_valid(self)), out, jnp.nan)
|
|
248
|
+
|
|
249
|
+
def cdf(self, value):
|
|
250
|
+
if self.event_dim:
|
|
251
|
+
raise NotImplementedError("a Mixture over an event axis has no cdf")
|
|
252
|
+
parts = self.component_distribution.cdf(self._per_component(value))
|
|
253
|
+
out = jnp.sum(jnp.exp(self._log_mix()) * parts, -1)
|
|
254
|
+
return jnp.where(is_valid(self), debug_check(self, out), jnp.nan)
|
|
255
|
+
|
|
256
|
+
def icdf(self, q):
|
|
257
|
+
raise NotImplementedError("Mixture has no quantile; has_icdf is False")
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
"""The distribution interface and the helpers shared by the scalar records."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
from abc import abstractmethod
|
|
5
|
+
|
|
6
|
+
import equinox as eqx
|
|
7
|
+
import jax
|
|
8
|
+
import jax.numpy as jnp
|
|
9
|
+
from jax import Array
|
|
10
|
+
|
|
11
|
+
# Read once at import. When on, a distribution evaluated with parameters outside their
|
|
12
|
+
# domain raises through eqx.error_if instead of returning -inf or NaN.
|
|
13
|
+
DEBUG_CHECKS = os.environ.get("PRIORITIES_DEBUG_CHECKS", "0") == "1"
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class AbstractDistribution(eqx.Module):
|
|
17
|
+
"""A probability distribution: a density against ``d(value)`` with its draws.
|
|
18
|
+
|
|
19
|
+
A distribution is a record of array parameters. It is elementwise (``event_dim``
|
|
20
|
+
0) or has one event axis (``event_dim`` 1). Shapes follow one rule: a
|
|
21
|
+
value is ``sample + batch + event``, where ``batch`` is the broadcast of
|
|
22
|
+
the parameter shapes. The output dtype is the promotion of the argument
|
|
23
|
+
and the parameters, so a distribution built from Python floats returns the dtype
|
|
24
|
+
of its argument.
|
|
25
|
+
|
|
26
|
+
Subclass this directly when the mathematics is new. A named distribution that only
|
|
27
|
+
fixes defaults of an existing record is a function returning that record.
|
|
28
|
+
|
|
29
|
+
Attributes:
|
|
30
|
+
event_dim: Number of event axes, 0 or 1. Static.
|
|
31
|
+
bounds: Which sides of the support are bounded: ``"real"``,
|
|
32
|
+
``"lower"``, ``"upper"`` or ``"interval"``. Static, so the default
|
|
33
|
+
transform is chosen before tracing.
|
|
34
|
+
has_icdf: Whether ``cdf`` and ``icdf`` form a bijection
|
|
35
|
+
between the support and the unit cube. Static; test it before
|
|
36
|
+
building a sampler that needs the map.
|
|
37
|
+
"""
|
|
38
|
+
|
|
39
|
+
event_dim: eqx.AbstractVar[int]
|
|
40
|
+
bounds: eqx.AbstractVar[str]
|
|
41
|
+
has_icdf: eqx.AbstractVar[bool]
|
|
42
|
+
|
|
43
|
+
def __check_init__(self):
|
|
44
|
+
"""Refuse concrete parameters outside their domain; skip tracers."""
|
|
45
|
+
valid = is_valid(self)
|
|
46
|
+
if not isinstance(valid, jax.core.Tracer) and not bool(jnp.all(valid)):
|
|
47
|
+
raise ValueError(f"parameters outside their domain: {self}")
|
|
48
|
+
|
|
49
|
+
@abstractmethod
|
|
50
|
+
def support(self) -> tuple[Array, Array]:
|
|
51
|
+
"""Return the bounds ``(low, high)`` of the support.
|
|
52
|
+
|
|
53
|
+
Each has shape ``batch + event`` and is infinite on an unbounded side.
|
|
54
|
+
An endpoint belongs to the support when the density there is finite.
|
|
55
|
+
Both are NaN where the parameters are outside their domain.
|
|
56
|
+
"""
|
|
57
|
+
|
|
58
|
+
@abstractmethod
|
|
59
|
+
def log_prob(self, value: Array) -> Array:
|
|
60
|
+
"""Return the log density against ``d(value)``, reduced over the event.
|
|
61
|
+
|
|
62
|
+
The result is exactly ``-inf`` outside the support, with a zero
|
|
63
|
+
gradient there, and for parameters outside their domain. It is NaN
|
|
64
|
+
when the value or a parameter is NaN.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
@abstractmethod
|
|
68
|
+
def sample(self, key: Array, sample_shape: tuple[int, ...] = ()) -> Array:
|
|
69
|
+
"""Draw values of shape ``sample_shape + batch + event``.
|
|
70
|
+
|
|
71
|
+
The dtype is the promotion of the parameters. Draws are NaN for
|
|
72
|
+
parameters outside their domain.
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
@abstractmethod
|
|
76
|
+
def cdf(self, value: Array) -> Array:
|
|
77
|
+
"""Map a value to the unit cube of the event shape.
|
|
78
|
+
|
|
79
|
+
For a scalar distribution this is the cumulative distribution function. NaN for
|
|
80
|
+
parameters outside their domain. Raises ``NotImplementedError`` when
|
|
81
|
+
the distribution has no such function.
|
|
82
|
+
"""
|
|
83
|
+
|
|
84
|
+
@abstractmethod
|
|
85
|
+
def icdf(self, q: Array) -> Array:
|
|
86
|
+
"""Map a point of the unit cube to a value: uniform in, the distribution out.
|
|
87
|
+
|
|
88
|
+
For a scalar distribution this is the quantile function. It returns the support
|
|
89
|
+
endpoints at 0 and 1 and NaN outside ``[0, 1]`` or for parameters
|
|
90
|
+
outside their domain. Raises ``NotImplementedError`` when
|
|
91
|
+
``has_icdf`` is false.
|
|
92
|
+
"""
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def as_float(x) -> Array:
|
|
96
|
+
"""Convert a parameter to a floating array, keeping weak types."""
|
|
97
|
+
x = jnp.asarray(x)
|
|
98
|
+
return x if jnp.issubdtype(x.dtype, jnp.inexact) else x * 1.0
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def is_valid(dist: AbstractDistribution) -> Array:
|
|
102
|
+
"""Return the batch-shaped mask of parameters inside their domain."""
|
|
103
|
+
low, high = dist.support()
|
|
104
|
+
invalid = jnp.isnan(low) | jnp.isnan(high)
|
|
105
|
+
return ~(invalid.any(-1) if dist.event_dim else invalid)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def debug_check(dist: AbstractDistribution, out: Array) -> Array:
|
|
109
|
+
"""Raise at run time for invalid parameters when the debug flag is on."""
|
|
110
|
+
if DEBUG_CHECKS:
|
|
111
|
+
message = f"{type(dist).__name__}: parameters outside their domain"
|
|
112
|
+
out = eqx.error_if(out, ~is_valid(dist), message)
|
|
113
|
+
return out
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def draw_spec(dist: AbstractDistribution, shape: tuple[int, ...]):
|
|
117
|
+
"""Return the shape ``shape + batch`` and dtype of scalar-distribution draws."""
|
|
118
|
+
leaves = jax.tree_util.tree_leaves(dist)
|
|
119
|
+
batch = jnp.broadcast_shapes(*(leaf.shape for leaf in leaves))
|
|
120
|
+
return tuple(shape) + batch, jnp.result_type(*leaves)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def bounded(dist: AbstractDistribution, valid, low, high) -> tuple[Array, Array]:
|
|
124
|
+
"""Broadcast scalar-distribution bounds over the batch; NaN where not ``valid``."""
|
|
125
|
+
shape, _ = draw_spec(dist, ())
|
|
126
|
+
low, high = (jnp.where(valid, bound, jnp.nan) for bound in (low, high))
|
|
127
|
+
return jnp.broadcast_to(low, shape), jnp.broadcast_to(high, shape)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def finish(
|
|
131
|
+
dist: AbstractDistribution, out, arg=0.0, inside=True, fill=jnp.nan
|
|
132
|
+
) -> Array:
|
|
133
|
+
"""Mask the result of a scalar distribution.
|
|
134
|
+
|
|
135
|
+
``fill`` replaces ``out`` outside ``inside`` and for invalid parameters;
|
|
136
|
+
NaN replaces it where ``arg`` or a parameter is NaN.
|
|
137
|
+
"""
|
|
138
|
+
inputs = (arg, *jax.tree_util.tree_leaves(dist))
|
|
139
|
+
nan = sum(jnp.isnan(x) for x in inputs) > 0
|
|
140
|
+
out = jnp.where(is_valid(dist) & inside, debug_check(dist, out), fill)
|
|
141
|
+
# Adding typed zeros promotes to the inputs' dtype and keeps weak types.
|
|
142
|
+
return jnp.where(nan, jnp.nan, out) + sum(jnp.zeros_like(x) for x in inputs)
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def unit_draws(dist: AbstractDistribution, key: Array, shape: tuple[int, ...]) -> Array:
|
|
146
|
+
"""Draw uniforms on the open unit interval for a quantile-based sample."""
|
|
147
|
+
shape, dtype = draw_spec(dist, shape)
|
|
148
|
+
tiny = jnp.finfo(dtype).tiny
|
|
149
|
+
return jax.random.uniform(key, shape, dtype, minval=tiny)
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def quantile(dist: AbstractDistribution, out, unit) -> Array:
|
|
153
|
+
"""Finish a scalar ``icdf``: exact endpoints, NaN off ``[0, 1]``."""
|
|
154
|
+
low, high = dist.support()
|
|
155
|
+
out = jnp.where(
|
|
156
|
+
unit <= 0, low, jnp.where(unit >= 1, high, jnp.clip(out, low, high))
|
|
157
|
+
)
|
|
158
|
+
return finish(dist, out, unit, (unit >= 0) & (unit <= 1))
|
priorities/_records.py
ADDED
|
@@ -0,0 +1,335 @@
|
|
|
1
|
+
"""Elementwise records: one distribution per class, array parameters only."""
|
|
2
|
+
|
|
3
|
+
import math
|
|
4
|
+
from typing import ClassVar
|
|
5
|
+
|
|
6
|
+
import equinox as eqx
|
|
7
|
+
import jax
|
|
8
|
+
import jax.numpy as jnp
|
|
9
|
+
from jax import Array
|
|
10
|
+
from jax.custom_derivatives import SymbolicZero
|
|
11
|
+
from jax.scipy.special import betainc, betaln, erf, erfinv, ndtr, ndtri
|
|
12
|
+
|
|
13
|
+
from priorities._distribution import (
|
|
14
|
+
AbstractDistribution,
|
|
15
|
+
as_float,
|
|
16
|
+
bounded,
|
|
17
|
+
draw_spec,
|
|
18
|
+
finish,
|
|
19
|
+
quantile,
|
|
20
|
+
unit_draws,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
_LOG_SQRT_2PI = 0.5 * math.log(2 * math.pi)
|
|
24
|
+
_SQRT_2 = math.sqrt(2.0)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Uniform(AbstractDistribution):
|
|
28
|
+
"""Uniform distribution on the closed interval ``[low, high]``.
|
|
29
|
+
|
|
30
|
+
Attributes:
|
|
31
|
+
low: Lower bound, finite.
|
|
32
|
+
high: Upper bound, finite and above ``low``.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
low: Array = eqx.field(converter=as_float)
|
|
36
|
+
high: Array = eqx.field(converter=as_float)
|
|
37
|
+
event_dim: ClassVar[int] = 0
|
|
38
|
+
bounds: ClassVar[str] = "interval"
|
|
39
|
+
has_icdf: ClassVar[bool] = True
|
|
40
|
+
|
|
41
|
+
def support(self):
|
|
42
|
+
valid = (self.low < self.high) & jnp.isfinite(self.high - self.low)
|
|
43
|
+
return bounded(self, valid, self.low, self.high)
|
|
44
|
+
|
|
45
|
+
def log_prob(self, value):
|
|
46
|
+
inside = (value >= self.low) & (value <= self.high)
|
|
47
|
+
return finish(self, -jnp.log(self.high - self.low), value, inside, -jnp.inf)
|
|
48
|
+
|
|
49
|
+
def sample(self, key, sample_shape=()):
|
|
50
|
+
return self.icdf(unit_draws(self, key, sample_shape))
|
|
51
|
+
|
|
52
|
+
def cdf(self, value):
|
|
53
|
+
clipped = jnp.clip(value, self.low, self.high)
|
|
54
|
+
return finish(self, (clipped - self.low) / (self.high - self.low), value)
|
|
55
|
+
|
|
56
|
+
def icdf(self, q):
|
|
57
|
+
return quantile(self, self.low + q * (self.high - self.low), q)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class LogUniform(AbstractDistribution):
|
|
61
|
+
"""Distribution with density proportional to ``1 / value`` on ``[low, high]``.
|
|
62
|
+
|
|
63
|
+
Attributes:
|
|
64
|
+
low: Lower bound, positive.
|
|
65
|
+
high: Upper bound, finite and above ``low``.
|
|
66
|
+
"""
|
|
67
|
+
|
|
68
|
+
low: Array = eqx.field(converter=as_float)
|
|
69
|
+
high: Array = eqx.field(converter=as_float)
|
|
70
|
+
event_dim: ClassVar[int] = 0
|
|
71
|
+
bounds: ClassVar[str] = "interval"
|
|
72
|
+
has_icdf: ClassVar[bool] = True
|
|
73
|
+
|
|
74
|
+
def support(self):
|
|
75
|
+
valid = (self.low > 0) & (self.low < self.high) & jnp.isfinite(self.high)
|
|
76
|
+
return bounded(self, valid, self.low, self.high)
|
|
77
|
+
|
|
78
|
+
def _log_ratio(self):
|
|
79
|
+
return jnp.log(self.high / self.low)
|
|
80
|
+
|
|
81
|
+
def log_prob(self, value):
|
|
82
|
+
inside = (value >= self.low) & (value <= self.high)
|
|
83
|
+
safe = jnp.where(inside, value, 1.0)
|
|
84
|
+
out = -jnp.log(safe) - jnp.log(self._log_ratio())
|
|
85
|
+
return finish(self, out, value, inside, -jnp.inf)
|
|
86
|
+
|
|
87
|
+
def sample(self, key, sample_shape=()):
|
|
88
|
+
return self.icdf(unit_draws(self, key, sample_shape))
|
|
89
|
+
|
|
90
|
+
def cdf(self, value):
|
|
91
|
+
clipped = jnp.clip(value, self.low, self.high)
|
|
92
|
+
return finish(self, jnp.log(clipped / self.low) / self._log_ratio(), value)
|
|
93
|
+
|
|
94
|
+
def icdf(self, q):
|
|
95
|
+
return quantile(self, self.low * jnp.exp(q * self._log_ratio()), q)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
class Normal(AbstractDistribution):
|
|
99
|
+
"""Normal distribution.
|
|
100
|
+
|
|
101
|
+
Attributes:
|
|
102
|
+
loc: Mean.
|
|
103
|
+
scale: Standard deviation, positive.
|
|
104
|
+
"""
|
|
105
|
+
|
|
106
|
+
loc: Array = eqx.field(converter=as_float)
|
|
107
|
+
scale: Array = eqx.field(converter=as_float)
|
|
108
|
+
event_dim: ClassVar[int] = 0
|
|
109
|
+
bounds: ClassVar[str] = "real"
|
|
110
|
+
has_icdf: ClassVar[bool] = True
|
|
111
|
+
|
|
112
|
+
def support(self):
|
|
113
|
+
return bounded(self, self.scale > 0, -jnp.inf, jnp.inf)
|
|
114
|
+
|
|
115
|
+
def log_prob(self, value):
|
|
116
|
+
z = (value - self.loc) / self.scale
|
|
117
|
+
out = -0.5 * z**2 - jnp.log(self.scale) - _LOG_SQRT_2PI
|
|
118
|
+
return finish(self, out, value, fill=-jnp.inf)
|
|
119
|
+
|
|
120
|
+
def sample(self, key, sample_shape=()):
|
|
121
|
+
noise = jax.random.normal(key, *draw_spec(self, sample_shape))
|
|
122
|
+
return finish(self, self.loc + self.scale * noise)
|
|
123
|
+
|
|
124
|
+
def cdf(self, value):
|
|
125
|
+
return finish(self, ndtr((value - self.loc) / self.scale), value)
|
|
126
|
+
|
|
127
|
+
def icdf(self, q):
|
|
128
|
+
return quantile(self, self.loc + self.scale * ndtri(q), q)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class LogNormal(AbstractDistribution):
|
|
132
|
+
"""Distribution of ``exp(x)`` for a normal ``x``, on ``(0, inf)``.
|
|
133
|
+
|
|
134
|
+
Attributes:
|
|
135
|
+
loc: Mean of ``log(value)``.
|
|
136
|
+
scale: Standard deviation of ``log(value)``, positive.
|
|
137
|
+
"""
|
|
138
|
+
|
|
139
|
+
loc: Array = eqx.field(converter=as_float)
|
|
140
|
+
scale: Array = eqx.field(converter=as_float)
|
|
141
|
+
event_dim: ClassVar[int] = 0
|
|
142
|
+
bounds: ClassVar[str] = "lower"
|
|
143
|
+
has_icdf: ClassVar[bool] = True
|
|
144
|
+
|
|
145
|
+
def support(self):
|
|
146
|
+
return bounded(self, self.scale > 0, 0.0, jnp.inf)
|
|
147
|
+
|
|
148
|
+
def _z(self, value):
|
|
149
|
+
"""Standardized ``log(value)`` and the log itself, safe off-support."""
|
|
150
|
+
log_value = jnp.log(jnp.where(value > 0, value, 1.0))
|
|
151
|
+
return (log_value - self.loc) / self.scale, log_value
|
|
152
|
+
|
|
153
|
+
def log_prob(self, value):
|
|
154
|
+
z, log_value = self._z(value)
|
|
155
|
+
out = -0.5 * z**2 - jnp.log(self.scale) - _LOG_SQRT_2PI - log_value
|
|
156
|
+
return finish(self, out, value, value > 0, -jnp.inf)
|
|
157
|
+
|
|
158
|
+
def sample(self, key, sample_shape=()):
|
|
159
|
+
noise = jax.random.normal(key, *draw_spec(self, sample_shape))
|
|
160
|
+
return finish(self, jnp.exp(self.loc + self.scale * noise))
|
|
161
|
+
|
|
162
|
+
def cdf(self, value):
|
|
163
|
+
return finish(self, jnp.where(value > 0, ndtr(self._z(value)[0]), 0.0), value)
|
|
164
|
+
|
|
165
|
+
def icdf(self, q):
|
|
166
|
+
return quantile(self, jnp.exp(self.loc + self.scale * ndtri(q)), q)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
class HalfNormal(AbstractDistribution):
|
|
170
|
+
"""Distribution of ``|x|`` for a zero-mean normal ``x``, on ``[0, inf)``.
|
|
171
|
+
|
|
172
|
+
Attributes:
|
|
173
|
+
scale: Standard deviation of the underlying normal, positive.
|
|
174
|
+
"""
|
|
175
|
+
|
|
176
|
+
scale: Array = eqx.field(converter=as_float)
|
|
177
|
+
event_dim: ClassVar[int] = 0
|
|
178
|
+
bounds: ClassVar[str] = "lower"
|
|
179
|
+
has_icdf: ClassVar[bool] = True
|
|
180
|
+
|
|
181
|
+
def support(self):
|
|
182
|
+
return bounded(self, self.scale > 0, 0.0, jnp.inf)
|
|
183
|
+
|
|
184
|
+
def log_prob(self, value):
|
|
185
|
+
z = jnp.maximum(value, 0.0) / self.scale
|
|
186
|
+
out = math.log(2.0) - 0.5 * z**2 - jnp.log(self.scale) - _LOG_SQRT_2PI
|
|
187
|
+
return finish(self, out, value, value >= 0, -jnp.inf)
|
|
188
|
+
|
|
189
|
+
def sample(self, key, sample_shape=()):
|
|
190
|
+
noise = jax.random.normal(key, *draw_spec(self, sample_shape))
|
|
191
|
+
return finish(self, self.scale * jnp.abs(noise))
|
|
192
|
+
|
|
193
|
+
def cdf(self, value):
|
|
194
|
+
z = jnp.maximum(value, 0.0) / self.scale
|
|
195
|
+
return finish(self, erf(z / _SQRT_2), value)
|
|
196
|
+
|
|
197
|
+
def icdf(self, q):
|
|
198
|
+
return quantile(self, self.scale * _SQRT_2 * erfinv(q), q)
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
class Rayleigh(AbstractDistribution):
|
|
202
|
+
"""Rayleigh distribution on ``(0, inf)``; the density vanishes at zero.
|
|
203
|
+
|
|
204
|
+
Attributes:
|
|
205
|
+
scale: Mode of the density, positive.
|
|
206
|
+
"""
|
|
207
|
+
|
|
208
|
+
scale: Array = eqx.field(converter=as_float)
|
|
209
|
+
event_dim: ClassVar[int] = 0
|
|
210
|
+
bounds: ClassVar[str] = "lower"
|
|
211
|
+
has_icdf: ClassVar[bool] = True
|
|
212
|
+
|
|
213
|
+
def support(self):
|
|
214
|
+
return bounded(self, self.scale > 0, 0.0, jnp.inf)
|
|
215
|
+
|
|
216
|
+
def log_prob(self, value):
|
|
217
|
+
inside = (value > 0) & (value < jnp.inf)
|
|
218
|
+
safe = jnp.where(inside, value, 1.0)
|
|
219
|
+
out = jnp.log(safe) - 2 * jnp.log(self.scale) - 0.5 * (safe / self.scale) ** 2
|
|
220
|
+
return finish(self, out, value, inside, -jnp.inf)
|
|
221
|
+
|
|
222
|
+
def sample(self, key, sample_shape=()):
|
|
223
|
+
return self.icdf(unit_draws(self, key, sample_shape))
|
|
224
|
+
|
|
225
|
+
def cdf(self, value):
|
|
226
|
+
z = jnp.maximum(value, 0.0) / self.scale
|
|
227
|
+
return finish(self, -jnp.expm1(-0.5 * z**2), value)
|
|
228
|
+
|
|
229
|
+
def icdf(self, q):
|
|
230
|
+
return quantile(self, self.scale * jnp.sqrt(-2 * jnp.log1p(-q)), q)
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def _beta_log_kernel(a, b, value):
|
|
234
|
+
"""Beta log density at ``value`` in ``[0, 1]``, finite off the open interval."""
|
|
235
|
+
log_low = jnp.log(jnp.where(value > 0, value, 1.0))
|
|
236
|
+
log_high = jnp.log1p(-jnp.where(value < 1, value, 0.0))
|
|
237
|
+
# betaln may drop the weak type of Python-number shapes, which would
|
|
238
|
+
# promote a float32 value to float64; cast it to the promoted dtype.
|
|
239
|
+
log_norm = betaln(a, b).astype(jnp.result_type(a, b, value))
|
|
240
|
+
return (a - 1) * log_low + (b - 1) * log_high - log_norm
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
@jax.custom_jvp
|
|
244
|
+
def _beta_quantile(a, b, unit):
|
|
245
|
+
"""Solve ``betainc(a, b, x) = unit`` by bisection on ``log(x)``.
|
|
246
|
+
|
|
247
|
+
Bisecting the logarithm keeps relative accuracy in the lower tail, where
|
|
248
|
+
``x`` spans many decades for a shape below one. The iteration count is
|
|
249
|
+
static: twice the bit width closes the bracket from ``log(tiny)`` to
|
|
250
|
+
adjacent floats anywhere in ``(0, 1)``.
|
|
251
|
+
"""
|
|
252
|
+
dtype = jnp.result_type(a, b, unit)
|
|
253
|
+
finfo = jnp.finfo(dtype)
|
|
254
|
+
a, b, unit = jnp.broadcast_arrays(a, b, jnp.asarray(unit, dtype))
|
|
255
|
+
|
|
256
|
+
def halve(_, bracket):
|
|
257
|
+
low, high = bracket
|
|
258
|
+
middle = 0.5 * (low + high)
|
|
259
|
+
below = betainc(a, b, jnp.exp(middle)) < unit
|
|
260
|
+
return jnp.where(below, middle, low), jnp.where(below, high, middle)
|
|
261
|
+
|
|
262
|
+
bracket = (jnp.full(unit.shape, jnp.log(finfo.tiny)), jnp.zeros(unit.shape, dtype))
|
|
263
|
+
low, high = jax.lax.fori_loop(0, 2 * finfo.bits, halve, bracket)
|
|
264
|
+
return jnp.exp(0.5 * (low + high))
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
def _beta_quantile_jvp(primals, tangents):
|
|
268
|
+
"""Differentiate the quantile in ``unit`` only: ``dx/du = 1 / pdf(x)``."""
|
|
269
|
+
a, b, unit = primals
|
|
270
|
+
a_dot, b_dot, unit_dot = tangents
|
|
271
|
+
if not (isinstance(a_dot, SymbolicZero) and isinstance(b_dot, SymbolicZero)):
|
|
272
|
+
raise ValueError("the Beta quantile is not differentiable in its shapes")
|
|
273
|
+
root = _beta_quantile(a, b, unit)
|
|
274
|
+
if isinstance(unit_dot, SymbolicZero):
|
|
275
|
+
return root, jnp.zeros_like(root)
|
|
276
|
+
return root, unit_dot * jnp.exp(-_beta_log_kernel(a, b, root))
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
_beta_quantile.defjvp(_beta_quantile_jvp, symbolic_zeros=True)
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
class Beta(AbstractDistribution):
|
|
283
|
+
"""Beta distribution on ``(0, 1)``.
|
|
284
|
+
|
|
285
|
+
An endpoint is in the support only when its shape is exactly one, where
|
|
286
|
+
the density there is finite and positive. The density is differentiable in
|
|
287
|
+
the shapes. The distribution function and the quantile are not: JAX has no
|
|
288
|
+
derivative of ``betainc`` in its shapes, so differentiating ``cdf`` or
|
|
289
|
+
``icdf`` in ``a`` or ``b`` raises ``ValueError``. The quantile is
|
|
290
|
+
differentiable in its argument.
|
|
291
|
+
|
|
292
|
+
Attributes:
|
|
293
|
+
a: First shape, positive.
|
|
294
|
+
b: Second shape, positive.
|
|
295
|
+
"""
|
|
296
|
+
|
|
297
|
+
concentration1: Array = eqx.field(converter=as_float)
|
|
298
|
+
concentration0: Array = eqx.field(converter=as_float)
|
|
299
|
+
event_dim: ClassVar[int] = 0
|
|
300
|
+
bounds: ClassVar[str] = "interval"
|
|
301
|
+
has_icdf: ClassVar[bool] = True
|
|
302
|
+
|
|
303
|
+
def support(self):
|
|
304
|
+
return bounded(
|
|
305
|
+
self, (self.concentration1 > 0) & (self.concentration0 > 0), 0.0, 1.0
|
|
306
|
+
)
|
|
307
|
+
|
|
308
|
+
def log_prob(self, value):
|
|
309
|
+
low = (value > 0) | ((value == 0) & (self.concentration1 == 1))
|
|
310
|
+
high = (value < 1) | ((value == 1) & (self.concentration0 == 1))
|
|
311
|
+
out = _beta_log_kernel(self.concentration1, self.concentration0, value)
|
|
312
|
+
return finish(self, out, value, low & high, -jnp.inf)
|
|
313
|
+
|
|
314
|
+
def sample(self, key, sample_shape=()):
|
|
315
|
+
sample_shape, dtype = draw_spec(self, sample_shape)
|
|
316
|
+
# The gamma rejection sampler behind the draw needs positive shapes.
|
|
317
|
+
a, b = (
|
|
318
|
+
jnp.where(shape_ > 0, shape_, 1.0)
|
|
319
|
+
for shape_ in (self.concentration1, self.concentration0)
|
|
320
|
+
)
|
|
321
|
+
return finish(self, jax.random.beta(key, a, b, sample_shape, dtype))
|
|
322
|
+
|
|
323
|
+
def cdf(self, value):
|
|
324
|
+
return finish(
|
|
325
|
+
self,
|
|
326
|
+
betainc(
|
|
327
|
+
self.concentration1, self.concentration0, jnp.clip(value, 0.0, 1.0)
|
|
328
|
+
),
|
|
329
|
+
value,
|
|
330
|
+
)
|
|
331
|
+
|
|
332
|
+
def icdf(self, q):
|
|
333
|
+
return quantile(
|
|
334
|
+
self, _beta_quantile(self.concentration1, self.concentration0, q), q
|
|
335
|
+
)
|
priorities/_transform.py
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
"""The default transform between a distribution's support and the real line."""
|
|
2
|
+
|
|
3
|
+
import jax
|
|
4
|
+
import jax.numpy as jnp
|
|
5
|
+
from jax import Array
|
|
6
|
+
|
|
7
|
+
from priorities._distribution import AbstractDistribution
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def _check_bounds(dist: AbstractDistribution) -> str:
|
|
11
|
+
if dist.bounds not in ("real", "lower", "upper", "interval"):
|
|
12
|
+
raise ValueError(f"unknown bounds {dist.bounds!r} on {type(dist).__name__}")
|
|
13
|
+
return dist.bounds
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def to_real(dist: AbstractDistribution, value: Array) -> Array:
|
|
17
|
+
"""Map a value in the support of ``dist`` to unconstrained coordinates.
|
|
18
|
+
|
|
19
|
+
The transform follows ``dist.bounds``: identity for ``"real"``,
|
|
20
|
+
``log(value - low)`` for ``"lower"``, ``log(high - value)`` for
|
|
21
|
+
``"upper"`` and the logit of the fractional position for ``"interval"``.
|
|
22
|
+
It is elementwise, also for a distribution with an event axis.
|
|
23
|
+
|
|
24
|
+
Args:
|
|
25
|
+
dist: The distribution whose support is mapped.
|
|
26
|
+
value: Values inside the support.
|
|
27
|
+
|
|
28
|
+
Returns:
|
|
29
|
+
Unconstrained coordinates of the shape of ``value``.
|
|
30
|
+
"""
|
|
31
|
+
bounds = _check_bounds(dist)
|
|
32
|
+
low, high = dist.support()
|
|
33
|
+
if bounds == "real":
|
|
34
|
+
return value
|
|
35
|
+
if bounds == "lower":
|
|
36
|
+
return jnp.log(value - low)
|
|
37
|
+
if bounds == "upper":
|
|
38
|
+
return jnp.log(high - value)
|
|
39
|
+
return jnp.log(value - low) - jnp.log(high - value)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def from_real(dist: AbstractDistribution, x: Array) -> tuple[Array, Array]:
|
|
43
|
+
"""Map unconstrained coordinates to a value in the support of ``dist``.
|
|
44
|
+
|
|
45
|
+
This inverts ``to_real``: identity, ``low + exp(x)``, ``high - exp(x)`` or
|
|
46
|
+
``low + (high - low) * sigmoid(x)``.
|
|
47
|
+
|
|
48
|
+
Args:
|
|
49
|
+
dist: The distribution whose support is the target.
|
|
50
|
+
x: Unconstrained coordinates.
|
|
51
|
+
|
|
52
|
+
Returns:
|
|
53
|
+
The value and ``log_volume``, the log of ``|d value / d x|``, summed
|
|
54
|
+
over the event axis when the distribution has one.
|
|
55
|
+
"""
|
|
56
|
+
bounds = _check_bounds(dist)
|
|
57
|
+
low, high = dist.support()
|
|
58
|
+
if bounds == "real":
|
|
59
|
+
value, log_volume = x, jnp.zeros_like(x)
|
|
60
|
+
elif bounds == "lower":
|
|
61
|
+
value, log_volume = low + jnp.exp(x), x
|
|
62
|
+
elif bounds == "upper":
|
|
63
|
+
value, log_volume = high - jnp.exp(x), x
|
|
64
|
+
else:
|
|
65
|
+
width = high - low
|
|
66
|
+
value = low + width * jax.nn.sigmoid(x)
|
|
67
|
+
log_volume = jnp.log(width) + jax.nn.log_sigmoid(x) + jax.nn.log_sigmoid(-x)
|
|
68
|
+
log_volume = jnp.broadcast_to(log_volume, value.shape)
|
|
69
|
+
return value, log_volume.sum(-1) if dist.event_dim else log_volume
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def real_log_prob(dist: AbstractDistribution, x: Array) -> Array:
|
|
73
|
+
"""Return the log density of ``dist`` against ``d(x)``.
|
|
74
|
+
|
|
75
|
+
This is ``dist.log_prob(value) + log_volume`` for the default transform,
|
|
76
|
+
the density a gradient sampler reads in unconstrained coordinates.
|
|
77
|
+
|
|
78
|
+
Args:
|
|
79
|
+
dist: The distribution to evaluate.
|
|
80
|
+
x: Unconstrained coordinates.
|
|
81
|
+
|
|
82
|
+
Returns:
|
|
83
|
+
The log density, reduced over the event axis.
|
|
84
|
+
"""
|
|
85
|
+
value, log_volume = from_real(dist, x)
|
|
86
|
+
return dist.log_prob(value) + log_volume
|
priorities/_version.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# file generated by vcs-versioning
|
|
2
|
+
# don't change, don't track in version control
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__all__ = [
|
|
6
|
+
"__version__",
|
|
7
|
+
"__version_tuple__",
|
|
8
|
+
"version",
|
|
9
|
+
"version_tuple",
|
|
10
|
+
"__commit_id__",
|
|
11
|
+
"commit_id",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
version: str
|
|
15
|
+
__version__: str
|
|
16
|
+
__version_tuple__: tuple[int | str, ...]
|
|
17
|
+
version_tuple: tuple[int | str, ...]
|
|
18
|
+
commit_id: str | None
|
|
19
|
+
__commit_id__: str | None
|
|
20
|
+
|
|
21
|
+
__version__ = version = '0.1.0'
|
|
22
|
+
__version_tuple__ = version_tuple = (0, 1, 0)
|
|
23
|
+
|
|
24
|
+
__commit_id__ = commit_id = None
|
priorities/testing.py
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
"""Contract checks for a distribution, for this library's tests and for subclass owners.
|
|
2
|
+
|
|
3
|
+
``check_distribution`` ties ``sample``, ``cdf`` and ``icdf`` to ``log_prob``
|
|
4
|
+
without restating any formula, so it applies unchanged to a new subclass of
|
|
5
|
+
``AbstractDistribution``. The absolute scale of ``log_prob`` is not covered here: pin
|
|
6
|
+
it against an independent reference.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import jax
|
|
10
|
+
import jax.numpy as jnp
|
|
11
|
+
from jax import Array
|
|
12
|
+
|
|
13
|
+
from priorities._distribution import AbstractDistribution
|
|
14
|
+
from priorities._transform import from_real, real_log_prob, to_real
|
|
15
|
+
|
|
16
|
+
# sup-norm quantile of the Kolmogorov distribution: P(sqrt(n) D > 2.69) = 1e-6.
|
|
17
|
+
KS_SCALE = 2.69
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def ks_distance(dist: AbstractDistribution, draws: Array) -> Array:
|
|
21
|
+
"""Return the Kolmogorov-Smirnov distance of draws to ``dist.cdf``.
|
|
22
|
+
|
|
23
|
+
Args:
|
|
24
|
+
dist: A distribution whose ``cdf`` is a distribution function (scalar)
|
|
25
|
+
or a map to independent uniforms (event distribution with an inverse CDF).
|
|
26
|
+
draws: Values of shape ``(n,) + event``.
|
|
27
|
+
|
|
28
|
+
Returns:
|
|
29
|
+
The largest distance between the empirical and the uniform
|
|
30
|
+
distribution functions of ``cdf(draws)``, over the coordinates.
|
|
31
|
+
"""
|
|
32
|
+
count = draws.shape[0]
|
|
33
|
+
unit = jnp.sort(dist.cdf(draws).reshape(count, -1), axis=0)
|
|
34
|
+
rank = jnp.arange(count)[:, None]
|
|
35
|
+
return jnp.max(jnp.maximum((rank + 1) / count - unit, unit - rank / count))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def icdf_round_trip(dist: AbstractDistribution, dtype=None, ulps: float = 4.0) -> Array:
|
|
39
|
+
"""Return the scaled error of ``cdf(icdf(u))`` over both tails.
|
|
40
|
+
|
|
41
|
+
The grid is logarithmic in ``u`` from 1e-30 to 0.5 and in ``1 - u`` from
|
|
42
|
+
0.5 down to the resolution of the dtype. The error is divided by
|
|
43
|
+
``min(u, 1 - u)`` after removing what the inputs cannot resolve:
|
|
44
|
+
``ulps`` units in the last place of ``u`` and of the value (the latter
|
|
45
|
+
mapped through the density). An absolute tolerance cannot see a lost tail;
|
|
46
|
+
this one can.
|
|
47
|
+
|
|
48
|
+
Args:
|
|
49
|
+
dist: A scalar distribution with an inverse CDF.
|
|
50
|
+
dtype: Floating dtype of the grid; the default float when ``None``.
|
|
51
|
+
ulps: Allowance for the representation of ``u`` and of the value.
|
|
52
|
+
|
|
53
|
+
Returns:
|
|
54
|
+
The relative error at each grid point, to compare with a tolerance.
|
|
55
|
+
"""
|
|
56
|
+
dtype = jnp.zeros((), dtype).dtype
|
|
57
|
+
eps = jnp.finfo(dtype).eps
|
|
58
|
+
lower = jnp.logspace(-30.0, jnp.log10(0.5), 61, dtype=dtype)
|
|
59
|
+
upper = 1 - jnp.logspace(jnp.log10(1e4 * eps), jnp.log10(0.5), 25, dtype=dtype)
|
|
60
|
+
unit = jnp.concatenate([lower, upper])
|
|
61
|
+
value = dist.icdf(unit)
|
|
62
|
+
floor = ulps * eps * (unit + jnp.abs(value) * jnp.exp(dist.log_prob(value)))
|
|
63
|
+
error = jnp.abs(dist.cdf(value) - unit)
|
|
64
|
+
return jnp.maximum(error - floor, 0.0) / jnp.minimum(unit, 1 - unit)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _check_support(dist, low, high):
|
|
68
|
+
grad = jax.vmap(jax.grad(dist.log_prob))
|
|
69
|
+
finfo = jnp.finfo(jnp.result_type(low, high))
|
|
70
|
+
# One spacing beyond each bound, kept a normal float: subnormals can flush.
|
|
71
|
+
step = jnp.maximum(finfo.eps * jnp.abs(jnp.stack([low, high])), finfo.tiny)
|
|
72
|
+
outside = jnp.stack([low - 1.0, low - step[0], high + step[1], high + 1.0])
|
|
73
|
+
outside = outside[jnp.isfinite(outside)]
|
|
74
|
+
assert bool(jnp.all(dist.log_prob(outside) == -jnp.inf)), "density off support"
|
|
75
|
+
assert bool(jnp.all(grad(outside) == 0.0)), "gradient off support"
|
|
76
|
+
assert bool(jnp.isnan(dist.log_prob(jnp.nan))), "NaN value must give NaN"
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _check_normalization(dist, tol, half_width=40.0, count=8001):
|
|
80
|
+
x = jnp.linspace(-half_width, half_width, count)
|
|
81
|
+
total = jnp.sum(jnp.exp(real_log_prob(dist, x))) * (x[1] - x[0])
|
|
82
|
+
assert abs(float(total) - 1.0) < tol, f"density integrates to {total}"
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def check_distribution(
|
|
86
|
+
dist: AbstractDistribution,
|
|
87
|
+
key: Array,
|
|
88
|
+
*,
|
|
89
|
+
n_draws: int = 200_000,
|
|
90
|
+
rtol: float = 1e-10,
|
|
91
|
+
unit_rtol: float = 1e-11,
|
|
92
|
+
) -> None:
|
|
93
|
+
"""Assert that the methods of an unbatched distribution agree with its density.
|
|
94
|
+
|
|
95
|
+
The checks, in order:
|
|
96
|
+
|
|
97
|
+
- draws lie in the support and survive the default transform round trip;
|
|
98
|
+
- a scalar distribution is exactly ``-inf`` with zero gradient outside its support
|
|
99
|
+
and NaN at NaN;
|
|
100
|
+
- a scalar distribution without a distribution function integrates to one over
|
|
101
|
+
the unconstrained axis (trapezoid rule on ``[-40, 40]``);
|
|
102
|
+
- otherwise ``cdf`` is 0 and 1 at the support ends and its derivative
|
|
103
|
+
is ``exp(log_prob)`` at 33 quantiles of the draws;
|
|
104
|
+
- with an inverse CDF, ``cdf(icdf(u))`` returns ``u`` to ``unit_rtol``
|
|
105
|
+
relative to ``min(u, 1 - u)`` (see ``icdf_round_trip``);
|
|
106
|
+
- the draws follow ``cdf``: the Kolmogorov-Smirnov distance stays
|
|
107
|
+
below ``2.69 / sqrt(n_draws)``, a false-rejection rate of 1e-6 per
|
|
108
|
+
coordinate.
|
|
109
|
+
|
|
110
|
+
The defaults are for float64. An event distribution without an inverse CDF gets the
|
|
111
|
+
first check only.
|
|
112
|
+
|
|
113
|
+
Args:
|
|
114
|
+
dist: The distribution to check, with an empty batch shape.
|
|
115
|
+
key: PRNG key for the draws.
|
|
116
|
+
n_draws: Number of draws. A deviation of 5 percent in a scale needs
|
|
117
|
+
200,000 draws to be rejected; fewer suffice when ``sample`` is the
|
|
118
|
+
quantile of uniforms.
|
|
119
|
+
rtol: Relative tolerance of the derivative and normalization checks.
|
|
120
|
+
unit_rtol: Relative tolerance of the unit round trip.
|
|
121
|
+
|
|
122
|
+
Raises:
|
|
123
|
+
AssertionError: If a check fails.
|
|
124
|
+
"""
|
|
125
|
+
low, high = dist.support()
|
|
126
|
+
draws = dist.sample(key, (n_draws,))
|
|
127
|
+
assert bool(jnp.all(jnp.isfinite(dist.log_prob(draws)))), "draw off support"
|
|
128
|
+
back, _ = from_real(dist, to_real(dist, draws[:64]))
|
|
129
|
+
assert bool(jnp.allclose(back, draws[:64], rtol=rtol, atol=0.0)), "transform"
|
|
130
|
+
if dist.event_dim == 0:
|
|
131
|
+
_check_support(dist, low, high)
|
|
132
|
+
try:
|
|
133
|
+
ends = dist.cdf(jnp.stack([low, high]))
|
|
134
|
+
except NotImplementedError:
|
|
135
|
+
return _check_normalization(dist, rtol)
|
|
136
|
+
assert bool(jnp.all(ends == jnp.array([0.0, 1.0]))), "cdf at the ends"
|
|
137
|
+
points = jnp.quantile(draws, jnp.linspace(0.01, 0.99, 33))
|
|
138
|
+
slope = jax.vmap(jax.grad(dist.cdf))(points)
|
|
139
|
+
density = jnp.exp(dist.log_prob(points))
|
|
140
|
+
assert bool(jnp.allclose(slope, density, rtol=rtol, atol=0.0)), "d cdf"
|
|
141
|
+
elif not dist.has_icdf:
|
|
142
|
+
return None
|
|
143
|
+
if dist.has_icdf and dist.event_dim == 0:
|
|
144
|
+
worst = float(jnp.max(icdf_round_trip(dist)))
|
|
145
|
+
assert worst < unit_rtol, f"unit round trip off by {worst}"
|
|
146
|
+
distance = float(ks_distance(dist, draws))
|
|
147
|
+
assert distance < KS_SCALE / n_draws**0.5, f"draws: KS distance {distance}"
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: priorities
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Probability distributions as Equinox records: densities, draws, inverse CDFs and default transforms in JAX
|
|
5
|
+
Project-URL: Homepage, https://github.com/CoreySpohn/priorities
|
|
6
|
+
Project-URL: Issues, https://github.com/CoreySpohn/priorities/issues
|
|
7
|
+
Author-email: Corey Spohn <corey.a.spohn@nasa.gov>
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2026 Corey Spohn
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Keywords: Equinox,JAX,distribution,prior,probability
|
|
31
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
32
|
+
Classifier: Intended Audience :: Science/Research
|
|
33
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
34
|
+
Classifier: Programming Language :: Python :: 3
|
|
35
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
36
|
+
Requires-Python: >=3.12
|
|
37
|
+
Requires-Dist: equinox>=0.13.2
|
|
38
|
+
Requires-Dist: jax>=0.8.1
|
|
39
|
+
Provides-Extra: dev
|
|
40
|
+
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
|
|
41
|
+
Provides-Extra: test
|
|
42
|
+
Requires-Dist: hypothesis>=6.79.1; extra == 'test'
|
|
43
|
+
Requires-Dist: ineedvalidation>=1.0; extra == 'test'
|
|
44
|
+
Requires-Dist: pytest-fail-slow>=0.1.0; extra == 'test'
|
|
45
|
+
Requires-Dist: pytest-markdown-docs>=0.5.0; extra == 'test'
|
|
46
|
+
Requires-Dist: pytest-testmon>=2.0.7; extra == 'test'
|
|
47
|
+
Requires-Dist: pytest-timeout>=1.3.1; extra == 'test'
|
|
48
|
+
Requires-Dist: pytest-xdist>=3.8.0; extra == 'test'
|
|
49
|
+
Requires-Dist: pytest>=7.3.2; extra == 'test'
|
|
50
|
+
Requires-Dist: scipy>=1.15; extra == 'test'
|
|
51
|
+
Description-Content-Type: text/markdown
|
|
52
|
+
|
|
53
|
+
# priorities
|
|
54
|
+
|
|
55
|
+
<p align="center">
|
|
56
|
+
<a href="https://github.com/CoreySpohn/priorities/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/CoreySpohn/priorities/ci.yml?branch=main&style=flat-square&logo=github&label=tests" alt="Tests"/></a>
|
|
57
|
+
<a href="https://github.com/CoreySpohn/priorities/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License"/></a>
|
|
58
|
+
<a href="https://github.com/CoreySpohn/priorities/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square&logo=python" alt="Python 3.12+"/></a>
|
|
59
|
+
</p>
|
|
60
|
+
|
|
61
|
+
Probability distributions as [Equinox](https://docs.kidger.site/equinox/) records for
|
|
62
|
+
JAX: a density, its draws and its map to the unit cube, held as array
|
|
63
|
+
parameters that jit, vmap and differentiate like any other pytree. The
|
|
64
|
+
runtime dependencies are `jax` and `equinox`.
|
|
65
|
+
|
|
66
|
+
## Example
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
import jax
|
|
70
|
+
|
|
71
|
+
jax.config.update("jax_enable_x64", True)
|
|
72
|
+
|
|
73
|
+
import jax.numpy as jnp
|
|
74
|
+
import priorities as pr
|
|
75
|
+
|
|
76
|
+
# An eccentricity prior: a Beta distribution cut at 0.95.
|
|
77
|
+
prior = pr.TruncatedDistribution(pr.Beta(0.867, 3.03), high=0.95)
|
|
78
|
+
|
|
79
|
+
draws = prior.sample(jax.random.key(0), (1000,))
|
|
80
|
+
assert draws.shape == (1000,)
|
|
81
|
+
assert float(draws.max()) <= 0.95
|
|
82
|
+
|
|
83
|
+
# The density, exactly -inf outside the support.
|
|
84
|
+
assert jnp.isfinite(prior.log_prob(0.2))
|
|
85
|
+
assert prior.log_prob(0.97) == -jnp.inf
|
|
86
|
+
|
|
87
|
+
# The inverse CDF: uniform in, the distribution out, and back.
|
|
88
|
+
value = prior.icdf(0.25)
|
|
89
|
+
assert jnp.allclose(prior.cdf(value), 0.25)
|
|
90
|
+
|
|
91
|
+
# An unconstrained coordinate for a gradient-based sampler. real_log_prob
|
|
92
|
+
# is the density of that coordinate, including the volume term.
|
|
93
|
+
z = pr.to_real(prior, value)
|
|
94
|
+
back, log_volume = pr.from_real(prior, z)
|
|
95
|
+
assert jnp.allclose(back, value)
|
|
96
|
+
gradient = jax.grad(lambda z: pr.real_log_prob(prior, z))(z)
|
|
97
|
+
assert jnp.isfinite(gradient)
|
|
98
|
+
|
|
99
|
+
# Parameters are leaves: one compiled function serves every value.
|
|
100
|
+
score = jax.jit(jax.grad(lambda dist: dist.log_prob(0.2)))(pr.Beta(0.867, 3.03))
|
|
101
|
+
assert jnp.isfinite(score.concentration1)
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## What it holds
|
|
105
|
+
|
|
106
|
+
| Record | Support | `icdf` |
|
|
107
|
+
| --- | --- | --- |
|
|
108
|
+
| `Uniform(low, high)` | `[low, high]` | yes |
|
|
109
|
+
| `LogUniform(low, high)` | `[low, high]`, `low > 0` | yes |
|
|
110
|
+
| `Normal(loc, scale)` | the real line | yes |
|
|
111
|
+
| `LogNormal(loc, scale)` | `(0, inf)` | yes |
|
|
112
|
+
| `HalfNormal(scale)` | `[0, inf)` | yes |
|
|
113
|
+
| `Rayleigh(scale)` | `(0, inf)` | yes |
|
|
114
|
+
| `Beta(concentration1, concentration0)` | `(0, 1)` | yes |
|
|
115
|
+
| `TruncatedDistribution(base_dist, low, high)` | the cut of a scalar distribution | yes |
|
|
116
|
+
| `MultivariateNormal(loc, scale_tril)` | vectors | yes |
|
|
117
|
+
| `Mixture(mixing_logits, component_distribution)` | union of the components | no |
|
|
118
|
+
|
|
119
|
+
Every record implements five methods: `support`, `log_prob`, `sample`,
|
|
120
|
+
`cdf` and `icdf`. Three free functions work on any distribution:
|
|
121
|
+
`to_real`, `from_real` and `real_log_prob`, the default change of variable to
|
|
122
|
+
an unconstrained coordinate, chosen from the static `bounds` of the distribution.
|
|
123
|
+
|
|
124
|
+
Names follow NumPyro: `sample(key, sample_shape)`, `log_prob`, `cdf`, `icdf(q)`,
|
|
125
|
+
`Beta(concentration1, concentration0)`, `MultivariateNormal(loc, scale_tril)`,
|
|
126
|
+
`TruncatedDistribution(base_dist, low, high)`. The differences are deliberate:
|
|
127
|
+
`support()` is a method returning the bounds as arrays rather than a
|
|
128
|
+
constraint object, `bounds` names the bounded sides statically, `has_icdf`
|
|
129
|
+
says before tracing whether `icdf` exists, and `Mixture(mixing_logits,
|
|
130
|
+
component_distribution)` takes its weights as logits rather than a
|
|
131
|
+
categorical distribution.
|
|
132
|
+
|
|
133
|
+
## Conventions
|
|
134
|
+
|
|
135
|
+
- **Shapes.** A value has shape `sample + batch + event`, where `batch` is
|
|
136
|
+
the broadcast of the parameter shapes. A distribution is elementwise or has one
|
|
137
|
+
event axis. The components of a `Mixture` are one distribution whose batch has a
|
|
138
|
+
last axis of length `K`.
|
|
139
|
+
- **Precision.** The output dtype is the promotion of the argument and the
|
|
140
|
+
parameters. A distribution built from Python numbers follows its argument, so it
|
|
141
|
+
serves float32 and float64 pipelines alike. Nothing is built at import:
|
|
142
|
+
enable x64 before constructing a distribution, not before importing the package.
|
|
143
|
+
- **Off the support.** `log_prob` is exactly `-inf` outside the support,
|
|
144
|
+
with a zero gradient, and NaN for a NaN value.
|
|
145
|
+
- **Invalid parameters.** A distribution built from concrete parameters outside their
|
|
146
|
+
domain raises `ValueError`. Under a transformation the parameters are
|
|
147
|
+
traced and cannot be inspected, so `log_prob` returns `-inf` and the other
|
|
148
|
+
methods return NaN: a sampler that proposes an invalid parameter rejects
|
|
149
|
+
it. Set `PRIORITIES_DEBUG_CHECKS=1` before import to raise at run time
|
|
150
|
+
instead.
|
|
151
|
+
- **Truncation.** Which sides are cut is static: `None` leaves a side open.
|
|
152
|
+
The mass of the cut is computed from the base distribution's `cdf`, so a cut
|
|
153
|
+
far in a tail loses relative precision.
|
|
154
|
+
- **Beta shapes.** The Beta density is differentiable in its shapes. Its
|
|
155
|
+
distribution function and quantile are not, and differentiating them in
|
|
156
|
+
`a` or `b` raises instead of returning a wrong number.
|
|
157
|
+
- **Mixture.** A scalar mixture has a distribution function (`cdf`) but
|
|
158
|
+
no quantile: `has_icdf` is false and `icdf` raises.
|
|
159
|
+
|
|
160
|
+
## Adding a distribution
|
|
161
|
+
|
|
162
|
+
Subclass `AbstractDistribution` when the mathematics is new, and implement the five
|
|
163
|
+
methods. A named prior that only fixes the parameters of an existing record
|
|
164
|
+
is a function returning that record, not a class:
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
import priorities as pr
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def kipping_eccentricity():
|
|
171
|
+
"""Short-period eccentricity distribution of Kipping (2013)."""
|
|
172
|
+
return pr.Beta(0.867, 3.03)
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
assert isinstance(kipping_eccentricity(), pr.Beta)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
`priorities.testing.check_distribution(distribution, key)` checks that the draws, the inverse CDF
|
|
179
|
+
and the support of a distribution agree with its density without restating any
|
|
180
|
+
formula, so it applies unchanged to a new subclass. It needs no reference
|
|
181
|
+
code; pin the absolute scale of `log_prob` against one separately.
|
|
182
|
+
|
|
183
|
+
## Scope
|
|
184
|
+
|
|
185
|
+
The package stays small on purpose. It holds distributions and the three functions
|
|
186
|
+
above. Samplers, inference, parameter trees, bijector objects and
|
|
187
|
+
domain-specific priors belong to the packages that use it. A test holds the
|
|
188
|
+
source to its line budget and to `jax` and `equinox` as the only runtime
|
|
189
|
+
dependencies.
|
|
190
|
+
|
|
191
|
+
## Installation
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
pip install priorities
|
|
195
|
+
```
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
priorities/__init__.py,sha256=dvO-4qNq0nbgtv4H_-NTvbazxXLkQ3kvxSBYoluhMkE,1272
|
|
2
|
+
priorities/_composite.py,sha256=NskSsC2whTsDQWHPEcnSpYGjeHB-1TXlZHfZjB6_TjY,10032
|
|
3
|
+
priorities/_distribution.py,sha256=vJhORiKItJKG6Qe5WSw5_rKkIwBqK99G3KiucEGaQdI,6492
|
|
4
|
+
priorities/_records.py,sha256=PmMoC364vyiKTy1fEFcb7KoISh0A8J9rpnbs-ZHtJ54,11540
|
|
5
|
+
priorities/_transform.py,sha256=QfSLCwRsp-FijEO-Bp2ObSuyO0at9RhjLYyjzRfDMOs,3000
|
|
6
|
+
priorities/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
|
|
7
|
+
priorities/testing.py,sha256=C0v2xSicJ6AIVSivltvF_Okccp1VIoTKEEkmXz7pw3E,6510
|
|
8
|
+
priorities-0.1.0.dist-info/METADATA,sha256=E1JtrqpiLmnyMjreQGSjnKI_vIduc1c_5qZgZPEKWc8,8974
|
|
9
|
+
priorities-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
10
|
+
priorities-0.1.0.dist-info/licenses/LICENSE,sha256=66ed08OMdjt-G3WoW0mfxmaAt-zqSwZ2A0kvPklkwwQ,1068
|
|
11
|
+
priorities-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Corey Spohn
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|