KeplerTargetPixelFile¶

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

Bases: lightkurve.targetpixelfile.TargetPixelFile

Represents pixel data products created by NASA’s Kepler pipeline.

This class enables extraction of custom light curves and centroid positions.

Parameters:

Parameters:	path : str or `astropy.io.fits.HDUList` Path to a Kepler Target Pixel (FITS) File or a `HDUList` object. quality_bitmask : str or int Bitmask (integer) which identifies the quality flag bitmask that should be used to mask out bad cadences. If a string is passed, it has the following meaning: “none”: no cadences will be ignored (`quality_bitmask=0`). “default”: cadences with severe quality issues will be ignored (`quality_bitmask=1130799`). “hard”: more conservative choice of flags to ignore (`quality_bitmask=1664431`). This is known to remove good data. “hardest”: removes all data that has been flagged (`quality_bitmask=2096639`). This mask is not recommended. See the `KeplerQualityFlags` class for details on the bitmasks. kwargs : dict Keyword arguments passed to `astropy.io.fits.open()`.

path : str or astropy.io.fits.HDUList

Path to a Kepler Target Pixel (FITS) File or a HDUList object.

quality_bitmask : str or int

Bitmask (integer) which identifies the quality flag bitmask that should be used to mask out bad cadences. If a string is passed, it has the following meaning:

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

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

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

“hardest”: removes all data that has been flagged (quality_bitmask=2096639). This mask is not recommended.

See the KeplerQualityFlags class for details on the bitmasks.

kwargs : dict

Keyword arguments passed 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`	Returns the header of the primary extension.
`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

