astrobase.periodbase.abls module

Contains the Kovacs, et al. (2002) Box-Least-squared-Search period-search algorithm implementation for periodbase. This uses the implementation in Astropy 3.1, so requires that version.

astrobase.periodbase.abls.bls_serial_pfind(times, mags, errs, magsarefluxes=False, startp=0.1, endp=100.0, stepsize=0.0005, mintransitduration=0.01, maxtransitduration=0.4, ndurations=100, autofreq=True, blsobjective='likelihood', blsmethod='fast', blsoversample=10, blsmintransits=3, blsfreqfactor=10.0, periodepsilon=0.1, nbestpeaks=5, sigclip=10.0, endp_timebase_check=True, verbose=True, raiseonfail=False)[source]

Runs the Box Least Squares Fitting Search for transit-shaped signals.

Based on the version of BLS in Astropy 3.1: astropy.stats.BoxLeastSquares. If you don’t have Astropy 3.1, this module will fail to import. Note that by default, this implementation of bls_serial_pfind doesn’t use the .autoperiod() function from BoxLeastSquares but uses the same auto frequency-grid generation as the functions in periodbase.kbls. If you want to use Astropy’s implementation, set the value of autofreq kwarg to ‘astropy’.

The dict returned from this function contains a blsmodel key, which is the generated model from Astropy’s BLS. Use the .compute_stats() method to calculate the required stats like SNR, depth, duration, etc.

Parameters:
  • times,mags,errs (np.array) – The magnitude/flux time-series 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 step-size 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.
  • ndurations (int) – The number of transit durations to use in the period-search.
  • autofreq (bool or str) –

    If this is True, the values of stepsize and nphasebins will be ignored, and these, along with a frequency-grid, 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))
    

    If this is False, you must set startp, endp, and stepsize as appropriate.

    If this is str == ‘astropy’, will use the astropy.stats.BoxLeastSquares.autoperiod() function to calculate the frequency grid instead of the kbls method.

  • blsobjective ({'likelihood','snr'}) – Sets the type of objective to optimize in the BoxLeastSquares.power() function.
  • blsmethod ({'fast','slow'}) – Sets the type of method to use in the BoxLeastSquares.power() function.
  • blsoversample ({'likelihood','snr'}) – Sets the oversample kwarg for the BoxLeastSquares.power() function.
  • blsmintransits (int) – Sets the min_n_transits kwarg for the BoxLeastSquares.autoperiod() function.
  • blsfreqfactor (float) – Sets the frequency_factor kwarg for the BoxLeastSquares.autperiod() function.
  • 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.

  • endp_timebase_check (bool) – If True, will check if the endp value is larger than the time-base of the observations. If it is, will change the endp value such that it is half of the time-base. If False, will allow an endp larger than the time-base of the observations.
  • verbose (bool) – If this is True, will indicate progress and details about the frequency grid used for the period search.
  • raiseonfail (bool) – If True, raises an exception if something goes wrong. Otherwise, returns None.
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 period-finders, 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': nbestpeaks-size list of best period peak values,
 'nbestperiods': nbestpeaks-size 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,
 'durations': the array of durations used to run BLS,
 'blsresult': Astropy BLS result object (BoxLeastSquaresResult),
 'blsmodel': Astropy BLS BoxLeastSquares object used for work,
 'stepsize': the actual stepsize used,
 'nfreq': the actual nfreq used,
 'durations': the durations array used,
 'mintransitduration': the input mintransitduration,
 'maxtransitduration': the input maxtransitdurations,
 'method':'bls' -> the name of the period-finder method,
 'kwargs':{ dict of all of the input kwargs for record-keeping}}

Return type:

dict

astrobase.periodbase.abls.bls_parallel_pfind(times, mags, errs, magsarefluxes=False, startp=0.1, endp=100.0, stepsize=0.0001, mintransitduration=0.01, maxtransitduration=0.4, ndurations=100, autofreq=True, blsobjective='likelihood', blsmethod='fast', blsoversample=5, blsmintransits=3, blsfreqfactor=10.0, nbestpeaks=5, periodepsilon=0.1, sigclip=10.0, endp_timebase_check=True, verbose=True, nworkers=None)[source]

Runs the Box Least Squares Fitting Search for transit-shaped signals.

Breaks up the full frequency space into chunks and passes them to parallel BLS workers.

Based on the version of BLS in Astropy 3.1: astropy.stats.BoxLeastSquares. If you don’t have Astropy 3.1, this module will fail to import. Note that by default, this implementation of bls_parallel_pfind doesn’t use the .autoperiod() function from BoxLeastSquares but uses the same auto frequency-grid generation as the functions in periodbase.kbls. If you want to use Astropy’s implementation, set the value of autofreq kwarg to ‘astropy’. The generated period array will then be broken up into chunks and sent to the individual 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.0e-3 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.

In particular, when you want to get reliable estimates of the SNR, transit depth, duration, etc. that Astropy’s BLS gives you, rerun bls_serial_pfind with startp, and endp close to the best period you want to characterize the transit at. The dict returned from that function contains a blsmodel key, which is the generated model from Astropy’s BLS. Use the .compute_stats() method to calculate the required stats.

Parameters:
  • times,mags,errs (np.array) – The magnitude/flux time-series 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 step-size 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.
  • ndurations (int) – The number of transit durations to use in the period-search.
  • autofreq (bool or str) –

    If this is True, the values of stepsize and nphasebins will be ignored, and these, along with a frequency-grid, 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))
    

    If this is False, you must set startp, endp, and stepsize as appropriate.

    If this is str == ‘astropy’, will use the astropy.stats.BoxLeastSquares.autoperiod() function to calculate the frequency grid instead of the kbls method.

  • blsobjective ({'likelihood','snr'}) – Sets the type of objective to optimize in the BoxLeastSquares.power() function.
  • blsmethod ({'fast','slow'}) – Sets the type of method to use in the BoxLeastSquares.power() function.
  • blsoversample ({'likelihood','snr'}) – Sets the oversample kwarg for the BoxLeastSquares.power() function.
  • blsmintransits (int) – Sets the min_n_transits kwarg for the BoxLeastSquares.autoperiod() function.
  • blsfreqfactor (float) – Sets the frequency_factor kwarg for the BoxLeastSquares.autoperiod() function.
  • 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.

  • endp_timebase_check (bool) – If True, will check if the endp value is larger than the time-base of the observations. If it is, will change the endp value such that it is half of the time-base. If False, will allow an endp larger than the time-base 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 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. This is a standardized format across all astrobase period-finders, 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': nbestpeaks-size list of best period peak values,
 'nbestperiods': nbestpeaks-size 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,
 'durations': the array of durations used to run BLS,
 'blsresult': Astropy BLS result object (BoxLeastSquaresResult),
 'blsmodel': Astropy BLS BoxLeastSquares object used for work,
 'stepsize': the actual stepsize used,
 'nfreq': the actual nfreq used,
 'durations': the durations array used,
 'mintransitduration': the input mintransitduration,
 'maxtransitduration': the input maxtransitdurations,
 'method':'bls' -> the name of the period-finder method,
 'kwargs':{ dict of all of the input kwargs for record-keeping}}

Return type:

dict