kepflatten -- Remove low frequency variability from time-series, preserve transits and flares
kepflatten infile outfile datacol nsig stepsize winsize npoly niter operation ranges
plot plotfit clobber verbose logfile
infile = string
The name of a MAST standard format FITS file containing a Kepler light curve
within the first data extension.
outfile = string
The name of the output FITS file. outfile will be a direct copy of
infile but with NaN timestamps removed and two new columns in the 1st extension - DETSAP_FLUX (a flattened or detrended for low-frequency variations version of the data) and DETSAP_FLUX_ERR (the associated 1-σ error).
datacol = string
The column name containing data stored within extension 1 of infile.
Typically this name is
SAP_FLUX (Simple Aperture Photometry fluxes), PDCSAP_FLUX
(Pre-search Data Conditioning fluxes) or CBVSAP_FLUX (SAP_FLUX corrected for systematic artifacts by the PyKE tool kepcotrend).
errcol = string
The column name containing photometric 1-σ errors stored within extension 1 of infile.
Typically this name is
SAP_FLUX_ERR (Simple Aperture Photometry fluxes), PDCSAP_FLUX_ERR
(Pre-search Data Conditioning fluxes). The error column coupled to CBVSAP_FLUX data is SAP_FLUX_ERR. kepflatten normalizes datacol and errcol consistently using a series of best fit polynomials.
nsig = float
The sigma clipping threshold in units of σ. Data deviating from a best fit function by
more than the threshold will ignored during subsequent fit iterations.
stepsize = float
The data within datacol is unlikely to be well represented by a single
polynomial function. stepsize splits the data up into a series of time
blocks, each is fit independently by a separate function. The user can provide
an informed choice of stepsize after inspecting the data with the
kepdraw tool. Units are days.
winsize = float
The size of the window to be fit during each step. Units are days. winsize must be greater or equal to stepsize. winsize >> stepsize is recommended.
npoly = integer
The order of each piecemeal polynomial function.
niter = integer
If outliers outside of nsig are found in a particular data section, that data will be removed
temporarily and the time series fit again. This will be iterated niter
times before freezing upon the best current fit.
ranges = string
The user can choose specific time ranges of data on which to work. This could,
for example, avoid removing known stellar flares from a dataset. Ranges can
be supplied using one of two methods.
- 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:
If the user wants to correct the entire time series then providing
ranges = '0,0' will tell the task to operate on the whole time
- The user can provide time ranges within a pre-prepared ascii file containing
one time range per line, e.g.:
The file 'arbitraryname.txt' is provided to the task using ranges =
@arbitraryname.txt, where the '@' tells the task that a file is being provided.
Files containing time ranges can be generated manually or with the aid of
data inspection using the task keprange.
plot = boolean
Plot the data, fit, outliers and result?
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
kepflatten detrends data for low-frequency photometric structure by dividing by the mean of best-fit sliding polynomials over a sequential series of small time ranges across the data. For example, a typical timestamp is fit three times of stepsize=1.0 and winsize=3.0. The adopted fit to the timestamp will be the mean of the three values. Outliers are iteratively-clipped from the fit, therefore structure in e.g. short-lived transits or flares are better preserved compared to e.g. bandpass filtering methods (kepfilter). Optionally, input data, best fits, fit outliers and output data are rendered to a plot window. In many respects kepflatten performs the opposite task to kepoutlier which removes statistical outliers while preserving low-frequency structure in light curves.
- Remove stellar rotation structure from a PDCSAP time-series:
- kepflatten infile=kplr012557548-2011177032512_llc.fits
outfile=kepflatten.fits datacol=PDCSAP_FLUX errcol=PDCSAP_FLUX_ERR nsig=3 stepsize=1.0 winsize=3.0 npoly=3
Full completion upon one quarter of Kepler long cadence target using a 3.06
GHz Intel Core 2 Duo Mac running OS 10.6.4 takes a few minutes. Running times
increase by several factors if input data contains NaNs. These will be
filtered out before task execution.
BUGS AND LIMITATIONS
The Kepler PyRAF package is privately-developed software made available to
the community through the contributed software page of the GO program at
http://keplerscience.arc.nasa.gov/ContributedSoftware.shtml. It is not an
official software product of the Kepler mission. Bugs and errors are not
the responsibility of NASA or the Kepler Team. Please send bug reports and
suggestions to firstname.lastname@example.org.
Initial software release (MS)
Added new parameter winsize. Bug fix: files with more than 4,000 timestamps were not fit across the full time range (MS)
kepoutlier, keprange, kepdetrend, kepfilter, kepstitch