ravest.prior ============ .. py:module:: ravest.prior .. autoapi-nested-parse:: Prior probability distributions for Bayesian fitting. Attributes ---------- .. autoapisummary:: ravest.prior.PRIOR_FUNCTIONS Classes ------- .. autoapisummary:: ravest.prior.Uniform ravest.prior.EccentricityUniform ravest.prior.Normal ravest.prior.TruncatedNormal ravest.prior.HalfNormal ravest.prior.Rayleigh ravest.prior.VanEylen19Mixture ravest.prior.Beta Module Contents --------------- .. py:data:: PRIOR_FUNCTIONS :value: ['Uniform', 'EccentricityUniform', 'Normal', 'TruncatedNormal', 'HalfNormal', 'Rayleigh',... .. py:class:: Uniform(lower: float, upper: float) Log of uniform prior distribution, with closed (inclusive) interval [a,b]. The uniform probability distribution is: .. math:: p(x) = \frac{1}{b - a} \quad \text{for} \quad a \leq x \leq b \\ 0 \quad \text{otherwise} The log probability is: .. math:: \log p(x) = -\log{(b - a)} \quad \text{for} \quad a \leq x \leq b \\ -\inf \quad \text{otherwise} Uses closed interval [a, b] - both boundary values are included. Note that for usage on eccentricity, we recommend EccentricityUniform instead, which uses a half-open interval [0, upper) to allow exactly e=0 (circular orbits) whilst excluding e=upper (to allow e up to, but not including, 1). :param lower: Lower bound of the uniform distribution. :type lower: float :param upper: Upper bound of the uniform distribution. :type upper: float .. py:attribute:: lower .. py:attribute:: upper .. py:method:: __call__(value: float) -> float Calculate log uniform prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str .. py:class:: EccentricityUniform(upper: float) Log Uniform prior for eccentricity. Uses half-open interval [0, upper). The uniform probability distribution is: .. math:: p(x) = \frac{1}{b} \quad \text{for} \quad 0 \leq x < b \\ 0 \quad \text{otherwise} The log probability is: .. math:: \log p(x) = -\log{b} \quad \text{for} \quad 0 \leq x < b \\ -\inf \quad \text{otherwise} :param upper: Upper bound of the uniform distribution. Must satisfy 0 < upper <= 1. :type upper: float .. rubric:: Notes Uses half-open interval [0, upper) to allow exactly e=0 (circular orbits) whilst excluding e=upper (to allow e up to, but not including, 1). .. py:attribute:: upper .. py:method:: __call__(value: float) -> float Calculate log eccentricity uniform prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str .. py:class:: Normal(mean: float, std: float) Log of Normal prior distribution. The Normal probability distribution is: .. math:: p(x) = \frac{1}{\sigma\sqrt{2\pi}} \exp\left(-\frac{(x - \mu)^2}{2\sigma^2}\right) The log probability is: .. math:: \log p(x) = -\frac{1}{2}\left(\frac{x - \mu}{\sigma}\right)^2 - \frac{1}{2}\log(2\pi\sigma^2) :param mean: Mean of the Normal distribution. :type mean: float :param std: Standard deviation of the Normal distribution. :type std: float .. py:attribute:: mean .. py:attribute:: std .. py:attribute:: _log_norm_const .. py:method:: __call__(value: float) -> float Calculate log Normal prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str .. py:class:: TruncatedNormal(mean: float, std: float, lower: float, upper: float) Log of properly normalized truncated Normal prior distribution. The truncated Normal probability distribution is: .. math:: p(x) = \frac{\phi\left(\frac{x - \mu}{\sigma}\right)}{\sigma \left[\Phi\left(\frac{b - \mu}{\sigma}\right) - \Phi\left(\frac{a - \mu}{\sigma}\right)\right]} \quad \text{for} \quad a \leq x \leq b \\ 0 \quad \text{otherwise} where lowercase phi is the standard normal PDF and uppercase Phi is the standard normal CDF. The log probability is: .. math:: \log p(x) = \log\phi\left(\frac{x - \mu}{\sigma}\right) - \log\sigma - \log\left[\Phi\left(\frac{b - \mu}{\sigma}\right) - \Phi\left(\frac{a - \mu}{\sigma}\right)\right] \quad \text{for} \quad a \leq x \leq b \\ -\inf \quad \text{otherwise} This provides a proper probability distribution that integrates to 1 over [a, b]. This is useful for parameters e.g. that can't go negative or that are bounded between a lower and upper value, but where you want a more informative prior than a uniform distribution. :param mean: Mean of the original (untruncated) Normal distribution. :type mean: float :param std: Standard deviation of the original Normal distribution. :type std: float :param lower: Lower bound of the truncation. :type lower: float :param upper: Upper bound of the truncation. :type upper: float .. py:attribute:: mean .. py:attribute:: std .. py:attribute:: lower .. py:attribute:: upper .. py:attribute:: _a .. py:attribute:: _b .. py:method:: __call__(value: float) -> float Calculate log truncated Normal prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str .. py:class:: HalfNormal(std: float) Log of half-Normal prior distribution. The half-Normal probability distribution is: .. math:: p(x) = \frac{2}{\sigma\sqrt{2\pi}} \exp\left(-\frac{x^2}{2\sigma^2}\right) \quad \text{for} \quad x \geq 0 \\ 0 \quad \text{otherwise} The log probability is: .. math:: \log p(x) = \log(2) - \log(\sigma) - \frac{1}{2}\log(2\pi) - \frac{x^2}{2\sigma^2} \quad \text{for} \quad x \geq 0 \\ -\inf \quad \text{otherwise} This is equivalent to a Normal distribution with mean=0 that has been truncated at x=0 to only allow non-negative values (equivalently, the absolute value of a Normal distribution with mean=0). This can be useful for parameters that must be positive, such as standard deviations, measurement uncertainties, or jitter terms. :param std: Standard deviation (sigma) of the half-Normal distribution. Must be > 0. :type std: float .. py:attribute:: std .. py:method:: __call__(value: float) -> float Calculate log half-Normal prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str .. py:class:: Rayleigh(scale: float) Log of Rayleigh prior distribution. The Rayleigh probability distribution is: .. math:: p(x) = \frac{x}{\sigma^2} \exp\left(-\frac{x^2}{2\sigma^2}\right) \quad \text{for} \quad x \geq 0 \\ 0 \quad \text{otherwise} The log probability is: .. math:: \log p(x) = \log(x) - 2\log(\sigma) - \frac{x^2}{2\sigma^2} \quad \text{for} \quad x \geq 0 \\ -\inf \quad \text{otherwise} :param scale: Scale parameter (sigma) of the Rayleigh distribution. Must be > 0. :type scale: float .. rubric:: Notes The Rayleigh prior is zero at x=0 (log prior is -inf). If you expect significant probability mass near zero, consider using another prior such as the HalfNormal or VanEylen19Mixture prior instead. .. py:attribute:: scale .. py:method:: __call__(value: float) -> float Calculate log Rayleigh prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str .. py:class:: VanEylen19Mixture(sigma_normal: float, sigma_rayleigh: float, f: float) Log of a Rayleigh & Half-Normal mixture model prior distribution. The mixture model combines a half-Normal and a Rayleigh distribution, weighted by a mixing fraction f. This model is particularly useful for eccentricity priors in exoplanet systems, where the half-Normal component captures low eccentricities, and the Rayleigh component captures higher eccentricities, as described in Van Eylen et al. (2019). The mixture probability distribution is: .. math:: p(x) = (1-f) \cdot p_{\text{HalfNormal}}(x; \sigma_{\text{normal}}) + f \cdot p_{\text{Rayleigh}}(x; \sigma_{\text{rayleigh}}) The log probability is: .. math:: \log p(x) = \log\left[(1-f) \cdot p_{\text{HalfNormal}}(x; \sigma_{\text{normal}}) + f \cdot p_{\text{Rayleigh}}(x; \sigma_{\text{rayleigh}})\right] where: - f = 0 indicates a pure half-Normal distribution (low eccentricities) - f = 1 indicates a pure Rayleigh distribution (higher eccentricities) - 0 < f < 1 represents a mixture of both components :param sigma_normal: Scale parameter for the half-Normal component. Must be > 0. :type sigma_normal: float :param sigma_rayleigh: Scale parameter for the Rayleigh component. Must be > 0. :type sigma_rayleigh: float :param f: Mixing fraction between 0 and 1. f=0 gives pure half-Normal, f=1 gives pure Rayleigh. :type f: float .. rubric:: References Vincent Van Eylen et al 2019 AJ 157 61 (https://doi.org/10.3847/1538-3881/aaf22f) .. py:attribute:: sigma_normal .. py:attribute:: sigma_rayleigh .. py:attribute:: f .. py:method:: __call__(value: float) -> float Calculate log mixture prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str .. py:class:: Beta(a: float, b: float) Log of Beta prior distribution, for parameter x where 0 <= x <= 1. The Beta probability distribution is: .. math:: p(x) = \frac{x^{a-1}(1-x)^{b-1}}{B(a,b)} \quad \text{for} \quad 0 \leq x \leq 1 \\ 0 \quad \text{otherwise} where B(a,b) is the beta function. The log probability is: .. math:: \log p(x) = (a - 1)\log(x) + (b - 1)\log(1-x) - \log B(a,b) \quad \text{for} \quad 0 \leq x \leq 1 \\ -\inf \quad \text{otherwise} :param a: Shape parameter a of the Beta distribution. Must be > 0. :type a: float :param b: Shape parameter b of the Beta distribution. Must be > 0. :type b: float .. rubric:: Notes The Beta distribution's behaviour at the boundaries depends on the shape parameters. Consider the shape of your Beta distribution if you expect to have significant probability mass near 0 or 1, where probability may be 0 or infinite (depending on the shape parameters). .. py:attribute:: a .. py:attribute:: b .. py:attribute:: _log_beta .. py:method:: __call__(value: float) -> float Calculate log Beta prior probability. :param value: Parameter value to evaluate :type value: float :returns: Log prior probability :rtype: float .. py:method:: __repr__() -> str