API

API#

Here we document the PSDEstimator, the main class to be used from this package.

class sgvb_psd.psd_estimator.PSDEstimator(x, N_theta=30, nchunks=1, ntrain_map=10000, N_samples=500, fs=1.0, max_hyperparm_eval=100, fmax_for_analysis=None, degree_fluctuate=None, seed=None, lr_range=(0.002, 0.02), n_elbo_maximisation_steps=500)#

A class for estimating the posterior Power Spectral Density (PSD) using Stochastic Gradient Variational Bayes (SGVB).

This class implements a two-step process: 1. Optimize the learning rate to maximize the posterior and Evidence Lower Bound (ELBO). 2. Use the optimized learning rate to estimate the posterior PSD.

The main interface is the run() method, which returns the posterior PSD and its quantiles.

Variables:

  • N_theta (int) – Number of basis functions for the theta component.

  • N_samples (int) – Number of parameters sampled from the surrogate distribution.

  • nchunks (int) – Number of blocks the multivariate time series is divided into.

  • ntrain_map (int) – Number of iterations in gradient ascent for Maximum A Posteriori (MAP) estimation.

  • fs (float) – Sampling frequency of the input data.

  • lr_range (tuple) – Range of learning rates to consider during optimization.

  • psd_scaling (numpy.ndarray) – Scaling factor for the input data.

  • psd_offset (numpy.ndarray) – Offset for the input data.

  • x (numpy.ndarray) – Normalized input multivariate time series.

  • n (int) – Number of time points in the input data.

  • p (int) – Number of variables in the multivariate time series.

  • fmax_for_analysis (int) – Maximum frequency in the frequency domain to be analyzed.

  • pdgrm (numpy.ndarray) – Periodogram of the input data.

  • pdgrm_freq (numpy.ndarray) – Frequencies corresponding to the periodogram.

  • max_hyperparm_eval (int) – Number of evaluations in hyperparameter optimization.

  • degree_fluctuate (float) – Hyperparameter from the prior, used when dealing with a large number of basis functions.

  • model (object) – Trained model object.

  • samps (numpy.ndarray) – Samples drawn from the posterior distribution.

  • vi_losses (numpy.ndarray) – Variational Inference losses during training.

  • psd_quantiles – Quantiles of the estimated PSD.

  • psd_all (numpy.ndarray) – All estimated PSDs.

  • inference_runner (ViRunner) – Object for running the variational inference.

  • optimal_lr (float) – Optimized learning rate.

  • runtimes (dict) – Runtime of the different steps in the estimation process.

  • n_elbo_maximisation_steps (int) – Number of steps for maximising the ELBO.

__find_optimal_learing_rate()#

Find the optimal learning rate using hyperopt.

This method uses the TPE algorithm to optimize the learning rate.

__learning_rate_optimisation_objective(lr)#

Objective function for hyperparameter optimization of the learning rate for MAP.

Args:

lr (dict): Dictionary containing the learning rate to be optimized.

Returns:

float: ELBO log_map_vals.

__train_model()#

Train the model using the optimal learning rate.

This method runs the variational inference to estimate the posterior PSD.

property freq: ndarray#

Get the frequencies per chunk of the PSD estimate.

Returns:

np.ndarray: Array of frequencies.

property nfreq_per_chunk: int#

Return the number of frequencies per chunk

property nt_per_chunk: int#

Return the number of time-points per chunk

plot(true_psd=None, quantiles='pointwise', plot_periodogram=True, tick_ln=5, diag_spline_thickness=2, xlims=None, diag_ylims=None, off_ylims=None, diag_log=True, off_symlog=True, sylmog_thresh=1e-49, **kwargs) → ndarray[Axes]#

Plot the estimated PSD, periodogram, and true PSD (if provided).

Parameters:

  • true_psd (tuple, optional) – True PSD and freq to plot for comparison (true_psd, true_freq)

  • quantiles (str, optional) – Type of quantiles (‘pointwise’, ‘uniform’) to plot, defaults to ‘pointwise’

  • plot_periodogram (bool) – Whether to plot the periodogram

  • tick_ln (int, optional) – Length of the ticks, defaults to 5

  • diag_spline_thickness (int, optional) – Thickness of the diagonal spline, defaults to 2

  • xlims (tuple, optional) – Limits for the x-axis

  • diag_ylims (tuple, optional) – Limits for the diagonal

  • off_ylims (tuple, optional) – Limits for the off-diagonal

  • diag_log (bool, optional) – Whether to use a log scale for the diagonal, defaults to True

  • off_symlog (bool, optional) – Whether to use a symlog scale for the off-diagonal, defaults to True

  • sylmog_thresh (float, optional) – Threshold for symlog, defaults to 1e-49

Returns:

Matplotlib Axes object

Return type:

numpy.ndarray

plot_coherence(true_psd=None, **kwargs) → ndarray[Axes]#

Plot the coherence of the estimated PSD.

Parameters:

  • true_psd (tuple, optional) – True PSD to plot for comparison

  • kwargs – Additional keyword arguments for plotting

Returns:

Matplotlib Axes object

Return type:

numpy.ndarray[plt.Axes]

plot_vi_losses() → Axes#

Plot the variational inference losses.

Returns:

Matplotlib Axes object

Return type:

plt.Axes

run(lr=None) → Tuple[ndarray, ndarray, ndarray]#

Run the SGVB algorithm to estimate the posterior PSD.

This method either uses a provided learning rate or finds the optimal one, then trains the model and computes the posterior PSD.

Parameters:

lr (float, optional) – Learning rate for MAP. If None, optimal rate is found, defaults to None.

Returns:

Tuple containing the posterior PSD and pointwise, and uniform quantiles of the PSD.

Return type:

tuple(numpy.ndarray, numpy.ndarray)