astrobase.periodbase.kbls module¶
Contains the Kovacs, et al. (2002) BoxLeastsquaredSearch periodsearch algorithm implementation for periodbase.

astrobase.periodbase.kbls.
bls_serial_pfind
(times, mags, errs, magsarefluxes=False, startp=0.1, endp=100.0, stepsize=0.0005, mintransitduration=0.01, maxtransitduration=0.4, nphasebins=200, autofreq=True, periodepsilon=0.1, nbestpeaks=5, sigclip=10.0, endp_timebase_check=True, verbose=True, get_stats=True)[source]¶ Runs the Box Least Squares Fitting Search for transitshaped signals.
Based on eebls.f from Kovacs et al. 2002 and pythonbls from ForemanMackey et al. 2015. This is the serial version (which is good enough in most cases because BLS in Fortran is fairly fast). If nfreq > 5e5, this will take a while.
Parameters:  times,mags,errs (np.array) – The magnitude/flux timeseries to search for transits.
 magsarefluxes (bool) – If the input measurement values in mags and errs are in fluxes, set this to True.
 startp,endp (float) – The minimum and maximum periods to consider for the transit search.
 stepsize (float) – The stepsize in frequency to use when constructing a frequency grid for the period search.
 mintransitduration,maxtransitduration (float) – The minimum and maximum transitdurations (in units of phase) to consider for the transit search.
 nphasebins (int) – The number of phase bins to use in the period search.
 autofreq (bool) –
If this is True, the values of stepsize and nphasebins will be ignored, and these, along with a frequencygrid, will be determined based on the following relations:
nphasebins = int(ceil(2.0/mintransitduration)) if nphasebins > 3000: nphasebins = 3000 stepsize = 0.25*mintransitduration/(times.max()times.min()) minfreq = 1.0/endp maxfreq = 1.0/startp nfreq = int(ceil((maxfreq  minfreq)/stepsize))
 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 sigmaclip will be performed using the number provided as the sigmamultiplier to cut out from the input timeseries.
If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigmaclip. 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 10sigma dimmings and greater than 3sigma 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 sigmaclipping will be performed, and the timeseries (with nonfinite elems removed) will be passed through to the output.
 endp_timebase_check (bool) – If True, will check if the
endp
value is larger than the timebase of the observations. If it is, will change theendp
value such that it is half of the timebase. If False, will allow anendp
larger than the timebase of the observations.  verbose (bool) – If this is True, will indicate progress and details about the frequency grid used for the period search.
 get_stats (bool) –
If True, runs
bls_stats_singleperiod()
for each of the best periods in the output and injects the output into the output dict so you only have to run this function to get the periods and their stats.The output dict from this function will then contain a ‘stats’ key containing a list of dicts with statistics for each period in
resultdict['nbestperiods']
. These dicts will contain fit values of transit parameters after a trapezoid transit model is fit to the phased light curve at each period inresultdict['nbestperiods']
, i.e. fit values for period, epoch, transit depth, duration, ingress duration, and the SNR of the transit.NOTE: make sure to check the ‘fit_status’ key for each
resultdict['stats']
item to confirm that the trapezoid transit model fit succeeded and that the stats calculated are valid.
Returns: This function returns a dict, referred to as an lspinfo dict in other astrobase functions that operate on periodogram results. This is a standardized format across all astrobase periodfinders, and is of the form below:
{'bestperiod': the best period value in the periodogram, 'bestlspval': the periodogram peak associated with the best period, 'nbestpeaks': the input value of nbestpeaks, 'nbestlspvals': nbestpeakssize list of best period peak values, 'nbestperiods': nbestpeakssize list of best periods, 'stats': BLS stats for each best period, 'lspvals': the full array of periodogram powers, 'frequencies': the full array of frequencies considered, 'periods': the full array of periods considered, 'blsresult': the result dict from the eebls.f wrapper function, 'stepsize': the actual stepsize used, 'nfreq': the actual nfreq used, 'nphasebins': the actual nphasebins used, 'mintransitduration': the input mintransitduration, 'maxtransitduration': the input maxtransitdurations, 'method':'bls' > the name of the periodfinder method, 'kwargs':{ dict of all of the input kwargs for recordkeeping}}
Return type: dict

astrobase.periodbase.kbls.
bls_parallel_pfind
(times, mags, errs, magsarefluxes=False, startp=0.1, endp=100.0, stepsize=0.0001, mintransitduration=0.01, maxtransitduration=0.4, nphasebins=200, autofreq=True, nbestpeaks=5, periodepsilon=0.1, sigclip=10.0, endp_timebase_check=True, verbose=True, nworkers=None, get_stats=True)[source]¶ Runs the Box Least Squares Fitting Search for transitshaped signals.
Based on eebls.f from Kovacs et al. 2002 and pythonbls from ForemanMackey et al. 2015. Breaks up the full frequency space into chunks and passes them to parallel BLS workers.
NOTE: the combined BLS spectrum produced by this function is not identical to that produced by running BLS in one shot for the entire frequency space. There are differences on the order of 1.0e3 or so in the respective peak values, but peaks appear at the same frequencies for both methods. This is likely due to different aliasing caused by smaller chunks of the frequency space used by the parallel workers in this function. When in doubt, confirm results for this parallel implementation by comparing to those from the serial implementation above.
Parameters:  times,mags,errs (np.array) – The magnitude/flux timeseries to search for transits.
 magsarefluxes (bool) – If the input measurement values in mags and errs are in fluxes, set this to True.
 startp,endp (float) – The minimum and maximum periods to consider for the transit search.
 stepsize (float) – The stepsize in frequency to use when constructing a frequency grid for the period search.
 mintransitduration,maxtransitduration (float) – The minimum and maximum transitdurations (in units of phase) to consider for the transit search.
 nphasebins (int) – The number of phase bins to use in the period search.
 autofreq (bool) –
