Analysis pipeline

Analysis pipeline#

star_privateer.analysis_pipeline(t, s, periods_in=None, wavelet_analysis=True, plot=True, filename=None, figsize=(6, 12), show_light_curve=True, add_periodogram=False, cmap='jet', normscale='log', ylogscale=False, vmin=None, vmax=None, lw=1, mother=None, xlim=None, dpi=200, pmin=None, pmax=None, smooth_acf=False, cutoff_global=None, cutoff_filter_acf=None, show_kepler_quarters=False, tref=0, add_profile_parameters_to_features=False, smooth_period=True, contourf_plot_wps=False, show_contour_wps=False, levels_wps=None, mode_wps=None, zero_padding_wavelet=False, pad=0, ylim_wps=(0.1, 100), shading='auto', n_profile=5, threshold=0.1, pfa_threshold=None, show_periods=True, ls_err_smooth=False, add_lomb_scargle_features_to_wavelets=False)#

Analysis pipeline combining Lomb-Scargle (or wavelet analysis), ACF and CS.

The pipeline compute Lomb-Scargle periodogram (or Wavelet Power Spectrum and Global Wavelet Power Spectrum), Auto-Correlation function, and Composite spectrum of the provided light curves, as well as a set of relevant features for each method of analysis.

Parameters:

  • t (ndarray) – Timestamps, in days.

  • s (ndarray) – Flux time series

  • period_in (ndarray) – value which will be used as input to compute the ACF lags. A periods vector corresponding to the exact position of the lags will be returned by the function. If None, a lags vector (and corresponding period vector) from 0 to s.size will be generated. Optional, default None.

  • wavelet_analysis (bool) – if set to True the timeseries will be analysed with a wavelet analysis. Otherwise the Lomb-Scargle periodogram will be computed and used to compute the composite spectrum

  • plot (bool) – if set to True a summary plot will be made. Optional, default None.

  • filename (str) – the filename under which the summary plot will be saved. Optional, default None.

  • figsize (tuple) – Figure size for the summary plot. Optional, default (10, 16).

  • show_light_curve (bool) – Set to True to show the light curve on the summary plot. Optional, default True.

  • add_periodogram (bool) – In case of a plot with wavelet, compute and add periodogram on a side panel. show_light_curve must be set to True for this option to work. Optional, default False.

  • pmin (float) – Minimum period to fit on PS and CS. Optional, default None.

  • pmax (float) – Maximum period to fit on PS and CS. Optional, default None.

  • mother (object) – mother wavelet to consider. Optional, if set to None, pycwt.Morlet (6) will be used.

  • cutoff_global (float) – Cutoff for the high pass filter to apply on time series before making any computation, in days. Optional, default None, in this case no filtering is applied.

  • cutoff_filter_acf (float) – Cutoff for the high pass filter to apply on time series before computing ACF, in days. Optional, default None, in this case no filtering is applied.

  • show_kepler_quarters (bool) – start time of Kepler quarters will be shown on the light curves and WPS (if wavelet_analysis is True)

  • tref (float) – reference time to use for the start of the series when showing Kepler quarters.

  • add_profile_parameters_to_features (bool) – if set to True, the parameters of the fitted profiles for the PS and CS will be included in features. The corresponding feature_names are named with the following pattern: CS_i_j or PS_i_j, with i is an integer greater or equal to zero denoting the profile index. with j=1 for the amplitude parameter of the profile j=2 for the central period (CS) or frequency (PS) and j=3 for the fwhm parameter of the profile.

  • mode_wps (string) – alternative ways to compute and filter the WPS. mm for a mathematical morphology filter trying to remove brief high frequency systematical noise. ssq to reassign the WPS according to the synchrosqueezing method (Daubechies et al. 2000). ssqmm for both methods combined. Default to None to use the standard wavelet approach. Will only use a Morlet wavelet with w=6

  • zero_padding_wavelet (bool) – If set to True, time series will be zero padded up to the next power of two plus pad before computing wavelet transform. Optional, default False.

  • pad (int) – If zero_padding_wavelet is set to True, the time series will be padded to the pad``th power of two beyond the first upper power of two of the time series length. Optional, default ``0.

  • n_profile (int) – Maximal number of Gaussian profiles to fit in PS (Lomb-Scargle or wavelets) and CS.

  • threshold (float) – Peaks with height below this threshold (given as a fraction as the highest peak) will not be fitted.

  • pfa_threshold (float) – False-alarm probability threshold to consider to stop the fitting process. In this case, the metric to compute false alarm probability will assume that the spectrum follow a chi square distribution. threshold and n_profile will not be considered if this argument is provided. A maximum of 100 profiles will be fitted. Will be considered only in the case where use_wavelets is False. Optional, default None.

  • show_periods (bool) – Show period values obtained with the differente methods on the summary plot. Optional default True.

  • ls_err_smooth (bool) – If set to True, the Lomb-Scargle period uncertainties will be computed by fitting a Gaussian function centred on the Lomb-Scargle largest peak, considering a smoothed version of the periodogram. Optional, default False.

  • add_lomb_scargle_features_to_wavelets (bool) – If set to True, Lomb-Scargle periodogram will be computed even if wavelet_analysis is True, and corresponding features will be provided in the returned elements.

