Prewhitener

Prewhitener provides the core frequency-analysis and iterative prewhitening functionality in Pyriod. It can be used independently of the graphical interface.

Prewhitener

Bases: object

Perform iterative frequency analysis and prewhitening.

Prewhitener contains the core analysis state and fitting functionality used by Pyriod. It can be used directly for non-interactive analysis or passed to PyriodGUI to create the interactive notebook interface.

Parameters:
  • lc (LightCurve) –

    Light curve data to analyze.

  • amp_unit (str, default: 'ppt' ) –

    Amplitude unit used for input and displayed amplitudes. Accepted values include "relative", "percent", "ppt", "ppm",

  • and –

    Frequency unit. Accepted values include aliases for microhertz (e.g., "muhz") and cycles per day (e.g., "1/d"). Default is "muHz".

  • use_weights (bool, default: True ) –

    If true, weight data points by 1/lc.flux_err when available. Default is True.

  • rescale_covar (bool, default: False ) –

    Whether lmfit should rescale the covariance matrix when estimating parameter uncertainties. Default is False.

  • ls_method ( str, default: 'fast' ) –

    Lomb-Scargle method keyword passed to lightkurve LombScarglePeriodogram. Default is "fast".

  • frequency (array - like) –

    Explicit frequency grid on which to calculate periodograms, in freq_unit. Default is None, and sampling frequencies will be chosen.

  • oversample_factor (float) –

    Number of frequency samples per natural resolution element 1 / duration. Default is 5.

  • nyquist_factor (float) –

    Maximum automatically generated frequency as a multiple of the approximate Nyquist frequency. Default is 1. Ignored when maxfreq is specified.

  • minfreq (float) –

    Minimum automatically generated frequency, in freq_unit. Default is 1/duration.

  • maxfreq (float) –

    Maximum automatically generated frequency, in freq_unit. By default it is determined from nyquist_factor.
Attributes:
  • lc (LightCurve) –

    Internal copy of the input light curve. It includes an include column indicating which observations are currently used.

  • stagedvalues (DataFrame) –

    Signal parameters staged for the next model fit.

  • fitvalues (DataFrame) –

    Parameters of the most recently fitted signal model.

  • fit_result (ModelResult or None) –

    Detailed result of the most recent lmfit optimization.

  • uptodate (bool) –

    Whether the fitted model reflects the current staged signal parameters and light curve mask.

  • lc_model (LightCurve) –

    Current fitted model evaluated at the observation times.

  • lc_resid (LightCurve) –

    Residual light curve after subtracting lc_model from lc.

  • freqs (ndarray) –

    Frequency grid on which the periodograms are evaluated, in freq_unit.

  • fres (float or None) –

    Natural frequency resolution used to construct an automatically generated frequency grid. None when an explicit frequency grid is supplied.

  • oversample_factor (float or None) –

    Oversampling factor of an automatically generated frequency grid.

  • nyquist (float) –

    Approximate Nyquist frequency, in freq_unit.

  • nyquist_factor (float) –

    Ratio of the upper frequency range to the approximate Nyquist frequency.

  • nyquist_quality (float) –

    Metric between 0 and 1 characterizing the strength of reflection across the approximate Nyquist frequency.

  • per_orig (ndarray) –

    Amplitude periodogram of the original light curve evaluated on freqs, in amp_unit.

  • per_model (ndarray) –

    Amplitude periodogram of the current fitted model evaluated on freqs, in amp_unit.

  • per_resid (ndarray) –

    Amplitude periodogram of the residual light curve evaluated on freqs, in amp_unit. This is the primary periodogram used to identify additional signals during prewhitening.

  • noise_spectrum (callable or None) –

    Interpolating function giving the estimated local average residual-periodogram amplitude as a function of frequency.

  • significance_multiplier (float or None) –

    Multiplier applied to noise_spectrum to define the current significance threshold.

  • significance_settings (dict or None) –

    Settings used to calculate the current significance threshold.

  • autorecalculate (bool) –

    Whether the significance threshold is automatically recalculated after the periodogram changes.

  • tshift (float) –

    Time offset, in days, applied internally to improve numerical behavior of phase fitting.

  • amp_unit (str) –

    Selected amplitude-unit name.

  • amp_conversion (float) –

    Conversion factor between internal relative amplitudes and displayed amplitudes.

  • freq_unit (Unit) –

    Astropy unit used for frequencies.

  • freq_conversion (float) –

    Conversion factor between frequencies in freq_unit and inverse days.

  • log_html (str) –

    HTML representation of messages recorded in the Pyriod log.

