Software: KEPLERFFI
Version: 2.0.0
Contributor:
Click → here ← to download the source code (37KB)

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.

KeplerFFI serves two purposes. The first permits display of the field-of-view around a user-provided target within a specified FFI. This functionality is 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 KeplerFFI is: (1) the name of an FFI FITS file, (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 KeplerFFI is to allow 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, the standard pixel masks for bright or extended targets do not provide optimized photometry. KeplerFFI creates a custom pixel mask by allowing 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 reposition 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.

KeplerFFI 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 PyKEP tool kepextract.

To create a new mask or modify an existing 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 aperture 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 'KeplerFFI' + str(kepid) + '.txt'.

The user has the ability to modify the image display intensity scale. Optional input parameters zmin and zmax define the range of the intensity scale; zscale defines the intensity relation. Choices are linear (lin), logarithmic (log) or square root (sq). 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 choose from when displaying the FFI image. All possible choices can be found by invoking KeplerFFI with the following command: keplerFFI.py --cmap=browse

An existing custom aperture definition file can be inspected and modified with KeplerFFI. 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.

USAGE

KeplerFFI is a python script and requires the core python modules to be located in your executable path plus three add-on modules: matplotlib - a python matlab emulator, numpy - a numerical array handling package, and pyfits - a FITS file I/O module. Mac users can obtain all of the above from the fink software repository at http://www.finkproject.org. Alternatively users of Mac, Linux and PCs can obtain source code from:

       python: http://www.python.org
       numpy: http://numpy.scipy.org
  matplotlib: http://matplotlib.sourceforge.net
          pyfits: http://www.stsci.edu/resources/software_hardware/pyfits

The script has been developed and tested against python2.6, matplotlib0.99, pyfits1.3 and numpy1.3.0. Correct execution by earlier versions of these modules cannot be guaranteed. In order to determine the FFI location of specific sources and sky coordinates, KeplerFFI requires access to the MAST archive and so users must be online during execution.

PARAMETERS

--kepid       Kepler target ID from the Kepler Input Catalog
--ra             RA J2000 coordinate of target (alternative to providing the Kepler ID)
--dec          Dec J2000 coordinate of target (alternative to providing the Kepler ID)
--ffifile        Path + name of the FFI file (FITS format)
--aperfile   Path + name of an existing custom aperture definition file (text).
--zmin        Minimum level for the image intensity scale [e-/cadence]
--zmax       Maximum level for the image intensity scale [e-/cadence]
--zscale     Scaling relation for the image intensity [lin | log | sqrt]
--cmap       Name of color intensity map
--npix         Square dimension of plotted sub-image [pixels], default is npix=30

aperfile, zmin, zmax, zscale, cmap and npix are optional control parameters. ffifile is a required parameter. The location of a source can be described using either its Kepler ID or coordinates.

Typical usage examples:

KeplerFFI.py   --kepid=6522823   --ffifile=kplr2009292020429_ffi-SocCal.fits   --npix=30
KeplerFFI.py   --kepid=7659570   --ffifile=kplr2009292020429_ffi-SocCal.fits   --zmin=5e5   --zmax=1e7   --zscale=lin   --npix=40
KeplerFFI.py   --ra=19:27:31.21   --dec=41:57:02.3   --ffifile=kplr2009292020429_ffi-SocCal.fits   --npix=20   --cmap=jet
KeplerFFI.py   --kepid=8635620   --ffifile=kplr2009292020429_ffi-SocCal.fits   --aperfile=KeplerFFI8635620.txt   --npix=20   --cmap=RdYlBu

BUGS AND LIMITATIONS
KEPLERFFI 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. This tool 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.