Returns:

Tuple of elementa containing output periods_acf, periods_wps, gwps, wps, acf, cs, coi, features, feature_names arrays if wavelet_analysis is set to True, periods_ps, periods_acf, ps, acf, cs, features, and feature_names, otherwise. In both case, the figure used for the plots is returned as the last element of the tuple.

Return type:

tuple

Lomb-Scargle periodogram#

star_privateer.compute_lomb_scargle(t, s, freq=None, renormalise=False, normalisation='snr', return_object=False, return_frequency_vector=False, method='fast')#

Compute Lomb Scargle for a given timeseries. Default normalisation follows the standard normalisation described in astropy documentation.

Parameters:

  • t (ndarray) – Timestamp array, in days.

  • s (ndarray) – Flux variations

  • freq (ndarray) – Frequency array on which to compute the power vector. If not provided, the function will compute the frequency array assuming a uniform sampling through numpy.fft.rfftfreq.

  • normalisation (str) – Normalisation choice, standard, psd correspond to the astropy implementation. snr corresponds to the psd normalisation divided by a mean spectrum value computed as the spectrum median value divided by (8/9)**3. This can be used only with return_object set as False. Optional, default snr.

  • return_object (bool) – If set to True, return astropy object as second element of the returned tuple, otherwise return power array.

  • return_frequency_vector (bool) – If set to True, the frequency vector (in Hz) will be returned instead of the period vector. Optional, default False.

  • method (str) – Method to compute Lomb-Scargle. See astropy.timeseries.LombScargle. Optional, default "fast".

Returns:

Tuple of array with periods (in days) and Lomb-Scargle power spectrum. Return the Lomb-Scargle object if return_object is set to True.

Return type:

tuple

star_privateer.compute_prot_err_gaussian_fit_chi2_distribution(periods, ps, n_profile=5, threshold=0.1, pfa_threshold=None, verbose=False, back=None, plot_procedure=False, pmin=None, pmax=None, procedure='mask')#

Fit a series of gaussian profiles on a power spectrum following a chi2 distribution and use it to extract the rotation period estimate and corresponding error.

Parameters:

  • periods (ndarray) – Period array, in days.

  • ps (ndarray) – Power spectrum.

  • n_profile (int) – Maximal number of Gaussian profile to fit.

  • threshold (float) – Peaks with height below this threshold (given as a fraction as the highest peak) will not be fitted.

  • pfa_threshold (float) – False-alarm probability threshold to consider to stop the fitting process. In this case, the metric to compute false alarm probability will assume that the spectrum follow a chi square distribution. threshold and n_profile will not be considered if this argument is provided. A maximum of 100 profiles will be fitted. Optional, default None.

  • pmin (float) – Minimum period to fit. Optional, default None.

  • pmax (float) – Maximum period to fit. Optional, default None.

Returns:

The rotation period, its uncertainty, corresponding height and the parameters fitted for the n_profile profiles (in this order for each profile: amplitude, central frequency, width, a, b, with a and b the parameters for the affine background law).

Return type:

tuple

star_privateer.plot_ls(periods, ls, ax=None, lw=1, filename=None, dpi=300, xlim=None, ylim=None, logscale=False, param_profile=None, p_smooth=None, ls_smooth=None, model_smooth=None, figsize=(8, 4))#

Plot Lomb-Scargle periodogram.