set_frequency_sampling 

set_frequency_sampling(frequency=None, oversample_factor=5, nyquist_factor=1, minfreq=None, maxfreq=None)

Set the frequency grid used for subsequent periodograms.

The grid may be supplied explicitly or generated at a specified oversampling factor over an automatically or explicitly bounded frequency range.

Parameters:
  • frequency (array - like, default: None ) –

    Explicit frequency samples, in freq_unit. If provided, oversample_factor, minfreq, and maxfreq are not used to construct the grid.

  • oversample_factor (float, default: 5 ) –

    Number of samples per natural frequency-resolution element 1 / duration. Default is 5.

  • nyquist_factor (float, default: 1 ) –

    Upper limit of an automatically generated grid as a multiple of the approximate Nyquist frequency. Default is 1. Overridden by maxfreq.

  • minfreq (float, default: None ) –

    Minimum frequency of an automatically generated grid, in freq_unit. Default is the natural frequency resolution.

  • maxfreq (float, default: None ) –

    Maximum frequency of an automatically generated grid, in freq_unit. By default it is determined from nyquist_factor.
Notes

This method updates freqs but does not automatically recalculate per_orig. Call compute_pers(orig=True) to recalculate the original-light-curve periodogram on the new grid.

The approximate Nyquist frequency is calculated as 1 / (2 dt), where dt is the median separation between adjacent observations. This is exact only for evenly sampled data. nyquist_quality provides a measure between 0 and 1 of how strongly the sampling produces reflection about this approximate Nyquist frequency.

add_signal 

add_signal(freq, amp=None, phase=None, fixfreq=False, fixamp=False, fixphase=False, include=True, brute=True, index=None)

Stage one or more independent sinusoidal signals for fitting.

Scalar arguments may be supplied for a single signal. For multiple signals, iterable arguments may be supplied; scalar values are repeated as needed.

Parameters:
  • freq (float or array-like of float) –

    Initial signal frequencies, in freq_unit.

  • amp (float or array-like of float, default: None ) –

    Initial signal amplitudes, in amp_unit.

  • phase (float or array-like of float, default: None ) –

    Initial phases, expressed in cycles.

  • fixfreq (bool or array-like of bool, default: False ) –

    If True, hold the corresponding frequency fixed during fitting. Default is False.

  • fixamp (bool or array-like of bool, default: False ) –

    If True, hold the corresponding amplitude fixed during fitting. Default is False.

  • fixphase (bool or array-like of bool, default: False ) –

    If True, hold the corresponding phase fixed during fitting. Default is False.

  • include (bool or array-like of bool, default: True ) –

    Whether to include each signal in the next model fit. Default is True.

  • brute (bool or array-like of bool, default: True ) –

    Whether to estimate the initial phase by brute-force sampling before fitting. Default is True.

  • index (str or iterable of str, default: None ) –

    Signal label or labels. Missing labels are assigned the next available independent-signal labels of the form "f#".
Raises:
  • ValueError –

    If duplicate labels are supplied or a supplied label already exists in stagedvalues.
Notes

Signals are added to stagedvalues and do not become part of the fitted model until fit_model() is called.

add_combination 

add_combination(combostr, amp=None, phase=None, fixamp=False, fixphase=False, include=True, brute=True)

Stage one or more combination-frequency signals for fitting.