If this is True, the values of stepsize and nphasebins will be ignored, and these, along with a frequencygrid, will be determined based on the following relations:
nphasebins = int(ceil(2.0/mintransitduration)) if nphasebins > 3000: nphasebins = 3000 stepsize = 0.25*mintransitduration/(times.max()times.min()) minfreq = 1.0/endp maxfreq = 1.0/startp nfreq = int(ceil((maxfreq  minfreq)/stepsize))
 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 sigmaclip will be performed using the number provided as the sigmamultiplier to cut out from the input timeseries.
If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigmaclip. 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 10sigma dimmings and greater than 3sigma 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 sigmaclipping will be performed, and the timeseries (with nonfinite elems removed) will be passed through to the output.
 endp_timebase_check (bool) – If True, will check if the
endp
value is larger than the timebase of the observations. If it is, will change theendp
value such that it is half of the timebase. If False, will allow anendp
larger than the timebase of the observations.  verbose (bool) – If this is True, will indicate progress and details about the frequency grid used for the period search.
 nworkers (int or None) – The number of parallel workers to launch for periodsearch. If None, nworkers = NCPUS.
 get_stats (bool) –
If True, runs
bls_stats_singleperiod()
for each of the best periods in the output and injects the output into the output dict so you only have to run this function to get the periods and their stats.The output dict from this function will then contain a ‘stats’ key containing a list of dicts with statistics for each period in
resultdict['nbestperiods']
. These dicts will contain fit values of transit parameters after a trapezoid transit model is fit to the phased light curve at each period inresultdict['nbestperiods']
, i.e. fit values for period, epoch, transit depth, duration, ingress duration, and the SNR of the transit.NOTE: make sure to check the ‘fit_status’ key for each
resultdict['stats']
item to confirm that the trapezoid transit model fit succeeded and that the stats calculated are valid.
Returns: This function returns a dict, referred to as an lspinfo dict in other astrobase functions that operate on periodogram results. This is a standardized format across all astrobase periodfinders, and is of the form below:
{'bestperiod': the best period value in the periodogram, 'bestlspval': the periodogram peak associated with the best period, 'nbestpeaks': the input value of nbestpeaks, 'nbestlspvals': nbestpeakssize list of best period peak values, 'nbestperiods': nbestpeakssize list of best periods, 'stats': list of stats dicts returned for each best period, 'lspvals': the full array of periodogram powers, 'frequencies': the full array of frequencies considered, 'periods': the full array of periods considered, 'blsresult': list of result dicts from eebls.f wrapper functions, 'stepsize': the actual stepsize used, 'nfreq': the actual nfreq used, 'nphasebins': the actual nphasebins used, 'mintransitduration': the input mintransitduration, 'maxtransitduration': the input maxtransitdurations, 'method':'bls' > the name of the periodfinder method, 'kwargs':{ dict of all of the input kwargs for recordkeeping}}
Return type: dict

astrobase.periodbase.kbls.
bls_stats_singleperiod
(times, mags, errs, period, magsarefluxes=False, sigclip=10.0, perioddeltapercent=10, nphasebins=200, mintransitduration=0.01, maxtransitduration=0.4, ingressdurationfraction=0.1, verbose=True)[source]¶ This calculates the SNR, depth, duration, a refit period, and time of centertransit for a single period.
The equation used for SNR is:
SNR = (transit model depth / RMS of LC with transit model subtracted) * sqrt(number of points in transit)
NOTE: you should set the kwargs sigclip, nphasebins, mintransitduration, maxtransitduration to what you used for an initial BLS run to detect transits in the input light curve to match those input conditions.
Parameters:  times,mags,errs (np.array) – These contain the magnitude/flux timeseries and any associated errors.
 period (float) – The period to search around and refit the transits. This will be used to calculate the start and end periods of a rerun of BLS to calculate the stats.
 magsarefluxes (bool) – Set to True if the input measurements in mags are actually fluxes and not magnitudes.
 sigclip (float or int or sequence of two floats/ints or None) –
If a single float or int, a symmetric sigmaclip will be performed using the number provided as the sigmamultiplier to cut out from the input timeseries.
If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigmaclip. 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 10sigma dimmings and greater than 3sigma 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 sigmaclipping will be performed, and the timeseries (with nonfinite elems removed) will be passed through to the output.
 perioddeltapercent (float) –
