kepbls: perform Box-Least Square searches for periodic exoplanet transits

pyke.kepbls.kepbls(infile, outfile=None, datacol='DETSAP_FLUX', errcol='DETSAP_FLUX_ERR', minper=1.0, maxper=30, mindur=0.5, maxdur=12, nsearch=1000, nbins=1000, plot=False, overwrite=False, verbose=False, logfile='kepbls.log')

kepbls – Perform Box-Least Square searches for periodic exoplanet transits


infile : str

The name of a standard format FITS file containing a Kepler light curve within the first data extension. The data in infile will typically have been flattened by kepflatten. Multiple quarters can be searched by appending light curves within a single file using kepstitch.

outfile : str

The name of the output FITS file. outfile will be a direct copy of infile but with a new extension called BLS appended containing a table of i) trial periods, PERIOD, ii) a reference Barycentric Julian Date (BJD) corresponding the center of the most transit-like structure in the folded light curve at the trial period, BJD0, iii) a duration (in hours) corresponding the width of the most transit-like structure in the folded light curve at the trial period, DURATION, and iv) the normalized signal residue of the most transit-like structure in the folded light curve at the trial period, SIG_RES. The definition of SIG_RES is provided in equation 5 of Kovacs, Zucker and Mazeh (2002). The maximum calculated value of SIG_RES and the corresponding trial period, BJD epoch and transit duration are stored as keywords in the BLS extension called SIGNRES, PERIOD, BJD0, TRANSDUR.

datacol : str

The column name containing data stored within FITS extension 1 of infile. This data will be searched for outliers. Typically this name is DETSAP_FLUX (Detrended Simple Aperture Photometry fluxes). This version of the data is computed by the task kepflatten. Other flux data will be accepted - SAP_FLUX (Simple Aperture Photometry), PDCSAP_FLUX (Pre-search Data Conditioning fluxes) or CBVSAP_FLUX (SAP_FLUX corrected for systematic artifacts by the PyKE tool kepcotrend). However neither of these three options are recommended because the flux data contain either astrophysical variability, systematic variability, or both.

errcol : str

The column name containing photometric 1-sigma errors stored within extension 1 of infile. Typically this name is DETSAP_FLUX_ERR.

minper : float [days]

The shortest trial period on which to search for transits.

maxper : float [days]

The longest trial period on which to search for transits.

mindur : float [hours]

For each trial period, the BLS function will be fit to the data by i) iterating upon the epoch of mid-transit in the model, and ii) adjusting the width of the modeled transit. The width is adjusted systematically in step sizes equaling the cadence of the input data. mindur provides a lower limit to the range of transit widths tested.

maxdur : float [hours]

Provides an upper limit to the range of transit widths tested over each trial period.

nsearch : int

The number of trial periods to search between the lower bound minper and the upper bound maxper.

nbins : int

Before the BLS transit model is fit to the data, data are folded upon the trail orbital period and then phase binned by calculating the mean flux level within each bin interval. nbins is the number of phase bins in which to store the data before each fit.

plot : bool

Plot the calculated Normalized Signal Residue as a function of trial orbital period?

overwrite : bool

Overwrite the output file? If overwrite is False and an existing file has the same name as outfile then the task will stop with an error.

verbose : bool

Print informative messages and warnings to the shell and logfile?

logfile : str

Name of the logfile containing error and warning messages.


After using kepflatten to remove low frequency variability in kplr011904151-2009350155506_llc.fits, we can use the output, kepflatten.fits, into kepbls, i.e.,

$ kepbls kepflatten.fits --datacol DETSAP_FLUX --errcol DETSAP_FLUX_ERR
--minper 0.8 --maxper 1.0 --mindur 1.0 --maxdur 12.0 --nsearch 1000
--nbins 1000 --plot --verbose

     Best trial period = 0.8375062346458435 days
   Time of mid-transit = BJD 2455093.5457274746
      Transit duration = 1.7099086232483387 hours
Maximum signal residue = 4.487271046981536e-06