kepextract -- create a light curve from a target pixel file by summing user-selected pixels
kepextract infile maskfile outfile clobber verbose
PARAMETERS infile = string
Filename for the target pixel file.
maskfile = string
This string can be one of three options: 1) 'ALL' tells the task to calculate principal components from all pixels within the pixel mask stored in the input file. 2) 'APER' tells the task to calculate principal components from only the pixels within the photometric aperture stored in the input file (e.g. only those pixels summed by the Kepler pipeline to produce the light curve archived at MAST 3) A filename describing the desired photometric aperture. Such a file can be constructed using the kepmask or kepffi tools, or can be created manually using the format described in the documentation for those tools.
outfile = string
Filename for the output light curve. This product will be written to the same FITS format as archived light curves.
background = boolean
Option to subtract an estimate of the background. Background is calculated by identifying the median pixel value for each exposure. This method requires an adequate number of pixels in within the target mask that contain background and negligible source flux. Note that background has already been subtracted from calibrated Kepler Target Pixel Files, but not early campaign data from the K2 mission.
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
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:
Inspect the pixel mask and the data.
Choose a new photometric aperture and record the list of pixels in a text file.
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
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:
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.
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.
Example of an optimal aperture, selected by the
pipeline, whose pixels are coded in white, defined within the observed pixel mask
indicated by the light blue pixels. Pixels for which no data was collected are
Example of a user-selected alternate aperture.
Coding is the same as in the image to the left. The pixel masks are displayed using
the visualization tool FV, indexed in physical pixel units.
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.
A maskfile can also be created using the
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
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
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.