kepflatten: remove low frequency variability from time-series, preserve transits and flares¶
kepflatten(infile, outfile=None, datacol='PDCSAP_FLUX', errcol='PDCSAP_FLUX_ERR', nsig=3.0, stepsize=0.5, winsize=5.0, npoly=3, niter=1, ranges='0, 0', plot=False, overwrite=False, verbose=False, logfile='kepflatten.log')¶
kepflatten – Remove low frequency variability from time-series, preserve transits and flares
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
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.
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 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-\(\sigma\) error).
datacol : str
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 : str
The column name containing photometric 1-\(\sigma\) 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 standard deviation. 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 : str
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. 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 series.
plot : bool
Plot the data, fit, outliers and result?
overwrite : bool
Overwrite the output file?
verbose : bool
Print informative messages and warnings to the shell and logfile?
logfile : str
Name of the logfile containing error and warning messages.
$ kepflatten kplr012557548-2011177032512_llc.fits --nsig 3 --stepsize 1.0 --winsize 3.0 --npoly 3 --niter 10 --plot --overwrite --verbose