kepdetrend: detrend aperture photometry data

pyke.kepdetrend.kepdetrend(infile, ranges1, ranges2, npoly1, npoly2, nsig1, nsig2, niter1, niter2, outfile=None, datacol='SAP_FLUX', errcol='SAP_FLUX_ERR', popnans=False, plot=False, overwrite=False, verbose=False, logfile='kepdetrend.log')

kepdetrend – Detrend aperture photometry data

Simple Aperture Photometry (SAP) data can contain a series of systematic trends associated with the spacecraft, detector and environment rather than the target. Within the Kepler pipeline these contaminants are treated during Pre-search Data Conditioning (PDC) and cleaned data are provided in the archived files as the PDCSAP_FLUX data. See the Kepler Data Characteristics Handbook for more precise descriptions of systematics. The Kepler pipeline attempts to remove systematics with a combination of data detrending and cotrending against weighted cotrending basis vectors derived from the time series structure most-common to all neighbors of the scientific target. These processes are imperfect but tackled within the pipeline in the spirit of correcting as many targets as possible with enough accuracy for the mission to meet exoplanet detection specifications. This approach is, however, not optimized for individual targets. Users of the Kepler archive may well find that individually-tailored detrending and cotrending yields corrected light curves more suited to their science. The purpose of kepdetrend is to provide a detrending algorithm that can be tailored for individual targets. We stress that an absolute correction is often impossible for Kepler data. We also recommend the use of kepcotrend instead of kepdetrend for systematic removal in most Kepler targets.

The current version of this task asks the user to define data ranges that are free of a systematic feature that needs to be removed and can be well-characterized by a single polynomial function. This function is what the task attempts to correct data to. The user then defines a data range that needs correcting and fits this with a second polynomial. The correction is the subtraction of one polynomial from the other in the data range to be detrended. The examples plotted below show the piecemeal correction of three systematic features within a Q2 light curve. These three corrections are provided in the task examples below.

Parameters:

infile : str

The name of a MAST standard format FITS file containing a Kepler light curve within the first data extension.

outfile : str

The name of the output FITS file. outfile will be an amended version of infile with specified time ranges detrended by subtraction of a polynomial fit.

datacol : str

The column name containing data stored within extension 1 of infile. This data will be detrended. Typically this name is SAP_FLUX (Simple Aperture Photometry fluxes), but any data column within extension 1 of the FITS file can be corrected.

errcol : str

The uncertainty data coupled to datacol. Typically this column is called SAP_FLUX_ERR. If no errors are associated with datacol then use errcol=None.

ranges1, ranges2 : list, list

Time ranges are supplied as comma-separated pairs of Barycentric Julian Dates (BJDs). Multiple ranges are separated by a semi-colon. An example containing two time ranges is:

'2455012.48517,2455014.50072;2455022.63487,2455025.08231'

Data within the range ranges1 will be detrended by subtracting the difference between the best fit to data in that range and the best fit function in the range ranges2 extrapolated into ranges1.

npoly1, npoly2 : int

The polynomial order for the function that fits the data ranges to be detrended.

nsig1, nsig2 : float, float

The data to be detrended is fit by a polynomial using an iterative scheme. After a best fit is found, those data points deviating from the fit by more than this specified amount are rejected and the remaining data are fit again, etc, until there are no further rejections. This threshold is in units of the standard deviation of the data about the best fit function.

niter1, niter2 : int, int

The polynomial fit over the data to be detrended will be iterated until there are no further outlier rejections or the number of iterations exceeds niter1 (niter2).

popnans : bool

Keep NaN flux values (times without a flux measurement) in the output FITS file. If set to no, any rows in the input FITS file containing NaNs will no be in the output file.

plot : boolean

Plot the data, the fits and the correction?

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.

Examples

$ kepdetrend kplr002436324-2009259160929_llc.fits --datacol SAP_FLUX
--errcol SAP_FLUX_ERR --ranges1 '2455063.59357,2455066.47292' --npoly1 5
--nsig1 3 --niter1 10 --ranges2 '2455060.57026,2455063.59357;2455066.9768,2455068.99235'
--npoly2 5 --nsig2 3 --niter2 10 --plot --verbose
../_images/kepdetrend.png