Parameters:

  • periods (ndarray) – Period array, in days.

  • ls (ndarray) – Lomb-Scargle periodogram.

  • ax (matplotlib.pyplot.axes) – If provided, the Lomb-Scargle periodogram will be plotted on this Axes instance. Optional, default None.

  • lw (float) – Linewidth.

  • filename (str or Path instance) – If provided, the figure will be saved under this name. Optional, default None.

  • dpi (int) – Dot-per-inch to consider for the plot.

  • xlim (tuple) – x-axis boundaries.

  • ylim (tuple) – y-axis boundaries.

  • logscale (bool) – Whether to use a logarithmic scale for the y-axis or not. Optional, default False.

  • param_profile (ndarray) – Parameters of the Gaussian profiles fitted on the periodogram.

  • p_smooth (ndarray) – Periods corresponding to the smoothed periodogram. Optional, default None

  • ls_smooth (ndarray) – Smoothed periodogram. Optional, default None

  • model_smooth (ndarray) – Model fitted on the smoothed periodogram. Optional, default None

  • figsize (tuple) – Figure size.

Returns:

The plotted figure.

Return type:

Figure

Auto-correlation function (ACF)#

star_privateer.compute_acf(s, dt, periods_in=None, normalise=True, use_scipy_correlate=True, smooth=False, pcutoff=None, pthresh=None, smooth_period=None, win_type='gaussian', verbose=False, cutoff_filter_acf=None)#

Compute autocorrelation function for a uniformly sampled timeseries.

Parameters:

  • s (ndarray) – Flux timeseries in ppm.

  • dt (float) – Time sampling, in days.

Returns:

A tuple of arrays. The first one contains the temporal shifts and the second one the ACF value.

Return type:

tuple of arrays

star_privateer.find_period_acf(periods, acf, pcutoff=None, pthresh=None, smooth=True, smooth_period=None, win_type='gaussian', verbose=False, return_smoothed_acf=False)#

Find significant periodicities identified by the ACF function computation and related control parameters.

Parameters:

  • periods (ndarray) – Period value on which the autocorrelation function has been computed.

  • acf (ndarray) – Autocorrelation function.

  • pcutoff (float) – Maximal period to search for. Optional, default None.

  • pthresh (float) – Minimal period to search for. Optional, default None.

  • smooth (bool) – Whether to smooth the acf before analysing it. Optional, default True.

  • smooth_period (float) – Smoothing period to consider. Will be automatically computed as a tenth of the largest peak in the periodogram computed from the ACF if not provided. Optional, default None.

  • win_type (str) – Window to consider for smoothing. Optional, default gaussian.

Returns:

Tuple with prot, hacf, gacf, all_prots, all_hacf and all_gacf.

Return type:

tuple

star_privateer.plot_acf(periods, acf, ax=None, figsize=(8, 4), lw=1, filename=None, dpi=300, prot=None, xlim=None, acf_additional=None, color_additional=None)#

Plot autocorrelation function (ACF).

Parameters:

  • periods (ndarray) – Period (shift) array, in days.

  • acf (ndarray) – Auto-correlation function.

  • ax (matplotlib.pyplot.axes) – If provided, the ACF will be plotted on this Axes instance. Optional, default None.

  • figsize (tuple) – Figure size.

  • lw (float) – Linewidth.

  • filename (str or Path instance) – If provided, the figure will be saved under this name. Optional, default None.

  • dpi (int) – Dot-per-inch to consider for the plot.

  • prot (float or array-like) – Period to mark with vertical lines.

  • xlim (tuple) – x-axis boundaries. Optional, default None.

  • acf_additional (ndarray or list of arrays) – Additional ACF function to plot. Optional, default None.

  • color_additional (str or list of str) – Color to use for the additional ACF function to plot. Optional, default None.

Returns:

The plotted figure.

Return type:

Figure

Composite spectrum (CS)#

star_privateer.compute_cs(ps, acf, p_acf=None, p_ps=None, normalise=False, smooth_cs=False, smooth_ps=False, index_prot_acf=-1)#

Compute CS from PS (from wavelets or Lomb-Scargle) and ACF (sampled at same periods by default). By default, the CS is normalised with its maximal value.

Parameters:

  • ps (ndarray) – Periodogram power spectrum.

  • acf (ndarray) – Autocorrelation function (ACF).

  • p_acf (ndarray) – Period (shift) array of the ACF function. Optional, default None.

  • p_ps (ndarray) – Period array of the PS. Optional, default None.

  • normalise (bool) – If set to True, the CS will be normalised by its maximum value. Optional, default False.

Returns:

The composite spectrum.

Return type:

ndarray

star_privateer.compute_prot_err_gaussian_fit(periods, ps, n_profile=5, threshold=0.1, verbose=False, pmin=None, pmax=None)#

