Ctrl+K
Ctrl+K

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, cmap='jet', normscale='log', ylogscale=False, vmin=None, vmax=None, lw=1, mother=None, xlim=None, dpi=200, smooth_acf=True, cutoff_global=None, cutoff_filter_acf=None, fit_lomb_scargle=True, 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, ylim_wps=(0.1, 100), shading='auto', n_profile=5, threshold=0.1)#

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

  • s (ndarray) – timeseries

  • 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).

  • 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.

  • fit_lomb_scargle (bool) – if set to True, the rotation peaks in the Lomb-Scargle periodograms will be fitted using a Lorentzian profile.

  • 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

Returns:

Tuple of arrays containing output periods, gwps, wps, acf, cs, coi, features, and feature_names arrays if wavelet_analysis is set to True, periods, ps, acf, cs, features, and feature_names, otherwise.

Return type:

tuple

Lomb-Scargle periodogram#

star_privateer.compute_lomb_scargle(t, s, periods=None, renormalise=False, normalisation='standard', return_object=True)#

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

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, verbose=False, back=None, plot_procedure=False)#

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.

Returns:

The rotation period, its uncertainty 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, figsize=(8, 4))#

Plot Lomb-Scargle periodogram.

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.

star_privateer.find_period_acf(periods, acf, pcutoff=None, pthresh=None)#

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.

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).

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.

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

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.

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).

Photometric index (Sph)#

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

Compute photometric activity index of the light curve. See Mathur et al. (2014).

Returns:

Sph computed according to the provided prot value.

Return type:

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=True, mother=None, mode=None, remove_coi_gwps=False, correct_scale=True)#

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 True.

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

  • 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.

Returns:

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

Return type:

tuple

star_privateer.plot_wps(t, periods, wps, gwps, coi, 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.

  • 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.

Contents