Software: PyKE
Version: 2.0.1
Contributor:

NAME
kepffi -- Display a portion of a Full Frame Image (FFI) and define custom target apertures

USAGE
kepffi ffifile kepid ra dec aperfile imin imax iscale cmap npix verbose logfile status

PARAMETERS
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 | squareroot.

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.

DESCRIPTION

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 season 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):
 

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 season 2.

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:

• Propose new observations via the GO cycle or the discretionary time program.
• 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 provided:

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: cmap=browse.

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:

NEW|79|{19:39:48.43,+39:27:23.7},TAD_NO_HALO,TAD_NO_UNDERSHOOT_COLUMN|859|1044|-1,-3;0,-3;1,-3;-1,-2;0,-2;1,-2;2,-2;
-2,-1;-1,-1;0,-1;1,-1;2,-1;3,-1;-2,0;-1,0;0,0;1,0;2,0;3,0;-1,1;0,1;1,1;2,1;-1,2;0,2

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.

EXAMPLES

1. Plot an FFI around a specific Kepler target ID:
   • kepffi   kepid=6522823   ffifile=kplr2009292020429_ffi-SocCal.fits   npix=30
   
   
2. Plot an FFI with a user-defined intensity scale:
   • kepffi   kepid=7659570   ffifile=kplr2009292020429_ffi-SocCal.fits   imin=5e5   imax=1e7   iscale=lin   npix=40
   
   
3. Plot an FFI around a target without a Kepler target ID, choose an alternative color map:
   • kepffi   ra=19:27:31.21   dec=41:57:02.3   ffifile=kplr2009292020429_ffi-SocCal.fits   npix=20   cmap=RdYlBu
   
   

TIME REQUIREMENTS
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
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 or NASA. Bugs and errors are not the responsibility of the Kepler Team. Please send bug reports and suggestions to keplergo@mail.arc.nasa.gov.

HISTORY