Software: PyKE
Version: 2.0.1
Contributor:

NAME
kepextract -- create a light curve from a target pixel file by summing user-selected pixels

USAGE
kepextract   infile   maskfile   outfile   clobber   verbose   logfile   status

PARAMETERS
infile = string
Filename for the target pixel file.

maskfile = string
Filename describing the desired photometric aperture. This file should contain a text string as defined below.

outfile = string
Filename for the output light curve.

clobber = boolean (optional)
Option to 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)
Option for verbose mode, in which informative messages and warnings to the shell and a 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.
 

DESCRIPTION
kepextract calculates simple aperture photometry, from a target pixel file, for a user-supplied set of pixels. The Kepler pipeline sums a specific set of pixels to produce the standard light curves delivered to users. Termed the optimal aperture, the default pixel set is designed to maximize the signal-to-noise ratio of the resulting light curve, optimizing for transit detection. This tool provides users with a straightforward capability to alter the summed pixel set. Applications include:

• Use of all pixels in the aperture
• The pipeline does not produce a light curve for sources observed with custom or dedicated pixel masks. The user can create a light curve for these sources using kepextract.
• Construction of pixel light curves, in which the time series for a single pixel can be examined.
• Light curves for extended sources which may be poorly sampled by the optimal aperture.

Building a Custom Light Curve

Users execute three steps to produce custom light curves:

1. Inspect the pixel mask and the data.
2. Choose a new photometric aperture and record the list of pixels in a text file.
3. Execute kepextract, which creates and save the light curve.

Data Inspection:   The user should inspect the pixel images to decide which pixels are to be summed in the aperture. A number of FITS file inspection tools are available for the user. FV, developed by NASA's High Energy Astrophysics Science and Archive Research Center, is the visualization tool used here. With FV users can examine the source image for any cadence, and also the pixel mask used by the pipeline for optimal apertures.

Pixel Selection:   Users can select an alternate pixel set by inspection directly from the mask image using either the tool kepmask or kepffi. Alternatively, you can manually write a an ASCII mask definition file containing one line:

KIC ID | skygroup || Y | X | y1,x1;y2,x2;y3,x3;yn,xn

where:

• KIC ID = an integer identifier for the target taken from the Kepler Input Catalog. This value is included as part of the filename for target pixel and light curve files. kepextract does not further use this value, however kepffi does.

• Skygroup = an integer from 1 to 84 describing the location where the target falls within the Kepler FOV. Skygroup values are given with the primary header keyword SKYGROUP. This field is present for compatibility with other target management software and is not further used here.

• The input elements in this string must be delineated by a pipe "|". Note the double pipe after the skygroup element; this syntax is included for consistency with other target management software (additional description of the aperture properties during target definition).

• Y = the row reference pixel location of the mask. Note that this is a row number in the FFI image, not the row number of the much smaller mask. If the reference row of the mask is the 367th row of the FFI image, then Y = 367, not e.g. 1. A suitable value for Y can also be obtained from the CRVAL2P keyword in the APERTURE extension of the target pixel file.

• X = the column reference pixel location of the mask. Note that this is a column number in the FFI image, not the column number of the much smaller mask. If the reference column of the mask is the 202nd column of the FFI image, then X = 202, not e.g. 1. A suitable value for X can also be obtained from the CRVAL1P keyword in the APERTURE extension of the target pixel file.

• y1,x1; ... yn,xn = the new photometric aperture, given as a set of relative y,x (row, column) coordinate pairs, separated by a semicolon. These coordinates are pixel offsets from the reference pixel.

• CAUTION: If using FV, the pixel mask may be displayed using relative pixels index values where the lower-left pixel is indexed as (1,1) - a 1-based system. Python is zero-based, in which the lower left element of an image (array) is indexed as (0,0). Users must be careful in assigning pixel values when using a 1-based display - kepextract is a Python script. IF you are selecting pixels using a 1-based image display, e.g., FV, you can:
  1. Display the pixel mask in physical coordinates by clicking on the "Edit" tab in the top toolbar of the pixel mask display, select "WCS", then select "WCS p" in the drop-down menu. The examples below are displayed using physical coordinates.

  2. Using this display, the user simply counts pixels incrementing rows (y) upward, and columns rightward (x) to assign y,x coordinate pairs.

• The examples below were generated using FV version 5.3.

Two legal examples of the syntax for a maskfile are given below. The y,x coordinate pairs correspond to the pixels indicated in the user-selected aperture displayed on the right above. The second example shows that the KIC ID and skygroup fields can be left blank - kepextract will execute nominally in this case.

    →   7523115|61||163|289|2,3;3,3;4,3;3,2;3,4

    →   |||163|289|2,3;3,3;4,3;3,2;3,4

A maskfile can also be created using the kepffi script. This program displays the source within the larger sky field around that source, using a full-frame image. The user then selects pixels to be included in an aperture using the mouse to click on each desired pixel. You can also inspect a previously-defined aperture by overlaying that aperture on the source. If you use kepffi, please note:

• Use a full frame image obtained during the same season as the target pixel data. KeplerFFI uses the object location as defined for that season, obtained from MAST, as the Y,X reference pixels recorded in the maskfile. These values can be change +/- a few pixels between quarters.
• kepextract ignores the text written by KeplerFFI between the double pipe in the maskfile example above. This text is needed for defining the pixel mask for target management, but not for photometry of already received pixel masks.

Extract:   Create a new light curve by executing kepextract, providing the required filenames: the file containing the target pixel data, the file into which you recorded the alternate pixel set, and a name for the output light curve file. kepextract constructs and saves a FITS-formatted file containing a new light curve:

• Output file contains a header, binary table extension, and aperture mask image extension.
• Copies timestamp, barycentric correction, cadence number, and data quality flags columns, one value per cadence.
• Sums the selected pixels with unit weight. Flux values in each pixel are already background-subtracted; no correction is needed here.
• Derives a flux error for each cadence by summing in quadrature the individual errors for the selected pixels, which include the uncertainty due to the background.
• Determines the background value and associated errors for each cadence in the same manner as the summed flux.

Users should note the following:

• The contents of the output light curve file conforms to a newly adopted format, not yet available at MAST. This new content is expected be implemented for Q8 data. In particular, the pixel mask used to create the light curve is included as an image extension in the new light curve file. Users can directly examine this mask, using FV.
• A maskfile is not required for kepextract to execute. If maskfile=none, the program will use the optimal aperture encoded in the aperture image extension of the input file to construct a light curve.

There are two special variants of the maskfile input. Instead of defining a specific new pixel mask, if maskfile='aperture' kepextract will construct a light curve from all pixels in the photometric aperture used by the SOC pipeline. Alternatively, if maskfile='all', kepextract will construct a light curve from all pixels within the target pixel file.

EXAMPLE

• kepextract infile=kplr003096278-2010076075105_lpd-targ.fits   maskfile=altmask1.txt   outfile=kic3096278_altmask1.fits

TIME REQUIREMENTS
Execution of this program for 1 quarter of long cadence data using a 3.06 GHz Intel Core 2 Duo Mac running OS 10.6.4 takes a few seconds.

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://keplergo.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 keplergo@mail.arc.nasa.gov.

HISTORY