virgil.angles
Angles sampled as 2-D vectors, so that no prior has a wrap boundary. Put an
AngleVector in a priors dict under an angle's path (in degrees, such as a
binary's "pa" or an orbit's node), and fit, gauss_newton_mass and
numpyro_model sample a vector v = r(cos θ, sin θ) at the site
"<path>_vec" instead of the angle. The model receives θ in degrees, in
[0°, 360°): numpyro_model records it as the deterministic site "<path>",
and fit reports both.
from virgil.angles import AngleVector
priors = {"pa": AngleVector()} # uniform, no wall at 0°/360°
priors = {"pa": AngleVector(350.0, 20.0)} # von Mises, mean 350°, κ = 20
priors = {"node": AngleVector(100.0, 4.0, axial=True)} # known modulo 180°
The density of \(v\) is
so \(r\) and \(\theta\) are independent and \(\theta\) has exactly the density \(p(\theta)\) (per radian): uniform, \(1/2\pi\), by default; a von Mises, \(\exp[\kappa(\cos(\theta - \mu) - 1)] / (2\pi\, \mathrm{i0e}(\kappa))\), given mean and kappa; or, with axial=True, the von Mises of \(2\theta\), so that \(\theta\) and \(\theta + 180°\) are equally likely. The radius is a nuisance with a ring prior whose mode is the unit circle, which keeps a maximum a posteriori fit away from the origin, where \(\theta\) is undefined. The ring width \(s\) (ring_width, default 0.25) does not change the prior on \(\theta\). The default, a uniform angle, is the invariant prior; a von Mises prior is strong information from an external measurement.
Every term has a least-squares form for Levenberg–Marquardt and gauss_newton_mass, and the density is normalized in \(\mathbb{R}^2\), so evidences stay normalized. The ring's residual is \((r - 1)/s\). A von Mises enters as a chord, \(\sqrt{\kappa}\,(\hat v - \hat m)\) with \(\hat v = v / r\) and \(\hat m = (\cos\mu, \sin\mu)\); half its square is \(\kappa(1 - \cos(\theta - \mu))\), the von Mises exponent, just as virgil's phase residuals \(2\sin(\Delta/2)/\sigma\) are chords with \(\kappa = 1/\sigma^2\) (see whitened_residuals). The axial chord is the same on the doubled direction, \((\cos 2\theta, \sin 2\theta) = (x^2 - y^2, 2xy)/r^2\).
For orbits, orientation_priors samples 2Ω and ϖ = Ω + ω for
position-only fits (so the node ambiguity is one point, not two modes), or Ω
and ϖ when RVs fix the node.
Credit. The construction follows Octofitter's UniformCircular (Thompson et al. 2023, AJ 166, 164) and exoplanet's Angle (Foreman-Mackey et al. 2021, JOSS 6, 3285), which sample \(v \sim N(0, I)\) and so peak at the origin; the ring and chord priors are virgil's own. No code is taken from either.
Angles sampled as 2-D vectors, so that no prior has a wrap boundary.
AngleVector in a priors dict, under an
angle's path, samples a vector v = r(cos θ, sin θ) at the site
"<path>_vec" instead of the angle; the model receives θ in degrees in
[0°, 360°), recorded (by numpyro_model)
and reported (by fit) under "<path>". See
the derivation in docs/api/angles.md.
AngleVector
Bases: Distribution
A prior on an angle (degrees), sampled as a 2-D vector.
Put it in a priors dict, keyed by the angle's path, for
fit,
gauss_newton_mass or
numpyro_model. The vector is
sampled at "<path>_vec", giving θ = atan2(v₂, v₁) in [0°, 360°); a
fit starts from the starting angle or init["<path>_vec"]. The
prior on θ is uniform unless mean and kappa give a von Mises
prior; see the derivation in docs/api/angles.md.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mean
|
float
|
Mean angle (degrees) and concentration of a von Mises prior (of 2θ
when |
None
|
kappa
|
float
|
Mean angle (degrees) and concentration of a von Mises prior (of 2θ
when |
None
|
axial
|
bool
|
Whether the von Mises prior is on 2θ (an axis known modulo 180°). |
False
|
ring_width
|
float
|
The ring's radial width (default 0.25); it does not change the prior on θ. |
0.25
|
arg_constraints = {'ring_width': constraints.positive}
class-attribute
instance-attribute
pytree_data_fields = ('mean_deg', 'kappa', 'ring_width')
class-attribute
instance-attribute
pytree_aux_fields = ('axial',)
class-attribute
instance-attribute
support = constraints.real_vector
class-attribute
instance-attribute
mean_deg = None if mean is None else mean if isinstance(mean, jax.Array) else float(mean)
instance-attribute
kappa = None if kappa is None else kappa if isinstance(kappa, jax.Array) else float(kappa)
instance-attribute
ring_width = ring_width if isinstance(ring_width, jax.Array) else float(ring_width)
instance-attribute
axial = bool(axial)
instance-attribute
uniform
property
Whether the prior on the angle is uniform.
__init__(mean=None, kappa=None, *, axial=False, ring_width=0.25, validate_args=None)
residuals(vector)
Residuals whose half sum of squares is -log p(vector) + const.
The ring, (r - 1)/s, then, for a von Mises prior, the chord √κ (v̂ - m̂) (two more rows).
log_prob(value)
sample(key, sample_shape=())
vector_angle(vector)
The direction of vector (last axis of length 2), in degrees in
[0°, 360°), measured from its first component towards its second.
vector_site(path)
The numpyro site of the vector that carries the angle at path.
is_angle_vector(prior)
Whether prior is an AngleVector.