keppca -- Perform principal component analysis upon a target pixel file
keppca infile maskfile outfile components plotpca
nreps clobber verbose logfile
infile = string
The name of a standard format FITS file containing Kepler or K2 target pixels
within the first data extension.
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 (note that no such light curves are currently being created for the K2 mission) 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. Note that if an aperture provided is not stricly rectangular, tkeppca will increase the size of the aperure so that it defines the smallest possible rectangle that contains all of the specified pixels.
outfile = string
Filename for the output light curves and principal components. This product will be written to the same FITS format as archived light curves. Aperture photometry will be stored in the SAP_FLUX column of the first FITS extension called LIGHTCURVE. A version of this light curve with principal components subtracted is stored in column PCA_FLUX and a normalized version is stored in PCA_FLUX_NRM. The individual principal components are stored within a new FITS extension called PRINCIPAL_COMPONENTS.
components = string
A list of the principal components to subtract from the aperture light curve. The strings '1 2 3 4 5', 1,'2,3,4,5' and '1,2,3-5' yield the same result.
plotpca = boolean
If plotpca = yes, keppca will produce plots containing individual principal components, correlation maps and light curves, both aperture and PCA-corrected versions. The will be stored as hardcopies in PNG format. PNG filenames are derivative of the outfile name.
nmaps = integer
The number of correlation maps and principal components to plot as output. This can be any positive integer up to the number of pixels within the mask, although note that many hundreds of plots will likely become prohibitive and is unlikely to be informative.
clobber = boolean (optional)
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)
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
keppca provides a method to mitigate for motion-derived systematic artifacts via Principle Component Analysis (PCA). This method was demonstrated on Kepler light curves by Harrison et al. (2012). It provides an alternative to cotrending data using basis vectors (kepcotrend) and correlating aperture photometry struture with time-series centroid measurements (kepsff). PCA will perhaps become a more widespread tool in the K2 era where the magnitde of target motion across the detector over a Kepler quarter is experienced by a K2 target over just 6-hours during its regular sequence of thruster firings that counteract boresight roll motion. Pixel-level PCA employs only those pixels collected around a specific target and separates photometric trends common to all pixels from trends localized to individual targets or pixels in a series of principal component curves.
The user has the option to choose the specific set of pixels to sample in this analysis. Principal components are plotted by the tool and written out to an output FITS file in an output extension called PRINCIPAL_COMPONENTS. The extension contains a 2D table with one row per timestamp recorded in the input file and one column for every principal component. Summing all principal components together will reconstruct a normalized version of the summed pixel within the chosen aperture. The user also has the choice of which principal components to optimally-subtract from the aperture-derived light curve in order to remove motion systematics from the time-series data. The aperture light curve and the corrected light curve are written to the LIGHTCURVE extension of the output file. The first populates the SAP_FLUX data column and the second is written to a column called PCA_FLUX. This output file can be used as input for other PyKE tasks and can be e.g. inspected using kepdraw.
First-time users of keppca will find a warning message indicating that the task will not complete without installing an external module called MDP. This is not a great chore if you follow the install insructions provided, but care should be taken to install MDP using the same version of python on your system that you call keppca with. If in doubt, install MDP will all the versions of python that you see after typing 'where python' in your shell.
- Calculate the principal components from a subset of pixels collected around a Kepler target and construct a motion-mitigated light curve by subtracting the first five components from aperture photometry. Plot the first 10 correlation maps and principal components (see Figures 1 and 2):
- keppca infile=ktwo202073445-2014147084813_lpd-targ.fits maskfile=all outfile=ktwo202073445-2014147084813_pca.fits components=1-5 plotpca=yes --nmaps=10 clobber=yes verbose=yes
Full completion upon one K2 long cadence target pixel file, using a 3.06
GHz Intel Core 2 Duo Mac running OS 10.7.5, takes 10 seconds.
BUGS AND LIMITATIONS
Flux errors in the input target pixel file are not currently propagated through the calculation.
The Kepler PyRAF package is privately-developed software made available to
the community through the contributed software page of the GO program at
http://keplerscience.arc.nasa.gov/ContributedSoftware.shtml. It 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 firstname.lastname@example.org.
Initial software release (MS)
For FITS compliance, the maximum number of principal components stored in the output file is 999 (MS)
Upgraded for the K2 mission. Subtracts optimized versions of the principal components from aperture-derived data. Provides correlation maps for each component. (MS, JC)