kepffi -- Display a portion of a Full Frame Image (FFI) and define custom target apertures
kepffi ffifile kepid ra dec aperfile imin imax iscale cmap npix verbose logfile status
ffifile = string
The name of a MAST standard format Full Frame Image (FFI) FITS file containing a Kepler
channel image within each data extension.
kepid = string
The numerical Kepler identification number for a specific source, obtained from the MAST
Target Search page).
ra = string (optional)
The J2000 Right Ascension of a target in decimal degrees or sexadecimal hours (hh:mm:ss.ss).
In conjunction with dec, this parameter overrides the content of kepid.
dec = string (optional)
The J2000 Declination of a target in decimal degrees or sexadecimal degrees (dd:mm:ss.s).
In conjunction with ra, this parameter argument overrides the content of kepid.
aperfile = string (optional)
The (directory path and) name of an existing custom aperture definition file. If provided,
this aperture will be plotted over the displayed image.
imin = float (optional)
Sets the minimum intensity range for the image display. The user can select the minimum
level (in electrons per cadence) with this parameter. The default minimum intensity level
is the median of the faintest 10% of pixels in the image.
imax = float (optional)
Sets the maximum intensity range for the image display. The user can select the maximum
level (in electrons per cadence) with this parameter. The default maximum intensity level
is the median of the brightest 10% of pixels in the image.
iscale = string (optional)
The type of intensity scaling for the image display. Options: linear | logarithmic |
cmap = string (optional)
Color intensity scheme for the image display. The various options can be inspected and
compared together if cmap=browse is selected. Options: Accent | Blues | BrBG | BuGn | BuPu | Dark2 | GnBu | Greens | Greys | OrRd | Oranges | PRGn | Paired | Pastel1 | Pastel2 | PiYG | PuBu | PuBuGn | PuOr | PuRd | Purples | RdBu | RdGy | RdPu | RdYlBu | RdYlGn | Reds | Set1 | Set2 | Set3 | Spectral | YlGn | YlGnBu | YlOrBr | YlOrRd | afmhot | autumn | binary | bone | brg | bwr | cool | copper | flag | gist_earth | gist_gray | gist_heat | gist_ncar | gist_rainbow | gist_yarg | gnuplot | gnuplot2 | gray | hot | hsv | jet | ocean | pink | prism | rainbow | seismic | spectral | spring | summer | terrain | winter | browse.
npix = integer (optional)
The pixel size of the square subimage extracted from the FFI for display.
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 user.
Once per month, Kepler obtains a Full Frame Image (FFI) immediately prior
to re-orienting the spacecraft to a data downlink attitude. Each FFI, taken with a 30-minute
(= 1 long cadence) exposure time, includes data from all 96.5 Megapixels from the 42 individual
CCDs that comprise the Kepler photometer. At all other times, due to onboard storage, telemetry
and bandwidth constraints, the only pixels stored onboard Kepler and downlinked to the ground are
the target apertures of interest, a subset of 170,000 specially selected targets. The majority of
these targets are bright, photometrically quiet FGKM class stars on or close to the main sequence,
comprising 6% of the full pixel set of the photometer. Therefore, the monthly FFIs are the only
Kepler data available for the vast majority of objects in the field. During routine science
operations, FFIs are utilized only to verify target apertures and obtain full-field calibration
information ( Haas et al. 2010).
Since the Kepler mission uses the FFIs solely for engineering purposes, the project does not
spend resources on these images for scientific purposes and they are released to the community
as soon as calibration is complete.
KepFFI serves two purposes. The first permits display of the field-of-view
around a user-provided target within a specified FFI. This functionality can be used to examine
the sources surrounding a target, assess crowding, identify artifacts, and understand
the effects of the photometric aperture on the light curves produced by the Pipeline
PA and PDC modules. In this mode the
minimum input to KepFFI is: (1) the location and name of a FITS file containing an FFI; (2) either
the Kepler ID from the Kepler Input Catalog or the J2000 RA and Dec of a target; and, (3) the pixel
dimension of the square subimage to be displayed.
The second purpose for KepFFI is to permit users to construct a custom pixel
mask for sources, e.g., those that are extended or saturated. Because the standard pixel masks
assigned during target planning assume that sources are point-like, in many cases of bright or
extended targets the standard pixel masks do not provide optimized photometry. KeplerFFI creates a
custom pixel mask by permitting users to select pixels for inclusion within an aperture. Individual
pixels are chosen by a click of the middle mouse button.
FFI files can be downloaded directly from the
MAST FFI repository. An
FFI search page is also available,
which permits the user to select FFIs by date or quarter. FFI image files, described more fully
here, are ~400 Mb in size.
The terminology of Kepler seasons and Kepler quarters needs to be understood in
order to interpret the output of this tool correctly. Kepler operates over 4 seasons each year. At
the beginning of each
data from the previous season are downlinked from the spacecraft, new commands and target tables are
uploaded, and the spacecraft is rotated by 90 degrees to re-position the solar arrays. This rotation
means that every source in the Kepler field will be recorded on a different CCD detector each season
of the year. Therefore the parameters used to locate each source on the detector array are
season-dependent. There are 84 output nodes in the Kepler detector array; each output provides a
separate image in the FFI file. Each output has a numerical identifier called the channel number, which
ranges from 1 to 84. CCD channels "rotate" with the spacecraft. Consequently each Kepler target will
land on 4 different and specific channels each year. This is the significance of a Kepler season.
The seasons are identified in MAST target and archive searches by the numbers 0,1,2,3. Kepler quarters
are defined by seasons but increment continuously from the first quarter of the mission. Kepler science
quarters began at Q1, but critically pre-science commissioning data is termed Q0 and were collected at
the same spacecraft orientation as Q1. Each of the 21 CCD modules contain 4 output nodes; the term
mod.out (e.g. 12.3, 20.4 etc) is an alternative naming scheme for the channel number. The column and row
pixel values locate the centroid of a target on a particular channel. The [column,row] range for all
channels is [1:1132,1:1070]. The following table defines the relationship between season and quarter
(dates are approximate):
Q2, Q6, Q10...
Q3, Q7, Q11...
Q4, Q8, Q12...
Q0, Q1, Q5, Q9...
The skygroup is a parameter similar in nature to the channel number.
There are also 84 skygroups but these remain fixed in position on the sky. A target does not change
its skygroup after a spacecraft roll. The skygroup and channel number are identical during
KepFFI displays a user-selected portion of the designated FFI, centered
on a location specified by either a Kepler target ID or RA,DEC coordinates. If desired,
the user can create a new pixel mask or examine an existing mask. These masks can be
used either to:
Define a new photometric aperture to create custom light curves from the
target pixel images using
the PyKE tool kepextract.
To create a mask, users click on the desired pixels using the middle
mouse button and utilize the functions on the GUI. There are four function buttons
CLEAR -- Removes all pixel selections for the custom aperture so that a
user can start the pixel selection process from scratch.
DUMP -- Write out the custom target pixel definition file.
PRINT -- Save an image of the GUI window in PNG format.
CLOSE -- Close the GUI and quit the application.
If the user creates a new aperture definition file, using the "DUMP"
button, the file will be written into the current directory with the filename
'kepffi-' + str(kepid) + '.txt'
The user has the ability to modify the image display intensity scale.
Optional input parameters imin and imax define the range of the intensity
scale; iscale defines the intensity relation. Choices are linear, logarithmic
or square root. The minimum is selected by determining the median value of faintest 10%
of pixels in the subimage; the maximum from the median value of brightest 10% of pixels.
The user can select the color map to use when displaying the
FFI image. All possible choices can be found by invoking Kepffi with the argument:
An existing custom aperture definition file can be inspected and modified
with KepFFI. The definition file can be read using the optional input argument --aperfile
which requires a filename and directory path. Multiple custom apertures can be inspected
simultaneously, but not edited simultaneously. The format of the ASCII definition file
describes one target per line. Here is a specific example:
Each line is a sequence of parameters delimited by a pipe "|". The first
parameter is a place holder identifier, the second is the skygroup value. The third parameter
is required during the target planning process but can be ignored by the user. This parameter
defines any extra pixels that are desired around the photometric aperture, and is
adjusted by the project if needed for custom apertures. The fourth and fifth parameters are
the row and column (Y,X) reference pixels for the aperture mask. The sixth parameter defines
the pixel map for the aperture mask, relative to the reference pixel, expressed as a set of
row,column (Y,X) values.
Full completion upon one quarter of Kepler long cadence target using a 3.06
GHz Intel Core 2 Duo Mac running OS 10.6.4 takes a few seconds. Running times
increase by several factors if input data contains NaNs. These will be
filtered out before task execution.
BUGS AND LIMITATIONS
Please send bug reports and suggestions to email@example.com.
Initial software release (MS)
Interface with the MAST target table updated in accordance with new table columns in the MAST database (MS)
Interface with the MAST target table updated in accordance with more new table columns in the MAST database (MS)
Replaced mouse event listener with button event listener to avoid mouse incompatibilities between mac and linux (MS)
Replaced pylab.ioff() call with pylab.draw() in order to avoid issues with plot rendering in subsequent tasks (MS)
Code can now be run from the command line (TB)
more reliable plot rendering on linux operating systems (MS)
Added functionality to load existing pixel mask defintion. Bug in pixel selection fixed. Task adapted in response to format changes to the target tables at MAST (MS)
Questions concerning Kepler's science opportunities and open programs, public archive or community tools? Contact us via the