pgmuvi.priors

Period/frequency prior distributions for pgmuvi GP models.

This module provides Prior classes for setting priors on period (for models parameterized directly in period space, e.g. QuasiPeriodicGPModel) and on frequency (for models parameterized in frequency space, e.g. SpectralMixtureGPModel).

Two flavours of prior are provided:

  1. Log-Normal in period space ("lognormal" / LPV default) Period P ~ LogNormal(mu, sigma), with mu=5 and sigma=1. The median period is exp(mu) ~ 148 days, loosely appropriate for Long-Period Variable (LPV) stars.

    • LogNormalPeriodPrior – register directly on a period_length parameter.

    • LogNormalFrequencyPrior – equivalent prior for a frequency parameter. Because P = 1/f and the log-normal is closed under reciprocal, the frequency prior is LogNormal(-mu, sigma) and the Jacobian correction is automatically included.

  2. Normal in period space ("normal" / second choice) Period P ~ Normal(mean, std), with mean=300 and std=75.

    • NormalPeriodPrior – register on a period_length parameter.

    • NormalFrequencyPrior – equivalent prior for a frequency parameter, obtained by change of variables with the correct Jacobian.

All classes accept optional bounds to truncate the prior to the physically allowed range. The log-probability is correctly normalised over the truncated support so that the distribution integrates to 1 within the allowed interval. Outside the interval the log-probability is -inf.

The frequency classes support a period keyword (default True) that controls whether the supplied bounds are expressed in period units or in frequency units, giving users the flexibility to work in whichever space is more natural.

Pre-defined prior sets

PRIOR_SETS mirrors the structure of CONSTRAINT_SETS and contains ready-to-use prior parameters for common source types. Period bounds are read directly from the corresponding constraint set at runtime to guarantee consistency.

Examples

>>> from pgmuvi.priors import LogNormalPeriodPrior, LogNormalFrequencyPrior
>>> import torch
>>> p_prior = LogNormalPeriodPrior(mu=5.0, sigma=1.0, lower_bound=100.0)
>>> p_prior.log_prob(torch.tensor([150.0, 300.0, 50.0]))
tensor([-5.1767, -5.5043,    -inf])
>>> f_prior = LogNormalFrequencyPrior(mu=5.0, sigma=1.0, lower_period=100.0)
>>> # frequency 1/150 ~ 0.00667 (period 150 days, passes lower bound of 100)
>>> f_prior.log_prob(torch.tensor([1.0 / 150.0]))
tensor([4.5170])
class pgmuvi.priors.LogNormalFrequencyPrior(mu=5.0, sigma=1.0, lower_period=None, upper_period=None, period=True)

Bases: LogNormalPrior

Log-Normal period prior expressed as a prior on a frequency parameter.

If period P ~ LogNormal(mu, sigma) and frequency f = 1/P, then the change-of-variables formula (with Jacobian) gives f ~ LogNormal(-mu, sigma). This class encapsulates that transformation so that the prior can be registered directly on a frequency (e.g. mixture_means) parameter while still encoding a belief about the period.

The log-probability is correctly normalised over the truncated support.

Parameters:

  • mu (float, optional) – Mean of the underlying normal distribution for the period (i.e. the log-mean of the log-normal period distribution). Default 5.0 (median period ~ 148 days, appropriate for LPVs).

  • sigma (float, optional) – Standard deviation of the underlying normal distribution for the period (i.e. the log-standard-deviation of the log-normal period distribution). Default 1.0.

  • lower_period (float or None, optional) –

    Lower bound on the allowed range. Interpretation depends on period:

    • period=True (default): minimum period. Frequencies whose corresponding period 1/f falls below this threshold receive -inf log-prob.

    • period=False: minimum frequency. Frequencies below this threshold receive -inf log-prob.

  • upper_period (float or None, optional) –

    Upper bound on the allowed range. Interpretation depends on period:

    • period=True (default): maximum period.

    • period=False: maximum frequency.

  • period (bool, optional) – Controls the units of lower_period and upper_period. If True (default) the bounds are in period units. If False the bounds are in frequency units, and are converted internally to period units (lower_freq becomes upper_period, upper_freq becomes lower_period).

Notes

The Jacobian correction is automatically included: this distribution is the mathematically correct probability density for the frequency when the period follows a log-normal.

Examples

>>> import torch
>>> from pgmuvi.priors import LogNormalFrequencyPrior
>>> # Bounds in period units (default)
>>> prior = LogNormalFrequencyPrior(mu=5.0, sigma=1.0, lower_period=100.0)
>>> prior.log_prob(torch.tensor([1.0 / 150.0]))
tensor([4.5170])
>>> prior.log_prob(torch.tensor([1.0 / 50.0]))
tensor([-inf])
>>> # Equivalent using frequency units (upper_period=0.01 is max frequency)
>>> prior_f = LogNormalFrequencyPrior(
...     mu=5.0, sigma=1.0, upper_period=1/100.0, period=False)
>>> prior_f.log_prob(torch.tensor([1.0 / 150.0]))
tensor([4.5170])
log_prob(f)
Returns:

log-probability of the parameter value under the prior

Return type:

torch.Tensor

class pgmuvi.priors.LogNormalPeriodPrior(mu=5.0, sigma=1.0, lower_bound=None, upper_bound=None)

Bases: LogNormalPrior

Log-Normal prior on a period parameter, with correct truncation normalisation.

Period P ~ LogNormal(mu, sigma), optionally truncated to the interval [lower_bound, upper_bound]. When bounds are supplied the log-probability is normalised so that the distribution integrates to 1 over the allowed interval; outside the interval the log-probability is -inf.

