KeplerTargetPixelFile¶

class lightkurve.targetpixelfile.KeplerTargetPixelFile(path, quality_bitmask='default', **kwargs)¶

Bases: lightkurve.targetpixelfile.TargetPixelFile

Class to read and interact with the pixel data products (“Target Pixel Files”) created by NASA’s Kepler pipeline.

This class offers a user-friendly way to open a Kepler Target Pixel File (TPF), access its meta data, visualize its contents, extract light curves with custom aperture masks, estimate centroid positions, and more.

Please consult the TargetPixelFile tutorial in the online documentation for examples on using this class.

Parameters

pathstr or HDUList

Path to a Kepler Target Pixel file. Alternatively, you can pass a HDUList object, which is the AstroPy object returned by the astropy.io.fits.open function.

quality_bitmask“none”, “default”, “hard”, “hardest”, or int

Bitmask that should be used to ignore bad-quality cadences. If a string is passed, it has the following meaning:

“none”: no cadences will be ignored (equivalent to quality_bitmask=0).

“default”: cadences with severe quality issues will be ignored (equivalent to quality_bitmask=1130799).

“hard”: more conservative choice of flags to ignore (equivalent to quality_bitmask=1664431). This is known to remove good data.

“hardest”: remove all cadences that have one or more flags raised (equivalent to quality_bitmask=2096639). This mask is not recommended because some quality flags can safely be ignored.

If an integer is passed, it will be used as a bitmask, i.e. it will have the effect of removing cadences where (tpf.hdu[1].data['QUALITY'] & quality_bitmask) > 0. See the KeplerQualityFlags class for details on the bitmasks.

**kwargsdict

Optional keyword arguments passed on to astropy.io.fits.open.

References

1: Kepler: A Search for Terrestrial Planets. Kepler Archive Manual. http://archive.stsci.edu/kepler/manuals/archive_manual.pdf

Attributes Summary

`astropy_time`	Returns an AstroPy Time object for all good-quality cadences.
`cadenceno`	Return the cadence number for all good-quality cadences.
`campaign`	K2 Campaign number.
`channel`	Kepler CCD channel number.
`column`	CCD pixel column number (‘1CRV5P’ header keyword).
`dec`	Declination of target (‘DEC_OBJ’ header keyword).
`flux`	Returns the flux for all good-quality cadences.
`flux_bkg`	Returns the background flux for all good-quality cadences.
`flux_bkg_err`
`flux_err`	Returns the flux uncertainty for all good-quality cadences.
`hdu`
`header`	DEPRECATED.
`mission`	‘Kepler’ or ‘K2’.
`module`	Kepler CCD module number.
`nan_time_mask`	Returns a boolean mask flagging cadences whose time is `nan`.
`obsmode`	‘short cadence’ or ‘long cadence’.
`output`	Kepler CCD module output number.
`pipeline_mask`	Returns the optimal aperture mask used by the pipeline.
`pos_corr1`	Returns the column position correction.
`pos_corr2`	Returns the row position correction.
`quality`	Returns the quality flag integer of every good cadence.
`quarter`	Kepler quarter number.
`ra`	Right Ascension of target (‘RA_OBJ’ header keyword).
`row`	CCD pixel row number (‘2CRV5P’ header keyword).
`shape`	Return the cube dimension shape.
`time`	Returns the time for all good-quality cadences.
`wcs`	Returns an `astropy.wcs.WCS` object with the World Coordinate System solution for the target pixel file.

Methods Summary