Fit a series of gaussian profiles on a power spectrum (GWPS or CS) and use it to extract the rotation period estimate and corresponding error.

Parameters:

  • periods (ndarray) – Period array, in days.

  • ps (ndarray) – Power spectrum.

  • n_profile (int) – Maximal number of Gaussian profile to fit.

  • threshold (float) – Peaks with height below this threshold (given as a fraction as the highest peak) will not be fitted.

  • verbose (float) – Output verbosity. Optional, default False.

  • pmin (float) – Minimum period to fit. Optional, default None.

  • pmax (float) – Maximum period to fit. Optional, default None.

Returns:

The rotation period, its uncertainty and the parameters fitted for the n_profile profiles.

Return type:

tuple

star_privateer.plot_cs(periods, cs, ax=None, figsize=(8, 4), lw=1, filename=None, dpi=300, param_gauss=None, xlim=None)#

Plot composite spectrum (CS).

Parameters:

  • periods (ndarray) – Period vector, in days.

  • cs (ndarray) – Composite spectrum.

  • ax (matplotlib.pyplot.axes) – If provided, the composite spectrum will be plotted on this Axes instance. Optional, default None.

  • figsize (tuple) – Figure size.

  • lw (float) – Linewidth.

  • filename (str or Path instance) – If provided, the figure will be saved under this name. Optional, default None.

  • dpi (int) – Dot-per-inch to consider for the plot.

  • param_gauss (ndarray) – Parameters of the Gaussian profiles fitted on the periodogram. Optional, default None.

  • xlim (tuple) – x-axis boundaries. Optional, default None.

Returns:

The plotted figure.

Return type:

Figure

Photometric index (Sph)#

star_privateer.compute_sph(t, s, prot, return_timeseries=False, method='loop', correct_noise=False, noise_band=None)#

Compute photometric activity index of the light curvei, sph. See Mathur et al. (2014).

Parameters:

  • t (ndarray) – Timestamps, in days.

  • s (ndarray) – Flux time series.

  • return_timeseries (bool) – If set to True, the full sph time series will be returned.

  • method (str) – Method to use to compute the sph. Can be loop or reshape.

  • correct_noise (bool) – If set to True, the photon noise in the light curve will be estimated and subtracted from the sph value.

  • noise_band (array-like) – Frequency band bounds, on which the mean photon noise should be estimated. Values should be provided in muHz If None, the noise will be estimated on band ranging from 0.9*nu_nyquist to 0.95*nu_nyquist.

Returns:

If return_timeseries is False, tuple of floats with mean sph computed according to the provided prot value, and corresponding uncertainty. Otherwise, tuple with mean sph, sph timestamps and sph timeseries.

Return type:

tuple of floats or tuple of ndarray

star_privateer.compute_lomb_scargle_sph(t_sph, sph, method='slow')#

Compute the Lomb-Scargle periodogram of the provided Sph time series.

Returns:

Tuple with the periods and the power vectors

Return type:

tuple

Wavelet analysis#

star_privateer.compute_wps(s, dt, periods=None, nbins=500, normalise=False, mother=None, mode=None, remove_coi_gwps=False, correct_scale=True, zero_padding=False, pad=0, backend='pycwt')#

Compute Wavelet Power Spectrum (WPS), Global Wavelet Power Spectrum (GWPS) and corresponding cone of influence (COI) from input time series.

Parameters:

  • s (ndarray) – time series to analyse

  • dt (float) – sampling of the time series (in s)

  • periods (ndarray) – Periods on which to compute the WPS. Optional, if not given, WPS will be computed for periods ranging from 0.1 to 50 day. Must be given in days.

  • nbins (int) – number of bins to consider if the periods vector is generated by the function.

  • normalise (bool) – if set to True, the computed GWPS will be normalised by the maximum value. Optional, default False.

  • mother (object) – mother wavelet to consider. Optional, if set to None, pycwt.Morlet (6) will be used if backend is "pycwt", "cmorl1.5-1.0" if backend is "pywavelets".

  • mode (str) – alternative ways to compute and filter the WPS. mm for a mathematical morphology filter trying to remove brief high frequency systematical noise. ssq to reassign the WPS according to the synchrosqueezing method (Daubechies et al. 2000). ssqmm for both methods combined. Default to None to use the standard wavelet approach. Will only use a Morlet wavelet with w=6

  • remove_coi_gwps (bool) – if set to True, do not account for bins in the cone of influence when computing GWPS. Optional, default False.

  • correct_scale (bool) – If set to True, apply the scale correction from Liu et al. (2007). Optional, default True.

  • zero_padding_wavelet (bool) – If set to True, time series will be zero padded up to the next power of two plus pad before computing wavelet transform. Optional, default False.

  • pad (int) – If zero_padding_wavelet is set to True, the time series will be padded to the power of two corresponding to the first larger than the time series length plus pad. Optional, default 0.

  • backend (str) – Backend to consider for wavelet computation when mode="standard". Either "pycwt" (default) or "pywavelets".

