Priors

AMPy uses Bayesian inference to estimate model parameters from observational data. In this framework, each parameter is assigned a prior distribution that encodes physically motivated constraints or prior knowledge about the parameter before considering the data.

All priors in AMPy follow a common interface and return log-densities (\(\log p(\theta)\)) so that they can be combined directly with the log-likelihood during MCMC sampling:

\[\log p(\theta \mid D) \propto \log \mathcal{L}(D \mid \theta) + \sum_i \log p_i(\theta_i)\]

Priors in AMPy serve two purposes:

Constrain parameters to physically meaningful ranges
Encode external knowledge

Each prior provides:

A normalized probability density
A log-density evaluation used during inference
A sampling method for initializing MCMC walkers
Serialization for configuration files

class ampy.inference.priors.UniformPrior(lower, upper, initial_guess=None, initial_sigma=None)

Bases: BoundedMixin

Uniform prior with an optional initialization region.

This class represents a uniform prior over the closed interval [lower, upper]. It also supports an optional initialization region (initial_guess ± initial_sigma) used when drawing initial samples for MCMC walkers. This can help concentrate starting positions without changing the actual prior used for inference.

lower

Lower bound of the prior (inherited from BoundedMixin).

Type:: float

upper

Upper bound of the prior (inherited from BoundedMixin).

Type:: float

initial_guess

Center of the initialization region, if provided.

Type:: float or None

initial_sigma

Half-width of the initialization region, if provided.

Type:: float or None

Notes

The initialization region affects draw() only when initial=True. It does not change the underlying prior used during inference.
evaluate() returns the log-prior (0 inside bounds, -np.inf outside), which is convenient for log-posterior calculations.

type = 'uniform'

classmethod from_dict(d)

Construct a UniformPrior from a dictionary.

Parameters:

d (dict) –

Dictionary containing keys:

"lower" : float
"upper" : float
"initial_guess" : float, optional
"initial_sigma" : float, optional

Returns:

Instantiated prior.

Return type:

UniformPrior

Raises:

TypeError – If any provided values are not numeric.

Examples

>>> prior = UniformPrior.from_dict({"lower": 0.0, "upper": 1.0})
>>> prior.lower, prior.upper
(0.0, 1.0)

>>> prior = UniformPrior.from_dict(
...     {"lower": 0.0, "upper": 10.0, "initial_guess": 5.0, "initial_sigma": 1.0}
... )

serialize()

Serialize the prior parameters.

Returns:: Dictionary representation containing lower, upper, initial_guess, and initial_sigma.
Return type:: dict

draw(n, initial=True)

Draw samples from the uniform prior.

Parameters:

n (int) – Number of samples to draw.
initial (bool, optional) – If True and initialization parameters are set, samples are drawn from the clipped initialization region. If False, samples are drawn from the full prior range.

Returns:

If n == 1, a scalar sample is returned. Otherwise, an array of shape (n,) containing samples.

Return type:

float or numpy.ndarray

Examples

>>> prior = UniformPrior(lower=0.0, upper=10.0, initial_guess=5.0, initial_sigma=1.0)
>>> s0 = prior.draw(n=1000, initial=True)   # mostly in [4, 6]
>>> s1 = prior.draw(n=1000, initial=False)  # in [0, 10]

evaluate(x)

Evaluate the log-prior at x.

Parameters:

x (float) – Value at which to evaluate the prior.

Returns:

Log-prior value:

0.0 if x is within bounds
-np.inf if x is outside bounds

Return type:

float

Notes

This method returns the log-density for convenience in log-posterior calculations.

class ampy.inference.priors.GaussianPrior(mu, sigma)

Bases: object

Gaussian (normal) prior distribution.

This class represents a univariate Gaussian prior with mean mu and standard deviation sigma. It provides utilities for sampling, evaluating the probability density function (PDF), serialization, and convenient bounds for initialization or visualization.

The prior is defined as:

\[p(x) = \frac{1}{\sqrt{2\pi}\,\sigma} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right)\]

mu

Mean of the distribution.

Type:: float

sigma

Standard deviation of the distribution.

Type:: float

Notes

The lower and upper properties return the ±3σ bounds of the distribution. These are often useful for visualization or initialization ranges but are not hard bounds of the prior.

type = 'gaussian'

property lower: float

Lower 3σ bound of the prior.

Returns:: mu - 3*sigma.
Return type:: float

