Warning: this page is no longer updated and may contain outdated information.

Please refer to the new Kepler/K2 science website at http://keplerscience.arc.nasa.gov

NASA - National Aeronautics and Space Administration Follow this link to skip to the main content + Contact NASA
Kepler Guest Observer Program

Contributed Software - KEPEXTRACT

Software: PyKE
Version: 2.0.2

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

kepextract   infile   maskfile   outfile   clobber   verbose   logfile   status

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.

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


  • 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.

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 coded black.

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.

    →   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.


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

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.

Please send bug reports and suggestions to keplergo@mail.arc.nasa.gov.


Initial software release (MS)
Added option to extract all pixels in a mask automatically (MS)
Trapped new behavior of STSCI_PYTHON 2.12 in reading multi-dimension FITS columns (MS)
Code will now make a column in the FITS file called RAW_FLUX which contains the raw counts from the target pixel file. Also fixed an issue with read/write to the same place in memory (TB).
Code can now be run from the command line (TB)
Added the 'background' option (MS)
Added the calculation of moment and simple PSF centroids from the extracted flux data (MS)
Corrected bug that prevented the maskfile='all' function from executing centroid calculations correctly (MS)


Questions concerning Kepler's science opportunities and open programs, public archive or community tools? Contact us via the email address.
FirstGov - Your First Click to the US Government
+ Freedom of Information Act
+ Budgets, Strategic Plans and Accountability Reports
+ The President's Management Agenda
+ NASA Privacy Statement, Disclaimer,
and Accessibility Certification

+ Inspector General Hotline
+ Equal Employment Opportunity Data Posted Pursuant
to the No Fear Act

+ Information-Dissemination Priorities and Inventories
NASA - National Aeronautics and Space Administration
Editor: Martin Still
NASA Official: Jessie Dotson
Last Updated: Jan 11, 2013
+ Contact NASA