`centroids`(**kwargs)	DEPRECATED: use `estimate_cdpp()` instead.
`create_threshold_mask`([threshold, …])	Returns an aperture mask creating using the thresholding method.
`estimate_centroids`([aperture_mask])	Returns centroid positions estimated using sample moments.
`extract_aperture_photometry`([aperture_mask])	Returns a LightCurve obtained using aperture photometry.
`extract_prf_photometry`([cadences, parallel])	Returns the results of PRF photometry applied to the pixel file.
`from_archive`(target[, cadence, quarter, …])	WARNING: THIS FUNCTION IS DEPRECATED AND WILL BE REMOVED VERY SOON.
`from_fits`(path_or_url, **kwargs)	WARNING: THIS FUNCTION IS DEPRECATED AND WILL BE REMOVED VERY SOON.
`from_fits_images`(images, position[, size, …])	Creates a new Target Pixel File from a set of images.
`get_bkg_lightcurve`([aperture_mask])
`get_coordinates`([cadence])	Returns two 3D arrays of RA and Dec values in decimal degrees.
`get_keyword`(keyword[, hdu, default])	Returns a header keyword value.
`get_model`([star_priors])	Returns a default `TPFModel` object for PRF fitting.
`get_prf_model`()	Returns an object of KeplerPRF initialized using the necessary metadata in the tpf object.
`interact`([notebook_url, max_cadences, …])	Display an interactive Jupyter Notebook widget to inspect the pixel data.
`plot`([ax, frame, cadenceno, bkg, …])	Plot the pixel data for a single frame (i.e.
`prf_lightcurve`(**kwargs)
`show_properties`()	Prints a description of all non-callable attributes.
`to_fits`([output_fn, overwrite])	Writes the TPF to a FITS file on disk.
`to_lightcurve`([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¶: Returns the header of the primary extension.

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:	w : astropy.wcs.WCS object WCS solution

Methods Documentation

centroids(**kwargs)¶: DEPRECATED: use estimate_cdpp() instead.

create_threshold_mask(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:

Parameters:	threshold : float 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_mask : ndarray 2D boolean numpy array containing `True` for pixels above the threshold.

threshold : float: 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_mask : ndarray: 2D boolean numpy array containing True for pixels above the threshold.

estimate_centroids(aperture_mask='pipeline')¶

Returns centroid positions estimated using sample moments.

Parameters:

Parameters:	aperture_mask : array-like, ‘pipeline’, 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.
Returns:	col_centr, row_centr : tuple Arrays containing centroids for column and row at each cadence

aperture_mask : array-like, ‘pipeline’, 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.

Returns:

col_centr, row_centr : tuple: Arrays containing centroids for column and row at each cadence

extract_aperture_photometry(aperture_mask='pipeline')¶

Returns a LightCurve obtained using aperture photometry.

Parameters:

Parameters:	aperture_mask : array-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.
Returns:	lc : KeplerLightCurve object Array containing the summed flux within the aperture for each cadence.

aperture_mask : array-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.

Returns:

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

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

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

Parameters:	cadences : list of int Cadences to fit. If `None` (default) then all cadences will be fit. parallel : bool If `True`, fitting cadences will be distributed across multiple cores using Python’s `multiprocessing` module. **kwargs : dict Keywords to be passed to `tpf.get_model()` to create the `TPFModel` object that will be fit.
Returns:	results : PRFPhotometry object Object that provides access to PRF-fitting photometry results and various diagnostics.

static from_archive(target, cadence='long', quarter=None, month=None, campaign=None, quality_bitmask='default', **kwargs)¶

WARNING: THIS FUNCTION IS DEPRECATED AND WILL BE REMOVED VERY SOON. Use lightkurve.search_targetpixelfile() instead.

Parameters:

Parameters:	target : str or int KIC/EPIC ID or object name. cadence : str ‘long’ or ‘short’. quarter, campaign : int, list of ints, or ‘all’ Kepler Quarter or K2 Campaign number. month : 1, 2, 3, list or ‘all’ For Kepler’s prime mission, there are three short-cadence Target Pixel Files for each quarter, each covering one month. Hence, if cadence=’short’ you need to specify month=1, 2, or 3. quality_bitmask : str or int Bitmask (integer) which identifies the quality flag bitmask that should be used to mask out bad cadences. If a string is passed, it has the following meaning: “none”: no cadences will be ignored (`quality_bitmask=0`). “default”: cadences with severe quality issues will be ignored (`quality_bitmask=1130799`). “hard”: more conservative choice of flags to ignore (`quality_bitmask=1664431`). This is known to remove good data. “hardest”: removes all data that has been flagged (`quality_bitmask=2096639`). This mask is not recommended. See the `KeplerQualityFlags` class for details on the bitmasks. kwargs : dict Keywords arguments passed to the constructor of `KeplerTargetPixelFile`.
Returns:	tpf : `KeplerTargetPixelFile` or `TargetPixelFileCollection` object.

target : str or int

KIC/EPIC ID or object name.

cadence : str

‘long’ or ‘short’.

quarter, campaign : int, list of ints, or ‘all’

Kepler Quarter or K2 Campaign number.

month : 1, 2, 3, list or ‘all’

For Kepler’s prime mission, there are three short-cadence Target Pixel Files for each quarter, each covering one month. Hence, if cadence=’short’ you need to specify month=1, 2, or 3.

quality_bitmask : str or int

Bitmask (integer) which identifies the quality flag bitmask that should be used to mask out bad cadences. If a string is passed, it has the following meaning:

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

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

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

“hardest”: removes all data that has been flagged (quality_bitmask=2096639). This mask is not recommended.

See the KeplerQualityFlags class for details on the bitmasks.

kwargs : dict

Keywords arguments passed to the constructor of KeplerTargetPixelFile.

Returns:

tpf : KeplerTargetPixelFile or TargetPixelFileCollection object.

classmethod from_fits(path_or_url, **kwargs)¶

WARNING: THIS FUNCTION IS DEPRECATED AND WILL BE REMOVED VERY SOON.

Please use lightkurve.open() instead.

static from_fits_images(images, position, size=(11, 11), extension=1, target_id='unnamed-target', hdu0_keywords={}, **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:

Parameters:	images : list of str, or list of fits.ImageHDU objects Sorted list of FITS filename paths or ImageHDU objects to get the data from. position : astropy.SkyCoord Position around which to cut out pixels. size : (int, int) Dimensions (cols, rows) to cut out around `position`. extension : int or str If `images` is a list of filenames, provide the extension number or name to use. Default: 0. target_id : int or str Unique identifier of the target to be recorded in the TPF. hdu0_keywords : dict Additional keywords to add to the first header file. **kwargs : dict Extra arguments to be passed to the `KeplerTargetPixelFile` constructor.
Returns:	tpf : KeplerTargetPixelFile A new Target Pixel File assembled from the images.

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

Returns:

tpf : KeplerTargetPixelFile: A new Target Pixel File assembled from the images.

get_bkg_lightcurve(aperture_mask=None)¶

get_coordinates(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:	ra : numpy array, same shape as tpf.flux[cadence] Array containing RA values for every pixel, for every cadence. dec : numpy array, same shape as tpf.flux[cadence] Array containing Dec values for every pixel, for every cadence.

get_keyword(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(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:	**kwargs : dict Arguments to be passed to the `TPFModel` constructor, e.g. `star_priors`.
Returns:	model : TPFModel object Model with appropriate defaults for this Target Pixel File.

get_prf_model()¶

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

Returns:	prf : instance of SimpleKeplerPRF

interact(notebook_url='localhost:8888', max_cadences=30000, aperture_mask='pipeline', exported_filename=None)¶

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:

Parameters:	notebook_url: str 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_cadences : int Raise a RuntimeError if the number of cadences shown is larger than this value. This limit helps keep browsers from becoming unresponsive. aperture_mask : array-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.

notebook_url: str: 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_cadences : int: Raise a RuntimeError if the number of cadences shown is larger than this value. This limit helps keep browsers from becoming unresponsive.
aperture_mask : array-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.

plot(ax=None, frame=0, cadenceno=None, bkg=False, aperture_mask=None, show_colorbar=True, mask_color='pink', 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:

Parameters:	ax : matplotlib.axes._subplots.AxesSubplot A matplotlib axes object to plot into. If no axes is provided, a new one will be generated. frame : int Frame number. The default is 0, i.e. the first frame. cadenceno : int, optional Alternatively, a cadence number can be provided. This argument has priority over frame number. bkg : bool If True, background will be added to the pixel values. aperture_mask : ndarray or str Highlight pixels selected by aperture_mask. show_colorbar : bool Whether or not to show the colorbar mask_color : str Color to show the aperture mask style : str 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. kwargs : dict Keywords arguments passed to `lightkurve.utils.plot_image`.
Returns:	ax : matplotlib.axes._subplots.AxesSubplot The matplotlib axes object.

ax : matplotlib.axes._subplots.AxesSubplot: A matplotlib axes object to plot into. If no axes is provided, a new one will be generated.
frame : int: Frame number. The default is 0, i.e. the first frame.
cadenceno : int, optional: Alternatively, a cadence number can be provided. This argument has priority over frame number.
bkg : bool: If True, background will be added to the pixel values.
aperture_mask : ndarray or str: Highlight pixels selected by aperture_mask.
show_colorbar : bool: Whether or not to show the colorbar
mask_color : str: Color to show the aperture mask
style : str: 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.
kwargs : dict: Keywords arguments passed to lightkurve.utils.plot_image.

Returns:

ax : matplotlib.axes._subplots.AxesSubplot: The matplotlib axes object.

prf_lightcurve(**kwargs)¶

show_properties()¶

Prints a description of all non-callable attributes.

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

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

to_lightcurve(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. **kwargs : dict Extra arguments to be passed to the `aperture_photometry` or the `prf_photometry` method of this class.
Returns:	lc : LightCurve object Object containing the resulting lightcurve.