Combination frequencies are defined by arithmetic expressions involving existing staged signal labels. The combination expression is also used as the signal label.

Parameters:
  • combostr (str or iterable of str) –

    Arithmetic expression or expressions defining frequencies in terms of existing staged signal labels, for example "f0+f1".

  • amp (float or iterable of float, default: None ) –

    Initial amplitude in amp_unit. If None, the amplitude is initialized by interpolating per_resid at the combination frequency.

  • phase (float or iterable of float, default: None ) –

    Initial phase in cycles.

  • fixamp (bool or iterable of bool, default: False ) –

    If True, hold amplitude fixed during fitting. Default is False.

  • fixphase (bool or iterable of bool, default: False ) –

    If True, hold phase fixed during fitting. Default is False.

  • include (bool or iterable of bool, default: True ) –

    Whether to include the signal in the next fit. Default is True.

  • brute (bool or iterable of bool, default: True ) –

    Whether to estimate the initial phase by brute-force sampling. Default is True.
Notes

Invalid combination expressions are reported to the Pyriod log and no combination signal is added.

remove_signals 

remove_signals(indices)

Remove signals from the staged solution.

Parameters:
  • indices (str or iterable of str) –

    Signal label or labels to remove from stagedvalues.
Notes

Combination signals that depend on a removed signal are also removed. Missing labels produce a warning in the Pyriod log.

Removing a staged signal does not remove it from the current fitted model until fit_model() is called.

fit_model 

fit_model()

Fit the staged sinusoidal model to the light curve.

The model is a sum of all signals in stagedvalues for which include is True. Initial parameter values are taken from stagedvalues. Signals marked with brute=True have their initial phase estimated by brute-force sampling before optimization.

Independent signals are represented by free or fixed sinusoidal parameters. Combination-signal frequencies are constrained through lmfit expressions relating them to their constituent independent frequencies.

After a successful fit, fitted parameters are stored in fitvalues and the complete lmfit result is stored in fit_result. The model and residual periodograms are then recalculated.

Notes

If no signals are included, no optimization is performed and the fitted solution is reset to an empty table. If all included parameters are fixed, a warning is written to the log and no optimization is performed.

solution_table 

solution_table(display_units=True, include_brute=True)

Return a copy of the current fitted signal table.

Parameters:
  • display_units (bool, default: True ) –

    If True, express amp and amperr in amp_unit. If False, leave them in internal relative-flux units. Default is True.

  • include_brute (bool, default: True ) –

    If True, include a brute column containing False for every fitted signal. Default is True.
Returns:
  • DataFrame –

    Copy of the fitted signal table. Modifying the returned table does not modify the internally stored fitted values.

staged_table 

staged_table(display_units=True)

Return a copy of the signal parameters staged for the next model fit.

Parameters:
  • display_units (bool, default: True ) –

    If True, convert the amp and amperr columns to the current display amplitude unit using amp_conversion. If False, return amplitudes in the internal fitting units. Default is True.
Returns:
  • DataFrame –

    Copy of the staged signal table. These values are those that will be used for the next model evaluation or fit. The returned table can be modified without changing the internally staged values.

sample_model 

sample_model(time)

Evaluate the current fitted signal model at specified times.

Parameters:
  • time (array - like) –

    Times at which to evaluate the model, in days.
Returns:
  • ndarray –

    Sum of the currently included fitted sinusoids evaluated at the requested times, in the numerical flux units of the input light curve.
Notes

Evaluates the sinusoidal variations only and does not include an additive offset to match mean light curve flux.

calculate_significance_threshold 

calculate_significance_threshold(multiplier=5, startfreq=0, endfreq=None, freqstep=100, winwidth=100, avgtype='mean', autorecalculate=False, **kwargs)

Estimate a frequency-dependent amplitude significance threshold.

The local noise level is estimated from the mean or median amplitude in moving windows across per_resid. An interpolating function describing this noise spectrum is stored in noise_spectrum. Multiplying it by multiplier gives the significance threshold.