Parameters:

  • mu (float, optional) – Mean of the underlying normal distribution (i.e. the log-mean of the log-normal). Default 5.0 (median ~ 148 days, appropriate for LPVs).

  • sigma (float, optional) – Standard deviation of the underlying normal distribution (i.e. the log-standard-deviation of the log-normal). Default 1.0.

  • lower_bound (float or None, optional) – Minimum period. Values below this bound receive -inf log-prob.

  • upper_bound (float or None, optional) – Maximum period. Values above this bound receive -inf log-prob.

Examples

>>> import torch
>>> from pgmuvi.priors import LogNormalPeriodPrior
>>> prior = LogNormalPeriodPrior(mu=5.0, sigma=1.0, lower_bound=100.0)
>>> prior.log_prob(torch.tensor([150.0, 300.0, 50.0]))
tensor([-5.1767, -5.5043,    -inf])
log_prob(x)
Returns:

log-probability of the parameter value under the prior

Return type:

torch.Tensor

class pgmuvi.priors.NormalFrequencyPrior(mean=300.0, std=75.0, lower_period=None, upper_period=None, period=True)

Bases: NormalPrior

Normal period prior expressed as a prior on a frequency parameter.

Evaluates a Normal(mean, std) distribution in period space (P = 1/f) and applies the correct change-of-variables Jacobian so that the resulting log-probability is appropriate for a frequency parameter:

log p(f) = Normal(mean, std).log_prob(1/f)  -  2*log(f)

The -2*log(f) term is the log-Jacobian |dp/df| = 1/f^2.

The log-probability is correctly normalised over the truncated support.

Parameters:

  • mean (float, optional) – Mean of the period Normal distribution (days). Default 300.0.

  • std (float, optional) – Standard deviation of the period Normal distribution (days). Default 75.0.

  • lower_period (float or None, optional) –

    Lower bound on the allowed range. Interpretation depends on period:

    • period=True (default): minimum period.

    • period=False: minimum frequency.

  • upper_period (float or None, optional) –

    Upper bound on the allowed range. Interpretation depends on period:

    • period=True (default): maximum period.

    • period=False: maximum frequency.

  • period (bool, optional) – If True (default), bounds are in period units. If False, bounds are in frequency units (converted internally).

Examples

>>> import torch
>>> from pgmuvi.priors import NormalFrequencyPrior
>>> prior = NormalFrequencyPrior(mean=300.0, std=75.0, lower_period=100.0)
>>> prior.log_prob(torch.tensor([1.0 / 300.0]))
tensor([6.1749])
>>> prior.log_prob(torch.tensor([1.0 / 50.0]))  # period 50 < lower_period 100
tensor([-inf])
log_prob(f)
Returns:

log-probability of the parameter value under the prior

Return type:

torch.Tensor

class pgmuvi.priors.NormalPeriodPrior(mean=300.0, std=75.0, lower_bound=None, upper_bound=None)

Bases: NormalPrior

Normal (Gaussian) prior on a period parameter, truncation-normalised.

Period P ~ Normal(mean, std), optionally truncated to [lower_bound, upper_bound]. When bounds are supplied the log-probability is normalised over the allowed interval.

Parameters:

  • mean (float, optional) – Mean of the Normal distribution. Default 300.0 (days).

  • std (float, optional) – Standard deviation. Default 75.0 (days).

  • lower_bound (float or None, optional) – Minimum period. Values below this bound receive -inf log-prob.

  • upper_bound (float or None, optional) – Maximum period. Values above this bound receive -inf log-prob.

Examples

>>> import torch
>>> from pgmuvi.priors import NormalPeriodPrior
>>> prior = NormalPeriodPrior(mean=300.0, std=75.0, lower_bound=100.0)
>>> prior.log_prob(torch.tensor([300.0, 100.0, 50.0]))
tensor([-5.2326, -7.8660,    -inf])
log_prob(x)
Returns:

log-probability of the parameter value under the prior

Return type:

torch.Tensor

pgmuvi.priors.PRIOR_SETS = {'LPV': {'lognormal': {'mu': 5.0, 'sigma': 1.0}, 'normal': {'mean': 300.0, 'std': 75.0}}}

Prior distribution parameters for common astronomical source types.

Each key is a source-type label (e.g. "LPV"). The value is a dict with the following sub-keys:

"lognormal"

Parameters for the default Log-Normal period prior.

"normal"

Parameters for the second-choice Normal period prior.

Period bounds are not stored here; they are read at runtime from the matching entry in CONSTRAINT_SETS by get_prior_set() to guarantee consistency.

Currently defined sets

LPV

Long-Period Variable stars. Default Log-Normal with mu=5, sigma=1. Second-choice Normal with mean=300, std=75. Truncation bounds come from CONSTRAINT_SETS["LPV"]["period"].

pgmuvi.priors.get_prior_set(name)

Return the prior-set dict for name, with period bounds from the constraint set.

The returned dict contains the distribution parameters ("lognormal" and "normal" sub-dicts) plus a "period_bounds" sub-dict that is read at call time from CONSTRAINT_SETS so that prior bounds and constraint bounds are always consistent.

Parameters:

name (str) – Name of the prior set (e.g. "LPV").

Returns:

Mapping containing "lognormal", "normal", and "period_bounds" sub-dicts. The caller receives a deep copy and may modify it freely.

Return type:

dict

Raises:

ValueError – If name is not a recognised prior set.

Examples

>>> from pgmuvi.priors import get_prior_set
>>> ps = get_prior_set("LPV")
>>> ps["lognormal"]["mu"]
5.0
>>> ps["period_bounds"]["lower"]  # from CONSTRAINT_SETS["LPV"]["period"]["lower"]
(100.0, True)