Notes

This is a convenience range estimate, not a truncation of the prior.

property upper: float

Upper 3σ bound of the prior.

Returns:: mu + 3*sigma.
Return type:: float

Notes

This is a convenience range estimate, not a truncation of the prior.

classmethod from_dict(d)

Construct a GaussianPrior from a dictionary.

Parameters:

d (dict) –

Dictionary containing prior parameters with keys:

"mu" : float
"sigma" : float

Returns:

Instantiated prior.

Return type:

GaussianPrior

Raises:

TypeError – If mu or sigma are not numeric.

Examples

>>> prior = GaussianPrior.from_dict({"mu": 0.0, "sigma": 1.0})
>>> prior.mu, prior.sigma
(0.0, 1.0)

serialize()

Serialize the prior parameters.

Returns:: Dictionary representation containing mu and sigma.
Return type:: dict

Notes

This method returns a deep copy so that external modification does not affect the prior instance.

draw(n)

Draw samples from the Gaussian prior.

Parameters:: n (int) – Number of samples to draw.
Returns:: If n == 1, a scalar sample is returned. Otherwise, an array of shape (n,) containing samples.
Return type:: float or numpy.ndarray

Examples

>>> prior = GaussianPrior(mu=0.3, sigma=0.1)
>>> s = prior.draw(n=1000)
>>> abs(s.mean() - prior.mu) < 0.01
True

evaluate(x)

Evaluate the Gaussian probability density at x.

Parameters:: x (float or array_like) – Value(s) at which to evaluate the prior PDF.
Returns:: Probability density evaluated at x. Shape matches input.
Return type:: float or numpy.ndarray

Notes

This returns the probability density, not the log-density. For MCMC inference, the log-PDF is typically used elsewhere.

Examples

>>> prior = GaussianPrior(mu=0.0, sigma=1.0)
>>> prior.evaluate(0.0)
0.3989...
>>> prior.evaluate([0.0, 1.0]).shape
(2,)

class ampy.inference.priors.MilkyWayRvPrior

Bases: object

Milky Way Rv Prior.

References

Adam Trotter (2011):: The Gamma-Ray Burst Afterglow Modeling Project: Foundational Statistics and Absorption & Extinction Models. See: Page 108.

property lower: float: Returns the lower 3-sigma bound of the prior.

property upper: float: Returns the upper 3-sigma bound of the prior.

classmethod from_dict(d)

Creates instance from dict ensuring values are OK.

Parameters:: d (dict) – mu : float low : float high : float
Returns:: Instantiated from dictionary
Return type:: GaussianPrior

serialize()

draw(n)

Draws n samples from the asymmetric distribution.

Parameters:: n (int) – The number of samples to draw.
Returns:: The samples drawn.
Return type:: float or np.ndarray, with shape (n, 1)

evaluate(x)

Evaluates the prior at the sampled value x.

Parameters:: x (float or array_like) – The sampled value.
Returns:: The prior evaluated at x.
Return type:: float or np.ndarray of float

class ampy.inference.priors.SinePrior(lower, upper, initial_guess=None, initial_sigma=None)

Bases: UniformPrior

Sine prior for an orientation angle.

This prior is useful for parameters representing an angle \(\theta\) drawn from an isotropic distribution of directions. For an isotropic orientation, the probability of observing a particular polar angle scales as the solid-angle element:

\[d\Omega = 2\pi \sin(\theta)\, d\theta\]

Therefore, the (unnormalized) density is \(p(\theta) \propto \sin(\theta)\) over a bounded interval \(\theta \in [\theta_\mathrm{min}, \theta_\mathrm{max}]\).

On the interval [lower, upper] (in radians), the properly normalized PDF is:

\[p(\theta) = \frac{\sin(\theta)}{\cos(\theta_\mathrm{min}) - \cos(\theta_\mathrm{max})}\]

Parameters:

lower (float) – Lower bound of the prior in radians.
upper (float) – Upper bound of the prior in radians.
initial_guess (float, optional) – Center of an optional initialization region used when sampling initial values (e.g., initial walker positions).
initial_sigma (float, optional) – Half-width of the initialization region about initial_guess. When used, the initialization region is clipped to [lower, upper].

Notes

Sampling is performed using inverse transform sampling by drawing uniformly in \(\cos(\theta)\) over the bounds and converting back to \(\theta\) via \(\arccos\).