The fraction of the period provided to use to search around this value. This is a percentage. The period range searched will then be:
[period  (perioddeltapercent/100.0)*period, period + (perioddeltapercent/100.0)*period]
 nphasebins (int) – The number of phase bins to use in the BLS run.
 mintransitduration (float) – The minimum transit duration in phase to consider.
 maxtransitduration (float) – The maximum transit duration to consider.
 ingressdurationfraction (float) – The fraction of the transit duration to use to generate an initial value of the transit ingress duration for the BLS model refit. This will be fit by this function.
 verbose (bool) – If True, will indicate progress and any problems encountered.
Returns: A dict of the following form is returned:
{'period': the refit best period, 'epoch': the refit epoch (i.e. midtransit time), 'snr':the SNR of the transit, 'transitdepth':the depth of the transit, 'transitduration':the duration of the transit, 'ingressduration':if trapezoid fit OK, is the ingress duration, 'npoints_in_transit':the number of LC points in transit, 'fit_status': 'ok' or 'trapezoid model fit failed,...', 'nphasebins':the input value of nphasebins, 'transingressbin':the phase bin containing transit ingress, 'transegressbin':the phase bin containing transit egress, 'blsmodel':the full BLS model used along with its parameters, 'subtractedmags':BLS model  phased light curve, 'phasedmags':the phase light curve, 'phases': the phase values}
You should check the ‘fit_status’ key in this returned dict for a value of ‘ok’. If it is ‘trapezoid model fit failed, using box model’, you may not want to trust the transit period and epoch found.
Return type: dict

astrobase.periodbase.kbls.
bls_snr
(blsdict, times, mags, errs, assumeserialbls=False, magsarefluxes=False, sigclip=10.0, npeaks=None, perioddeltapercent=10, ingressdurationfraction=0.1, verbose=True)[source]¶ Calculates the signal to noise ratio for each best peak in the BLS periodogram, along with transit depth, duration, and refit period and epoch.
The following equation is used for SNR:
SNR = (transit model depth / RMS of LC with transit model subtracted) * sqrt(number of points in transit)
Parameters:  blsdict (dict) –
This is an lspinfo dict produced by either bls_parallel_pfind or bls_serial_pfind in this module, or by your own BLS function. If you provide results in a dict from an external BLS function, make sure this matches the form below:
{'bestperiod': the best period value in the periodogram, 'bestlspval': the periodogram peak associated with the best period, 'nbestpeaks': the input value of nbestpeaks, 'nbestlspvals': nbestpeakssize list of best period peak values, 'nbestperiods': nbestpeakssize list of best periods, 'lspvals': the full array of periodogram powers, 'frequencies': the full array of frequencies considered, 'periods': the full array of periods considered, 'blsresult': list of result dicts from eebls.f wrapper functions, 'stepsize': the actual stepsize used, 'nfreq': the actual nfreq used, 'nphasebins': the actual nphasebins used, 'mintransitduration': the input mintransitduration, 'maxtransitduration': the input maxtransitdurations, 'method':'bls' > the name of the periodfinder method, 'kwargs':{ dict of all of the input kwargs for recordkeeping}}
 times,mags,errs (np.array) – These contain the magnitude/flux timeseries and any associated errors.
 assumeserialbls (bool) – If this is True, this function will not rerun BLS around each best peak in the input lspinfo dict to refit the periods and epochs. This is usally required for bls_parallel_pfind so set this to False if you use results from that function. The parallel method breaks up the frequency space into chunks for speed, and the results may not exactly match those from a regular BLS run.
 magsarefluxes (bool) – Set to True if the input measurements in mags are actually fluxes and not magnitudes.
 npeaks (int or None) – This controls how many of the periods in blsdict[‘nbestperiods’] to find the SNR for. If it’s None, then this will calculate the SNR for all of them. If it’s an integer between 1 and len(blsdict[‘nbestperiods’]), will calculate for only the specified number of peak periods, starting from the best period.
 perioddeltapercent (float) –
The fraction of the period provided to use to search around this value. This is a percentage. The period range searched will then be:
[period  (perioddeltapercent/100.0)*period, period + (perioddeltapercent/100.0)*period]
 ingressdurationfraction (float) – The fraction of the transit duration to use to generate an initial value of the transit ingress duration for the BLS model refit. This will be fit by this function.
 verbose (bool) – If True, will indicate progress and any problems encountered.
Returns: A dict of the following form is returned:
{'npeaks: the number of periodogram peaks requested to get SNR for, 'period': list of refit best periods for each requested peak, 'epoch': list of refit epochs (i.e. midtransit times), 'snr':list of SNRs of the transit for each requested peak, 'transitdepth':list of depths of the transits, 'transitduration':list of durations of the transits, 'nphasebins':the input value of nphasebins, 'transingressbin':the phase bin containing transit ingress, 'transegressbin':the phase bin containing transit egress, 'allblsmodels':the full BLS models used along with its parameters, 'allsubtractedmags':BLS models  phased light curves, 'allphasedmags':the phase light curves, 'allphases': the phase values}
Return type: dict
 blsdict (dict) –