pgmuvi.initialization

Smart initialization routines for GP kernel hyperparameters.

This module provides functions to automatically initialize kernel hyperparameters from data using periodogram analysis and data statistics.

pgmuvi.initialization.initialize_from_physics(period, lengthscale=None, decay=None, outputscale=1.0)

Create initial hyperparameters from user-supplied physical parameters.

Parameters:

  • period (float) – Known or expected period of the source (same units as input time).

  • lengthscale (float, optional) – Periodic lengthscale (PeriodicKernel). Defaults to 0.1 * period (10% of the period), which gives a moderately smooth periodic shape that is resolved by typical observing cadences.

  • decay (float, optional) – Long-term decay timescale. Defaults to 5 * period (slow decay).

  • outputscale (float, optional) – Amplitude of the variability. Defaults to 1.0.

Returns:

Dictionary suitable for passing to QuasiPeriodicGPModel or pgmuvi.lightcurve.Lightcurve.fit(guess=...).

Return type:

dict

Examples

>>> from pgmuvi.initialization import initialize_from_physics
>>> params = initialize_from_physics(period=10.0, outputscale=0.5)
>>> params['period']
10.0
pgmuvi.initialization.initialize_quasi_periodic_from_data(train_x, train_y, yerr=None)

Initialize quasi-periodic kernel parameters from data via Lomb-Scargle.

Computes the Lomb-Scargle periodogram on the input data and returns sensible initial hyperparameter values based on the dominant period.

Parameters:

  • train_x (torch.Tensor or array-like) – Time stamps (1D).

  • train_y (torch.Tensor or array-like) – Observed values (1D).

  • yerr (torch.Tensor or array-like, optional) – Measurement uncertainties. If provided, the data are weighted during the periodogram computation.

Returns:

Dictionary with keys 'period', 'lengthscale', 'decay', and 'outputscale'.

Return type:

dict

Examples

>>> import torch
>>> import numpy as np
>>> from pgmuvi.initialization import initialize_quasi_periodic_from_data
>>> t = torch.linspace(0, 20, 100)
>>> y = torch.sin(2 * np.pi * t / 5.0)
>>> params = initialize_quasi_periodic_from_data(t, y)
>>> abs(params['period'] - 5.0) < 1.0  # rough check
True
pgmuvi.initialization.initialize_separable_from_data(train_x, train_y, yerr=None)

Initialize separable 2D kernel parameters from multiwavelength data.

Uses MultibandLSWithSignificance to compute a single multiband Lomb-Scargle periodogram over all bands simultaneously and to assess the significance of the dominant period. Per-band single-band periodograms are then used to check whether the variability is achromatic (consistent periods across bands) or chromatic.

Parameters:

  • train_x (torch.Tensor or array-like) – Input data of shape (n, 2) where column 0 is time and column 1 is wavelength/band.

  • train_y (torch.Tensor or array-like) – Observed values (1D tensor of length n).

  • yerr (torch.Tensor or array-like, optional) – Measurement uncertainties (1D).

Returns:

Dictionary with keys:

  • 'period' — dominant multiband period (or per-band mean if the multiband approach fails).

  • 'is_significant' — True if the peak FAP < 0.05.

  • 'is_achromatic' — True if per-band periods agree within 10 %.

  • 'wavelength_lengthscale' — half the wavelength range.

  • 'periods_per_band' — list of per-band peak periods.

  • 'outputscale' — std of the observed data.

Return type:

dict

Examples

>>> import torch
>>> from pgmuvi.initialization import initialize_separable_from_data
>>> t = torch.linspace(0, 10, 40)
>>> wl = torch.cat([torch.ones(20) * 500.0, torch.ones(20) * 700.0])
>>> x = torch.stack([t, wl], dim=1)
>>> y = torch.sin(2 * 3.14159 * t / 3.0)
>>> params = initialize_separable_from_data(x, y)
>>> 'period' in params
True