Returns:

Tuple with WPS periods (in day), WPS, GWPS and COI.

Return type:

tuple

star_privateer.plot_wps(t, periods, wps, gwps, coi=None, scales=None, cmap='jet', shading='auto', color_coi='black', ylogscale=False, ax1=None, ax2=None, lw=1, normscale='log', vmin=None, vmax=None, filename=None, dpi=300, param_gauss=None, show_kepler_quarters=False, tref=0, figsize=(14, 8), show_contour=True, significance_contours=False, significance_level=0.95, cmap_contour='cividis', levels=None, contourf_plot=False, ylim=(0.1, 100), xlabel=None, xticks=None, xticklabels=None, yticks=None, yticklabels=None, gwps_logscale=False, gwps_xlim=None, renormalise_gwps_in_ylim=True, color_gwps='black', legend_gwps=None)#

Plot output from compute_wps.

Parameters:

  • t (ndarray) – Time stamp of the time series.

  • periods (ndarray) – Period vector of the wavelet analysis.

  • wps (ndarray) – 2d wavelet power spectrum.

  • gwps (ndarray) – 1d global wavelet power spectrum.

  • coi (ndarray) – Boolean array defining the cone of influence of the wavelet analysis. Optional, default None.

  • cmap (str or ColorMap object) – Colormap to use for the WPS.

  • shading (str) – Shading of the WPS colormesh.

  • color_coi (str) – Color to use for the cone of influence.

  • ylogscale (bool) – If set to True, the y-axis will be shown in log scale.

  • ax1 (Axes) – Axe of external figure to use for WPS plotting. If any of ax1 or ax2 is None, a new figure with corresponding axes will be generated. Optional, default None.

  • ax2 (Axes) – ax2 Axe of external figure to use for GWPS plotting. Optional, default None.

  • lw (float) – Linewidth

  • normscale (str) – Colormap scaling: linear or log.

  • vmin (float) – Minimal value to consider for the colormap.

  • vmax (float) – Maximal value to consider for the colormap.

  • filename (str or Path) – Path where to save the generated figure.

  • dpi (int) – Dot-per-inch of the figure.

  • param_gauss (array-like) – Parameters of the Gaussian profiles fitted on the GWPS.

  • show_kepler_quarters (bool) – For Kepler light curves, whether to show or not the boundary of the quarters.

  • tref (float) – Reference time for the Kepler quarters.

  • figsize (tuple) – Figure size.

  • show_contour (bool) – Whether to show or not contour of the WPS.

  • cmap_contour (str or Colormap) – Colormap to consider for the contours.

  • levels (array-like) – Level on which draw the contour of the WPS on the figure.

  • contourf_plot (bool) – If set to True, a contour-filled plot will be produced for the WPS panel.

  • ylim (tuple) – Limit of the y-axis of the two panels.

  • color_gwps (str) – Color to use for the gwps plot.

  • legend_gwps (NoneType or str) – Label of the gwps plot.

Return type:

The corresponding matplotlib.pyplot.Figure.

Preprocessing#

star_privateer.preprocess(t, s, cut=55, numtaps=10001, bands=None, desired=None)#

Preprocess a time series by substracting its mean value and applying a FIR filter (see scipy.signal.firls). By default the filter will be a high-filter with period cutoff specified by cut, and is applied using scipy.signal.filtfilt.

Parameters:

  • t (float or array-like) – Vector of time stamps (if array) or sampling time (if float). Must be provided in days.

  • s (array-like) – Time series

  • cut (float) – Filter cutoff (in days) in case the default high-pass filter is used. Optional, default 55.

  • numtaps (int) – Number of taps in the filter. Must be odd, default to 10001. See scipy.signal.firls documentation.

  • bands (array-like) – Frequency bands (in Hz) for the filter. Override cut if provided. See scipy.signal.firls documentation. Optional, default None.

  • desired (array-like) – Corresponding gain for the filter if bands is provided. Optional, default None.

Returns:

The filtered time series.

Return type:

ndarray