astrobase.periodbase.htls module

Contains the Hippke & Heller (2019) transit-least-squared period-search algorithm implementation for periodbase. This depends on the external package written by Hippke & Heller, https://github.com/hippke/tls.

astrobase.periodbase.htls.tls_parallel_pfind(times, mags, errs, magsarefluxes=None, startp=0.1, endp=None, tls_oversample=5, tls_mintransits=3, tls_transit_template='default', tls_rstar_min=0.13, tls_rstar_max=3.5, tls_mstar_min=0.1, tls_mstar_max=2.0, periodepsilon=0.1, nbestpeaks=5, sigclip=10.0, verbose=True, nworkers=None)[source]

Wrapper to Hippke & Heller (2019)’s “transit least squares”, which is BLS, but with a slightly better template (and niceties in the implementation).

A few comments:

  • The time series must be in units of days.

  • The frequency sampling Hippke & Heller (2019) advocate for is cubic in frequencies, instead of linear. Ofir (2014) found that the linear-in-frequency sampling (which is correct for sinusoidal signal detection) isn’t optimal for a Keplerian box signal. He gave an equation for “optimal” sampling. tlsoversample is the factor by which to oversample over that. The grid can be imported independently via:

    from transitleastsquares import period_grid

    The spacing equations are given here: https://transitleastsquares.readthedocs.io/en/latest/Python%20interface.html#period-grid

  • The boundaries of the period search are by default 0.1 day to 99% the baseline of times.

Parameters:
  • times,mags,errs (np.array) – The magnitude/flux time-series to search for transits.
  • magsarefluxes (bool) – transitleastsquares requires fluxes. Therefore if magsarefluxes is set to false, the passed mags are converted to fluxes. All output dictionary vectors include fluxes, not mags.
  • startp,endp (float) – The minimum and maximum periods to consider for the transit search.
  • tls_oversample (int) – Factor by which to oversample the frequency grid.
  • tls_mintransits (int) – Sets the min_n_transits kwarg for the BoxLeastSquares.autoperiod() function.
  • tls_transit_template (str) – default, grazing, or box.
  • tls_rstar_min,tls_rstar_max (float) – The range of stellar radii to consider when generating a frequency grid. In uniits of Rsun.
  • tls_mstar_min,tls_mstar_max (float) – The range of stellar masses to consider when generating a frequency grid. In units of Msun.
  • periodepsilon (float) – The fractional difference between successive values of ‘best’ periods when sorting by periodogram power to consider them as separate periods (as opposed to part of the same periodogram peak). This is used to avoid broad peaks in the periodogram and make sure the ‘best’ periods returned are all actually independent.
  • nbestpeaks (int) – The number of ‘best’ peaks to return from the periodogram results, starting from the global maximum of the periodogram peak values.
  • sigclip (float or int or sequence of two floats/ints or None) –

    If a single float or int, a symmetric sigma-clip will be performed using the number provided as the sigma-multiplier to cut out from the input time-series.

    If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigma-clip. The first element in this list is the sigma value to use for fainter flux/mag values; the second element in this list is the sigma value to use for brighter flux/mag values. For example, sigclip=[10., 3.], will sigclip out greater than 10-sigma dimmings and greater than 3-sigma brightenings. Here the meaning of “dimming” and “brightening” is set by physics (not the magnitude system), which is why the magsarefluxes kwarg must be correctly set.

    If sigclip is None, no sigma-clipping will be performed, and the time-series (with non-finite elems removed) will be passed through to the output.

  • verbose (bool) – Kept for consistency with periodbase functions.
  • nworkers (int or None) – The number of parallel workers to launch for period-search. If None, nworkers = NCPUS.
Returns:

This function returns a dict, referred to as an lspinfo dict in other astrobase functions that operate on periodogram results. The format is similar to the other astrobase period-finders – it contains the nbestpeaks, which is the most important thing. (But isn’t entirely standardized.)

Crucially, it also contains “tlsresult”, which is a dictionary with transitleastsquares spectra (used to get the SDE as defined in the TLS paper), statistics, transit period, mid-time, duration, depth, SNR, and the “odd_even_mismatch” statistic. The full key list is:

dict_keys(['SDE', 'SDE_raw', 'chi2_min', 'chi2red_min', 'period',
'period_uncertainty', 'T0', 'duration', 'depth', 'depth_mean',
'depth_mean_even', 'depth_mean_odd', 'transit_depths',
'transit_depths_uncertainties', 'rp_rs', 'snr', 'snr_per_transit',
'snr_pink_per_transit', 'odd_even_mismatch', 'transit_times',
'per_transit_count', 'transit_count', 'distinct_transit_count',
'empty_transit_count', 'FAP', 'in_transit_count',
'after_transit_count', 'before_transit_count', 'periods',
'power', 'power_raw', 'SR', 'chi2',
'chi2red', 'model_lightcurve_time', 'model_lightcurve_model',
'model_folded_phase', 'folded_y', 'folded_dy', 'folded_phase',
'model_folded_model'])

The descriptions are here:

https://transitleastsquares.readthedocs.io/en/latest/Python%20interface.html#return-values

The remaining resultdict is:

resultdict = {
    'tlsresult':tlsresult,
    'bestperiod': the best period value in the periodogram,
    'bestlspval': the peak associated with the best period,
    'nbestpeaks': the input value of nbestpeaks,
    'nbestlspvals': nbestpeaks-size list of best period peak values,
    'nbestperiods': nbestpeaks-size list of best periods,
    'lspvals': the full array of periodogram powers,
    'periods': the full array of periods considered,
    'tlsresult': Astropy tls result object (BoxLeastSquaresResult),
    'tlsmodel': Astropy tls BoxLeastSquares object used for work,
    'method':'tls' -> the name of the period-finder method,
    'kwargs':{ dict of all of the input kwargs for record-keeping}
}

Return type:

dict