Parameters:
  • multiplier (float, default: 5 ) –

    Factor by which the local noise estimate is multiplied to define the significance threshold. Default is 5.

  • startfreq (float, default: 0 ) –

    Frequency at the center of the first averaging window, in freq_unit. Default is 0.

  • endfreq (float, default: None ) –

    Upper limit for centers of averaging windows, in freq_unit. Default is the highest sampled frequency.

  • freqstep (float, default: 100 ) –

    Separation between averaging-window centers, in freq_unit. Default is 100.

  • winwidth (float, default: 100 ) –

    Width of each averaging window, in freq_unit. Default is 100.

  • avgtype ((mean, median), default: "mean" ) –

    Statistic used to estimate the local periodogram amplitude. Default is "mean".

  • autorecalculate (bool, default: False ) –

    If True, recalculate the threshold with these settings whenever the periodogram changes. Default is False.

  • **kwargs –

    Additional keyword arguments passed to scipy.interpolate.interp1d. If fill_value is omitted, "extrapolate" is used.
Notes

The settings used for the calculation are stored in significance_settings. Signal-to-noise ratios in the fitted signal table are updated using the resulting noise spectrum.

mask_indices 

mask_indices(indices, threshold=30)

Mask selected light-curve points by index.

Parameters:
  • indices (array-like of int) –

    Indices of observations to exclude from the analysis. Their include values in lc are set to False.

  • threshold (int, default: 30 ) –

    Array-printing threshold used when recording the selected indices in the log. Passed to numpy.array2string. Default is 30.
Notes

If no indices are supplied, the mask is unchanged and a warning is written to the Pyriod log.

Changing the mask recalculates the time shift and periodograms and causes uptodate to become False until the model is refitted. Use clear_mask() to restore all observations.

clear_mask 

clear_mask()

Restore all masked light-curve points.

All values in the include column of lc are set to True. The time shift and periodograms are recalculated, and the fitted model is marked as out of date until it is refitted.

save_solution 

save_solution(filename='Pyriod_solution.csv')

Save the current fitted signal solution to a CSV file.

Parameters:
  • filename (str or path - like, default: 'Pyriod_solution.csv' ) –

    Output CSV filename. Default is "Pyriod_solution.csv".
Notes

Amplitudes and amplitude uncertainties are written in the current display amplitude unit.

load_solution 

load_solution(filename='Pyriod_solution.csv')

Load a saved signal solution and stage it for fitting.

Parameters:
  • filename (str or path - like, default: 'Pyriod_solution.csv' ) –

    CSV file containing a solution previously written by save_solution(). Default is "Pyriod_solution.csv".
Notes

Loaded amplitudes are interpreted in the current amp_unit and converted to internal units. The loaded values replace stagedvalues but are not fitted automatically.

If the file does not exist, an error is written to the Pyriod log and no exception is raised.

log 

log(message, level='info')

Record a message in the Pyriod log.

Parameters:
  • message (str) –

    Message to record.

  • level ((debug, info, warning, error, critical), default: "debug" ) –

    Logging level. Default is "info".

save_log 

save_log(filename, overwrite=False)

Write the Pyriod log to a text file.

Parameters:
  • filename (str or path - like) –

    Output filename.

  • overwrite (bool, default: False ) –

    If True, replace an existing file. If False, append the current log to an existing file, or create the file if it does not exist. Default is False.

close 

close(clear_data=True, collect=False)

Release resources owned by this Prewhitener.

Parameters:
  • clear_data (bool, default: True ) –

    If True, release large science data products such as the light curve, periodograms, fitted values, fit result, and significance-threshold arrays. The default is True.

    If False, only logger resources are closed.

  • collect (bool, default: False ) –

    If True, run garbage collection at the end. Usually not necessary, but useful in notebooks after creating many large objects.
Notes

After clear_data=True, this Prewhitener should be considered closed and should not be used for further fitting or plotting.