Warning: this page is no longer updated and may contain outdated information.

Please refer to the new Kepler/K2 science website at http://keplerscience.arc.nasa.gov

NASA - National Aeronautics and Space Administration Follow this link to skip to the main content + Contact NASA
Kepler Guest Observer Program

Contributed Software - KEPBLS

Software: PyKE
Version: 1.0.0

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

kepbls infile outfile datacol errcol minper maxper mindur maxdur nsearch nbins plot clobber verbose logfile

infile = string
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 = string
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 = string
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 = string
The column name containing photometric 1-σ errors stored within extension 1 of infile. Typically this name is DETSAP_FLUX_ERR.

minper = float
The shortest trial period on which to search for transits. Units are days.

maxper = float
The longest trial period on which to search for transits. Units are days.

mindur = float
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. Units are hours.

maxdur = float
Provides an upper limit to the range of transit widths tested over each trial period. Units are hours.

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

nbins = integer
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 = boolean
Plot the calculated Normalized Signal Residue as a function of trial orbital period?

clobber = boolean (optional)
Overwrite the output file? if clobber = no and an existing file has the same name as outfile then the task will stop with an error.

verbose = boolean (optional)
Print informative messages and warnings to the shell and logfile?

logfile = string (optional)
Name of the logfile containing error and warning messages.

status = integer
Exit status of the script. It will be non-zero if the task halted with an error. This parameter is set by the task and should not be modified by the user.

kepbls searches for transit-like signal within Kepler light curves using the Box Least Square (BLS) method described by Kovacs, Zucker and Mazeh (2002). The BLS method is to fit a simple function cast over orbital phase units - two flux constants of finite duration , meeting at specific phases where there occurs a discontinuity. The fainter constant is an approximation to the floor of planetary transit and the phase difference between the two discontinuities is an approximation for transit width. Phase space containing period, depth, width and epoch of mid-transit are explored by calculating the Signal Residue statistic between phased data and model. The greater the value of the statistic the more the phased data resemble a simplified phased transit light curve. The output file stores a new table containing the maximum value of the Signal Residue, most-likely transit duration and mid-transit epoch for each trial period.


  1. Calculate the BLS statistic for a quarter of long cadence data over 1,000 trial periods between 39.5-40.5 days. Test box functions of width 1-12 hours over data binned into 1,000 orbital phase bins for each trial period:
    • kepbls infile=kplr008478994-2009259160929_llc.fits outfile=kepbls.fits datacol=DETSAP_FLUX errcol=DETSAP_FLUX_ERR minper=39.5 maxper=40.5 mindur=1.0 maxdur=12.0 nsearch=1000 nbins=1000 plot=y

Full completion upon 12 stitched quarters of Kepler long cadence target, performing 1,000 period trials and binning the data into 1,000 phase bins, using a 3.06 GHz Intel Core 2 Duo Mac running OS 10.7.5, takes 26 minutes.

Please send bug reports and suggestions to keplergo@mail.arc.nasa.gov.


Initial software release (MS)

kepflatten, kepstitch, keptransit

Questions concerning Kepler's science opportunities and open programs, public archive or community tools? Contact us via the email address.
FirstGov - Your First Click to the US Government
+ Freedom of Information Act
+ Budgets, Strategic Plans and Accountability Reports
+ The President's Management Agenda
+ NASA Privacy Statement, Disclaimer,
and Accessibility Certification

+ Inspector General Hotline
+ Equal Employment Opportunity Data Posted Pursuant
to the No Fear Act

+ Information-Dissemination Priorities and Inventories
NASA - National Aeronautics and Space Administration
Editor: Martin Still
NASA Official: Jessie Dotson
Last Updated: Jan 11, 2013
+ Contact NASA