kepprfphot -- Fit a PSF model to time series observations within a Target Pixel File
kepprfphot infile plotfile rownum columns rows fluxes border background focus prfdir xtol ftol qualflags plot clobber verbose logfile status
infile = string
The name of a MAST standard format FITS file containing Kepler Target Pixel data within the first data extension.
outroot = string
kepprfphot creates two types of output file containing fit results and diagnostics. outroot.png contains a time series plot of fit parameters, residuals and χ2. outroot.fits contains a table of the same properties, consistent with Kepler archive light curve files. The FITS column PSF_FLUX contains the flux time-series in units of e-/s derived by integrating under the best-fit PRF model. PSF_BKG provides the best-fit background (if calculated) averaged over all mask pixels in units of e-/s/pixel. PSF_CENTR1 provides the best-fit PSF centroid position in the CCD column direction, in CCD pixel units. Similarly, PSF_CENTR2 provides the best-fit PSF centroid position in the CCD row direction, in CCD pixel units. If calculated, PSF_FOCUS1 and PSF_FOCUS2 provide scale factors in the column and row dimensions by which the CCD pixel scale is adjusted to approximate focus variation. PSF_ROTATION provides the angle by which the scaled PSF model was rotated on the focal plane in order to yield a best fit. The table column PSF_RESIDUAL provides the sum of all mask pixels after the best-fit model has been subtracted from the data. PSF_CHI2 delivers the best-fit χ2 statistic for each observation.
columns = float
A starting guess for the CCD column position(s) of the source(s) that are to be fit. The model is unlikely to converge if the guess is too far away from the correct location. A rule of thumb is to provide a guess within 1 CCD pixel of the true position. If more than one source is being modeled then the column positions of each are separated by a comma. The same number of sources in the columns, rows and fluxes field is a requirement of this task.
rows = float
A starting guess for the CCD row position(s) of the source(s) that are to be fit. The model is unlikely to converge if the guess is too far away from the correct location. A rule of thumb is to provide a guess within 1 CCD pixel of the true position. If more than one source is being modeled then the row positions of each are separated by a comma. The same number of sources in the columns, rows and fluxes field is a requirement of this task.
fluxes = float
A starting guess for the flux(es) of the source(s) that are to be fit. Fit convergence is not particularly reliant on the accuracy of these guesses, but the fit will converge faster the more accurate the guess. If more than one source is being modeled then the row positions of each are separated by a comma. The same number of sources in the columns, rows and fluxes field is a requirement of this task.
border = integer (optional)
If a background is included in the fit then it is modeled as a two-dimensional polynomial. This parameter is the polynomial order. A zero-order polynomial is generally recommended.
background = boolean (optional)
Whether to include a background component in the model. If 'yes' the background will be represented by a two-dimensional polynomial of order border. This functionality is somewhat experimental, with one eye upon potential background gradients across large masks or on those detectors more prone to pattern noise. Generally it is recommended to set background = no.
focus = boolean (optional)
Whether to include pixel scale and focus rotation with the fit parameters of the model. This is also an experimental function. This approach does not attempt to deal with inter- or intra-pixel variations. The recommended use is currently to set focus = no.
prfdir = string
The full or relative directory path to a folder containing the Kepler PSF calibration. Calibration files can be downloaded from the Kepler focal plane characteristics page at the MAST.
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.
xtol = float
The dimensionless, relative model parameter convergence criterion for the fit algorithm.
ftol = float
The dimensionless, relative model residual convergence criterion for the fit algorithm.
qualflags = boolean
If qualflags = no, archived observations flagged with any quality issue will not be fit.
plot = boolean (optional)
Plot fit results to the screen?
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
kepprfphot fits a PSF model, combined with spacecraft jitter and pixel scale variations (the Pixel Response Function; PRF) to a series of observations using Kepler target pixels.
The Kepler PSF calibration is based upon a sequence of dithered commissioning observations performed before the exoplanet survey began. Dithering enables sub-pixel detail of the undersampled PSF to be characterized Anderson and King (2000). Kepler pixel sizes are 3.98x3.98 arcsec and the 95 percent encircled energy is < 7 pixels but varies across the detector. Target masks of 21x21 pixels were selected to capture the majority of the PSF and spacecraft jitter for 19,189 Kp = 11-12 stars over 121 observations. Details of the observations and derivation of the Kepler PSF are provided in Bryson et al. (2010). Unlike the polynomial representations of the PSF described in Bryson et al. (2010) and employed by the pipeline, the publicly archived PSF calibration is stored as a lookup table. It provides the normalized value of the PSF, typically within a 11x11 pixel grid around the target position. Each pixel within the grid is represented by a 50x50 array representing the value of a pixel for different sub-pixel locations of the target. The sup-pixel lookup nature of the calibration product naturally provides for the characterization of photon sensitivity and diffusion within individual pixels -- the intra-pixel variability; (Lauer 1999a, Lauer 1999b). An assumption going forward is that all pixels have identical intra-pixel variability within the detector locale of the target. Since the PSF varies across the field-of-view, five independent lookup tables are provided for each of the 84 detector channels. One at the center of the channel and one in each corner.
The original purposes of the calibration were to enable calculations of the size, shape and location of pixel mask definitions for upload to the spacecraft and, subsequent to observations, calculate centroids for a small number of reference targets in order to measure absolute astrometry and pixel scale. All PSF tables are precise statistically, but a number of systematic features limit their accuracy. i) The stars comprising the PSF calibration are binned coarsely. The PSF model is broadened artificially by combining stars separated by hundreds of detector pixels, and interpolation is required to a target position on the CCD between the sparse lookup table locations. ii) The thermal state of the spacecraft and it's impact upon image focus varies on multiple timescales e.g. with the spacecraft orbit and after Earth-point operations (Christiansen et al. 2013). PSF dithering observations were taken during a relatively short fraction of the spacecraft orbit, close to thermal equilibrium, therefore the PSF calibration has no ability to match the constantly varying \kepler focus. iii) No attempt has been made to investigate the color-dependency on the PSF. Furthermore, applying the calibration to survey data requires assumptions that spacecraft jitter on timescales shorter than an exposure remains constant over time and that each source confused spatially with the target star is accounted for.
The PSF model used in the fit is linearly interpolated from the 5 reference models associated with the CCD channel, according to their positions. The model employed can contain any number of sources, with three independent parameters for each. The free parameters are target flux, CCD pixel column location, and CCD pixel row location. A time-varying background component was calculated within the pipeline from the spatial interpolation of a background reference pixel grid across the detector channel and subtracted from the target pixel data before archiving. In most cases it can be assumed that a secondary direct background subtraction from the target pixels is not required, however the capability is provided in the form or a two-dimension background polynomial that can be added to the source fits. Model fluxes for each pixel in the target mask are extracted directly from the 50x50 sub-sampled PSF calibration. For target pixel positions falling in between the subpixels of the calibration product, fluxes are interpolated by 2-dimensional cubic splines. The residual between data and model is minimized by adjusting fit parameters according to the Powell (1964) conjugate direction method. A fit is considered converged once the xtol and ftol criteria are met.
- kepprfphot infile=kplr012557548-2012004120508_lpd-targ.fits outroot=kplr012557548-2012004120508_psf columns=95 rows=1020 fluxes=1.0 border=0 background=n focus=n prfdir=/Volumes/data/Kepler/PRF ranges=0,0 xtol=1e-07 ftol=1e-07 qualflags=n plot=y clobber=y verbose=y logfile=kepprfphot.log
Completion upon one observation of target pixels using a 2.66
GHz Intel Core 2 i7 Mac running OS 10.9, takes 10 minutes to fit a full quarter of pixel observations containing a single source and 20 pixels. Run times increase with larger numbers of sources, larger numbers of pixels and smaller tolerance criteria.
BUGS AND LIMITATIONS
The Kepler PyRAF package is made available to the community through the Kepler Science Center at
http://keplerscience.arc.nasa.gov/PyKE.shtml. Please send bug reports and suggestions firstname.lastname@example.org.
Initial software release (MS)