pgmuvi.multiband_ls_significance

Multiband Lomb-Scargle with significance testing.

This module provides a wrapper around astropy’s LombScargleMultiband that adds false-alarm probability (FAP) computation capabilities.

class pgmuvi.multiband_ls_significance.MultibandLSWithSignificance(t, y, bands, dy=None, ls_method='fast', **kwargs)

Bases: object

Wrapper around LombScargleMultiband with significance testing.

This class extends astropy’s LombScargleMultiband with false-alarm probability (FAP) computation capabilities. Since LombScargleMultiband does not provide a built-in false_alarm_probability method, this wrapper implements several methods for estimating FAP:

  1. analytical (default): Adapt Baluev (2008) formula to multiband case

  2. bootstrap: Permute data within each band independently

  3. phase_scramble: Randomize phases while preserving power spectrum

  4. calibrated: Use Astropy’s single-band FAP as calibration

The bootstrap and phase_scramble methods support optional parallelism via joblib (n_jobs parameter). When joblib is installed (it ships with scikit-learn), setting n_jobs=-1 uses all available CPU cores to parallelise the Monte-Carlo samples, which can give a large speed-up for large datasets or high n_samples values.

References

  • VanderPlas & Ivezić 2015, ApJ 812, 18: “Periodograms for Multiband Astronomical Time Series”

  • Baluev 2008, MNRAS 385, 1279: Analytical FAP formulae for Lomb-Scargle periodograms

Examples

>>> t = np.array([1, 2, 3, 4, 5, 6, 7, 8])
>>> y = np.array([1, 2, 1, 2, 1, 2, 1, 2])
>>> bands = np.array([0, 0, 0, 0, 1, 1, 1, 1])
>>> ls = MultibandLSWithSignificance(t, y, bands)
>>> freq = ls.autofrequency()
>>> power = ls.power(freq)
>>> fap = ls.false_alarm_probability(power.max(), method='analytical')
autofrequency(**kwargs)

Get automatic frequency grid.

Parameters:

**kwargs (dict) – Additional keyword arguments passed to LombScargleMultiband.autofrequency()

Returns:

frequency – Automatically determined frequency grid

Return type:

ndarray

false_alarm_probability(power_values, method='analytical', n_samples=100, freq_grid=None, n_jobs=1)

Compute FAP for multiband LS periodogram.

The false-alarm probability (FAP) estimates the probability that a peak of the given power would arise from pure noise. Lower FAP values indicate more significant detections.

Parameters:

  • power_values (float or array-like) – Power value(s) to compute FAP for. Can be a single value or an array of values.

  • method (str, optional) –

    Method for computing FAP. Options:

    • ’analytical’: Analytical approximation (fastest, default)

    • ’bootstrap’: Permute data within bands (most robust)

    • ’phase_scramble’: Randomize phases (preserves autocorrelation)

    • ’calibrated’: Use single-band Astropy FAP (conservative)

    Default: ‘analytical’

  • n_samples (int, optional) – Number of bootstrap/permutation samples for Monte Carlo methods (‘bootstrap’ and ‘phase_scramble’). Higher values give more accurate FAP estimates but take longer. Default: 100

  • freq_grid (array-like, optional) – Frequency grid for computing null distribution. If None, uses autofrequency(). Only used for Monte Carlo methods.

  • n_jobs (int, optional) – Number of parallel jobs to use for Monte Carlo methods (‘bootstrap’ and ‘phase_scramble’). -1 uses all available CPU cores. Requires joblib (installed with scikit-learn). Default: 1 (serial execution).

Returns:

fap – False alarm probability for each power value. Values range from 0 (highly significant) to 1 (likely noise).

Return type:

float or ndarray

Notes

Method comparison:

  • analytical (default): Fastest; adapts the Baluev (2008) formula for the multiband case. Makes assumptions about data distribution. Cost: O(1).

  • bootstrap: Most robust; permutes data within bands to build a null distribution. Computational cost: O(n_samples). Supports parallel execution via n_jobs.

  • phase_scramble: Better for data with temporal correlations. Preserves power spectrum structure. Cost: O(n_samples). Supports parallel execution via n_jobs.

  • calibrated: Conservative estimate using single-band approach. Useful as sanity check. Cost: O(1).

Performance: For n_samples=100, bootstrap typically takes 1-2 seconds for ~100 data points. Parallelism (n_jobs=-1) can reduce this substantially on multi-core machines. Use n_samples=1000 for publication-quality results if time permits.

Note for pgmuvi users: Since the primary use case in pgmuvi is to generate initial guesses for periods rather than final significance testing, the default ‘analytical’ method is typically sufficient. Use ‘bootstrap’ with parallel execution (n_jobs=-1) when publication-quality significance estimates are required.

power(frequency)

Compute power at given frequencies.

Uses the method specified at construction time (default: 'fast').

Parameters:

frequency (array-like) – Frequencies at which to compute power

Returns:

power – Lomb-Scargle power at each frequency

Return type:

ndarray