`create_threshold_mask`(self[, threshold, …])	Returns an aperture mask creating using the thresholding method.
`cutout`(self[, center, size])	Cut a rectangle out of the Target Pixel File.
`estimate_centroids`(self[, aperture_mask, method])	Returns the flux center of an object inside `aperture_mask`.
`extract_aperture_photometry`(self[, …])	Returns a LightCurve obtained using aperture photometry.
`extract_prf_photometry`(self[, cadences, …])	Returns the results of PRF photometry applied to the pixel file.
`from_fits_images`(images, position[, size, …])	Creates a new Target Pixel File from a set of images.
`get_bkg_lightcurve`(self[, aperture_mask])
`get_coordinates`(self[, cadence])	Returns two 3D arrays of RA and Dec values in decimal degrees.
`get_header`(self[, ext])	Returns the metadata embedded in the file.
`get_keyword`(self, keyword[, hdu, default])	Returns a header keyword value.
`get_model`(self[, star_priors])	Returns a default `TPFModel` object for PRF fitting.
`get_prf_model`(self)	Returns an object of KeplerPRF initialized using the necessary metadata in the tpf object.
`interact`(self[, notebook_url, max_cadences, …])	Display an interactive Jupyter Notebook widget to inspect the pixel data.
`interact_sky`(self[, notebook_url, …])	Display a Jupyter Notebook widget showing Gaia DR2 positions on top of the pixels.
`plot`(self[, ax, frame, cadenceno, bkg, …])	Plot the pixel data for a single frame (i.e.
`prf_lightcurve`(self, **kwargs)
`query_solar_system_objects`(self[, …])	Returns a list of asteroids or comets which affected the target pixel files.
`show_properties`(self)	Prints a description of all non-callable attributes.
`to_corrector`(self[, method])	Returns a `Corrector` instance to remove systematics.
`to_fits`(self[, output_fn, overwrite])	Writes the TPF to a FITS file on disk.
`to_lightcurve`(self[, method])	Performs photometry on the pixel data and returns a LightCurve object.

Attributes Documentation

astropy_time¶: Returns an AstroPy Time object for all good-quality cadences.

cadenceno¶: Return the cadence number for all good-quality cadences.

campaign¶: K2 Campaign number. (‘CAMPAIGN’ header keyword)

channel¶: Kepler CCD channel number. (‘CHANNEL’ header keyword)

column¶: CCD pixel column number (‘1CRV5P’ header keyword).

dec¶: Declination of target (‘DEC_OBJ’ header keyword).

flux¶: Returns the flux for all good-quality cadences.

flux_bkg¶: Returns the background flux for all good-quality cadences.

flux_bkg_err¶

flux_err¶: Returns the flux uncertainty for all good-quality cadences.

hdu¶

header¶: DEPRECATED. Please use get_header() instead.

mission¶: ‘Kepler’ or ‘K2’. (‘MISSION’ header keyword)

module¶: Kepler CCD module number. (‘MODULE’ header keyword)

nan_time_mask¶: Returns a boolean mask flagging cadences whose time is nan.

obsmode¶: ‘short cadence’ or ‘long cadence’. (‘OBSMODE’ header keyword)

output¶: Kepler CCD module output number. (‘OUTPUT’ header keyword)

pipeline_mask¶: Returns the optimal aperture mask used by the pipeline.

pos_corr1¶: Returns the column position correction.

pos_corr2¶: Returns the row position correction.

quality¶: Returns the quality flag integer of every good cadence.

quarter¶: Kepler quarter number. (‘QUARTER’ header keyword)

ra¶: Right Ascension of target (‘RA_OBJ’ header keyword).

row¶: CCD pixel row number (‘2CRV5P’ header keyword).

shape¶: Return the cube dimension shape.

time¶: Returns the time for all good-quality cadences.

wcs¶

Returns an astropy.wcs.WCS object with the World Coordinate System solution for the target pixel file.

Returns

wastropy.wcs.WCS object: WCS solution

Methods Documentation

create_threshold_mask(self, threshold=3, reference_pixel='center')¶

Returns an aperture mask creating using the thresholding method.

This method will identify the pixels in the TargetPixelFile which show a median flux that is brighter than threshold times the standard deviation above the overall median. The standard deviation is estimated in a robust way by multiplying the Median Absolute Deviation (MAD) with 1.4826.

If the thresholding method yields multiple contiguous regions, then only the region closest to the (col, row) coordinate specified by reference_pixel is returned. For exmaple, reference_pixel=(0, 0) will pick the region closest to the bottom left corner. By default, the region closest to the center of the mask will be returned. If reference_pixel=None then all regions will be returned.

Parameters

thresholdfloat: A value for the number of sigma by which a pixel needs to be brighter than the median flux to be included in the aperture mask.
reference_pixel: (int, int) tuple, ‘center’, or None: (col, row) pixel coordinate closest to the desired region. For example, use reference_pixel=(0,0) to select the region closest to the bottom left corner of the target pixel file. If ‘center’ (default) then the region closest to the center pixel will be selected. If None then all regions will be selected.

Returns

aperture_maskndarray: 2D boolean numpy array containing True for pixels above the threshold.

cutout(self, center=None, size=5)¶

Cut a rectangle out of the Target Pixel File.

This methods returns a new TargetPixelFile object containing a rectangle of a given size cut out around a given center.

Parameters

center(int, int) tuple or astropy.SkyCoord: Center of the cutout. If an (int, int) tuple is passed, it will be interpreted as the (column, row) coordinates relative to the bottom-left corner of the TPF. If an astropy.SkyCoord is passed then the sky coordinate will be used instead. If None (default) then the center of the TPF will be used.
sizeint or (int, int) tuple: Number of pixels to cut out. If a single integer is passed then a square of that size will be cut. If a tuple is passed then a rectangle with dimensions (column_size, row_size) will be cut.

Returns

tpflightkurve.TargetPixelFile object: New and smaller Target Pixel File object containing only the data cut out.

estimate_centroids(self, aperture_mask='pipeline', method='moments')¶

Returns the flux center of an object inside aperture_mask.

Telescopes tend to smear out the light from a point-like star over multiple pixels. For this reason, it is common to estimate the position of a star by computing the geometric center of its image. Astronomers refer to this position as the centroid of the object, i.e. the term centroid is often used as a generic synonym to refer to the measured position of an object in a telescope exposure.

This function provides two methods to estimate the position of a star:

method='moments' will compute the “center of mass” of the light based on the 2D image moments of the pixels inside aperture_mask.
method='quadratic' will fit a two-dimensional, second-order polynomial to the 3x3 patch of pixels centered on the brightest pixel inside the aperture_mask, and return the peak of that polynomial. Following Vakili & Hogg 2016 (ArXiv:1610.05873, Section 3.2).

Parameters

aperture_mask‘pipeline’, ‘threshold’, ‘all’, or array-like: Which pixels contain the object to be measured, i.e. which pixels should be used in the estimation? If None or ‘all’ are passed, all pixels in the pixel file will be used. If ‘pipeline’ is passed, the mask suggested by the official pipeline will be used. If ‘threshold’ is passed, all pixels brighter than 3-sigma above the median flux will be used. Alternatively, users can pass a boolean array describing the aperture mask such that True means that the pixel will be used.
method‘moments’ or ‘quadratic’: Defines which method to use to estimate the centroids. ‘moments’ computes the centroid based on the sample moments of the data. ‘quadratic’ fits a 2D polynomial to the data and returns the coordinate of the peak of that polynomial.

Returns

columns, rowsarray, array: Arrays containing the column and row positions for the centroid for each cadence, or NaN for cadences where the estimation failed.

extract_aperture_photometry(self, aperture_mask='pipeline', centroid_method='moments')¶

Returns a LightCurve obtained using aperture photometry.

Parameters

aperture_maskarray-like, ‘pipeline’, ‘threshold’ or ‘all’: A boolean array describing the aperture such that True means that the pixel will be used. If None or ‘all’ are passed, all pixels will be used. If ‘pipeline’ is passed, the mask suggested by the official pipeline will be returned. If ‘threshold’ is passed, all pixels brighter than 3-sigma above the median flux will be used.
centroid_methodstr, ‘moments’ or ‘quadratic’: For the details on this arguments, please refer to the documentation for TargetPixelFile.estimate_centroids.

Returns

lcKeplerLightCurve object: Array containing the summed flux within the aperture for each cadence.

extract_prf_photometry(self, cadences=None, parallel=True, **kwargs)¶

Returns the results of PRF photometry applied to the pixel file.

Parameters

cadenceslist of int: Cadences to fit. If None (default) then all cadences will be fit.
parallelbool: If True, fitting cadences will be distributed across multiple cores using Python’s multiprocessing module.
**kwargsdict: Keywords to be passed to tpf.get_model() to create the TPFModel object that will be fit.

Returns

resultsPRFPhotometry object: Object that provides access to PRF-fitting photometry results and various diagnostics.

static from_fits_images(images, position, size=11, 11, extension=1, target_id='unnamed-target', hdu0_keywords=None, **kwargs)¶

Creates a new Target Pixel File from a set of images.

This method is intended to make it easy to cut out targets from Kepler/K2 “superstamp” regions or TESS FFI images.

Parameters

imageslist of str, or list of fits.ImageHDU objects: Sorted list of FITS filename paths or ImageHDU objects to get the data from.
positionastropy.SkyCoord: Position around which to cut out pixels.
size(int, int): Dimensions (cols, rows) to cut out around position.
extensionint or str: If images is a list of filenames, provide the extension number or name to use. Default: 0.
target_idint or str: Unique identifier of the target to be recorded in the TPF.
hdu0_keywordsdict: Additional keywords to add to the first header file.
**kwargsdict: Extra arguments to be passed to the KeplerTargetPixelFile constructor.

Returns

tpfKeplerTargetPixelFile: A new Target Pixel File assembled from the images.

get_bkg_lightcurve(self, aperture_mask=None)¶

get_coordinates(self, cadence='all')¶

Returns two 3D arrays of RA and Dec values in decimal degrees.

If cadence number is given, returns 2D arrays for that cadence. If cadence is ‘all’ returns one RA, Dec value for each pixel in every cadence. Uses the WCS solution and the POS_CORR data from TPF header.

Parameters

cadence‘all’ or int: Which cadences to return the RA Dec coordinates for.

Returns

ranumpy array, same shape as tpf.flux[cadence]: Array containing RA values for every pixel, for every cadence.
decnumpy array, same shape as tpf.flux[cadence]: Array containing Dec values for every pixel, for every cadence.

get_header(self, ext=0)¶

Returns the metadata embedded in the file.

Target Pixel Files contain embedded metadata headers spread across three different FITS extensions:

The “PRIMARY” extension (ext=0) provides a metadata header providing details on the target and its CCD position.
The “PIXELS” extension (ext=1) provides details on the data column and their coordinate system (WCS).
The “APERTURE” extension (ext=2) provides details on the aperture pixel mask and the expected coordinate system (WCS).

Parameters

extint or str: FITS extension name or number.

Returns

headerHeader: Header object containing metadata keywords.

get_keyword(self, keyword, hdu=0, default=None)¶

Returns a header keyword value.

If the keyword is Undefined or does not exist, then return default instead.

get_model(self, star_priors=None, **kwargs)¶

Returns a default TPFModel object for PRF fitting.

The default model only includes one star and only allows its flux and position to change. A different set of stars can be added using the star_priors parameter.

Parameters

**kwargsdict: Arguments to be passed to the TPFModel constructor, e.g. star_priors.

Returns

modelTPFModel object: Model with appropriate defaults for this Target Pixel File.

get_prf_model(self)¶

Returns an object of KeplerPRF initialized using the necessary metadata in the tpf object.

Returns

prfinstance of SimpleKeplerPRF

interact(self, notebook_url='localhost:8888', max_cadences=30000, aperture_mask='pipeline', exported_filename=None, transform_func=None, ylim_func=None, **kwargs)¶

Display an interactive Jupyter Notebook widget to inspect the pixel data.

The widget will show both the lightcurve and pixel data. By default, the lightcurve shown is obtained by calling the to_lightcurve() method, unless the user supplies a custom LightCurve object. This feature requires an optional dependency, bokeh (v0.12.15 or later). This dependency can be installed using e.g. conda install bokeh.

At this time, this feature only works inside an active Jupyter Notebook, and tends to be too slow when more than ~30,000 cadences are contained in the TPF (e.g. short cadence data).

Parameters

notebook_urlstr: Location of the Jupyter notebook page (default: “localhost:8888”) When showing Bokeh applications, the Bokeh server must be explicitly configured to allow connections originating from different URLs. This parameter defaults to the standard notebook host and port. If you are running on a different location, you will need to supply this value for the application to display properly. If no protocol is supplied in the URL, e.g. if it is of the form “localhost:8888”, then “http” will be used.
max_cadencesint: Raise a RuntimeError if the number of cadences shown is larger than this value. This limit helps keep browsers from becoming unresponsive.
aperture_maskarray-like, ‘pipeline’, ‘threshold’ or ‘all’: A boolean array describing the aperture such that True means that the pixel will be used. If None or ‘all’ are passed, all pixels will be used. If ‘pipeline’ is passed, the mask suggested by the official pipeline will be returned. If ‘threshold’ is passed, all pixels brighter than 3-sigma above the median flux will be used.
exported_filename: str: An optional filename to assign to exported fits files containing the custom aperture mask generated by clicking on pixels in interact. The default adds a suffix ‘-custom-aperture-mask.fits’ to the TargetPixelFile basename.
transform_func: function: A function that transforms the lightcurve. The function takes in a LightCurve object as input and returns a LightCurve object as output. The function can be complex, such as detrending the lightcurve. In this way, the interactive selection of aperture mask can be evaluated after inspection of the transformed lightcurve. The transform_func is applied before saving a fits file. Default: None (no transform is applied).
ylim_func: function: A function that returns ylimits (low, high) given a LightCurve object. The default is to return an expanded window around the 10-90th percentile of lightcurve flux values.

Examples

To select an aperture mask for V827 Tau:

>>> import lightkurve as lk
>>> tpf = lk.search_targetpixelfile("V827 Tau", mission="K2").download()  
>>> tpf.interact()  

To see the full y-axis dynamic range of your lightcurve and normalize the lightcurve after each pixel selection:

>>> ylim_func = lambda lc: (0.0, lc.flux.max())  
>>> transform_func = lambda lc: lc.normalize()  
>>> tpf.interact(ylim_func=ylim_func, transform_func=transform_func)  

interact_sky(self, notebook_url='localhost:8888', magnitude_limit=18)¶

Display a Jupyter Notebook widget showing Gaia DR2 positions on top of the pixels.

Parameters

notebook_urlstr: Location of the Jupyter notebook page (default: “localhost:8888”) When showing Bokeh applications, the Bokeh server must be explicitly configured to allow connections originating from different URLs. This parameter defaults to the standard notebook host and port. If you are running on a different location, you will need to supply this value for the application to display properly. If no protocol is supplied in the URL, e.g. if it is of the form “localhost:8888”, then “http” will be used.
magnitude_limitfloat: A value to limit the results in based on Gaia Gmag. Default, 18.

plot(self, ax=None, frame=0, cadenceno=None, bkg=False, aperture_mask=None, show_colorbar=True, mask_color='pink', title=None, style='lightkurve', **kwargs)¶

Plot the pixel data for a single frame (i.e. at a single time).

The time can be specified by frame index number (frame=0 will show the first frame) or absolute cadence number (cadenceno).

Parameters

axAxes: A matplotlib axes object to plot into. If no axes is provided, a new one will be generated.
frameint: Frame number. The default is 0, i.e. the first frame.
cadencenoint, optional: Alternatively, a cadence number can be provided. This argument has priority over frame number.
bkgbool: If True, background will be added to the pixel values.
aperture_maskndarray or str: Highlight pixels selected by aperture_mask.
show_colorbarbool: Whether or not to show the colorbar
mask_colorstr: Color to show the aperture mask
stylestr: Path or URL to a matplotlib style file, or name of one of matplotlib’s built-in stylesheets (e.g. ‘ggplot’). Lightkurve’s custom stylesheet is used by default.
kwargsdict: Keywords arguments passed to lightkurve.utils.plot_image.

Returns

axAxes: The matplotlib axes object.

prf_lightcurve(self, **kwargs)¶

query_solar_system_objects(self, cadence_mask='outliers', radius=None, sigma=3, cache=True, return_mask=False)¶

Returns a list of asteroids or comets which affected the target pixel files.

Light curves of stars or galaxies are frequently affected by solar system bodies (e.g. asteroids, comets, planets). These objects can move across a target’s photometric aperture mask on time scales of hours to days. When they pass through a mask, they tend to cause a brief spike in the brightness of the target. They can also cause dips by moving through a local background aperture mask (if any is used).

The artifical spikes and dips introduced by asteroids are frequently confused with stellar flares, planet transits, etc. This method helps to identify false signals injects by asteroids by providing a list of the solar system objects (name, brightness, time) that passed in the vicinity of the target during the span of the light curve.

This method queries the SkyBot API, which returns a list of asteroids/comets/planets given a location, time, and search cone.

Notes: * This method will use the ra and dec properties of the LightCurve

object to determine the position of the search cone.

The size of the search cone is 15 spacecraft pixels by default. You can change this by passing the radius parameter (unit: degrees).
This method will only search points in time during which he light curve showed 3-sigma outliers in flux. You can override this behavior and search all times by passing the cadence_mask='all' argument, but this will be much slower.

Parameters

cadence_maskstr or bool: mask in time to select which frames or points should be searched for SSOs. Default “outliers” will search for SSOs at points that are sigma from the mean. “all” will search all cadences. Pass a boolean array with values of “True” for times to search for SSOs.
radiusoptional, float: Radius to search for bodies. If None, will search for SSOs within 5 pixels of all pixels in the TPF.
sigmaoptional, float: If cadence_mask is set to "outlier", sigma will be used to identify outliers.
cacheoptional, bool: If True will cache the search result in the astropy cache. Set to False to request the search again.
return_mask: bool: If True will return a boolean mask in time alongside the result

Returns

resultpandas.DataFrame: DataFrame containing the list objects in frames that were identified to contain SSOs.

show_properties(self)¶

Prints a description of all non-callable attributes.

Prints in order of type (ints, strings, lists, arrays, others).

to_corrector(self, method='pld')¶

Returns a Corrector instance to remove systematics.

Parameters

methodsstring: Currently, only “pld” is supported. This will return a PLDCorrector class instance.

Returns

correcterlightkurve.Correcter: Instance of a Corrector class, which typically provides correct() and diagnose() methods.

to_fits(self, output_fn=None, overwrite=False)¶: Writes the TPF to a FITS file on disk.

to_lightcurve(self, method='aperture', **kwargs)¶

Performs photometry on the pixel data and returns a LightCurve object.

See the docstring of aperture_photometry() for valid arguments if the method is ‘aperture’. Otherwise, see the docstring of prf_photometry() for valid arguments if the method is ‘prf’.

Parameters

method‘aperture’ or ‘prf’.: Photometry method to use.
**kwargsdict: Extra arguments to be passed to the aperture_photometry or the prf_photometry method of this class.

Returns

lcLightCurve object: Object containing the resulting lightcurve.