Documentation for KeplerFFI
Class for loading Kepler's FFI files and compute PRF models out of them following
the method discussed in Hedges et al. 2021 and Martinez-Palomera et al. 2021.
__init__(self, ffi_name='', channel=1, quarter=None, plot=True, save=True)
special
Initialization of the KeplerFFI class
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ffi_name |
str |
Name of the FFI file used to model the PRF profile. Either ffi_name or quarter can be provided. |
'' |
channel |
int |
Channel number of the FFI to be used to model the PRF. Valid values are between 1 and 84. |
1 |
quarter |
int |
Number of the quarter that will be used to model the PRF. Either ffi_name or quarter can be provided, if quarter is provided, then all FFI files observed during the time window of that quarter will be used to model the PRF by averaging the images. Valid values are between 1 and 17. |
None |
plot |
bool |
Whether to clreate diagnostic plots or not. |
True |
save |
bool |
Whether to save the models or not. |
True |
Attributes:
| Name | Type | Description |
|---|---|---|
channel |
int |
Number of the quarter that will be used to model the PRF. |
quarter |
int |
Channel number of the FFI to be used to model the PRF. |
plot |
bool |
Boolean to create diagnostic plots. |
save |
bool |
Boolean to save models and figures. |
hdr |
dict |
Header dictionary of the FFI file. |
img |
numpy.ndarray |
Original FFI flux image in electros / sec. |
wcs |
astropy.WCS |
Object with the WCS solution of the image. |
col_2d |
numpy.ndarray |
Data array with the pixel column number in 2D |
row_2d |
numpy.ndarray |
Data array with the pixel row number in 2D |
ra_2d |
numpy.ndarray |
Data array with the pixel Right Ascension value in 2D, in degs |
dec_2d |
numpy.ndarray |
Data array with the pixel Declination value in 2D, in degs |
flux_2d |
numpy.ndarray |
Data array with the flux value of each pixel with substracted background in 2D, in electros / sec. |
sources |
pandas.DataFrame |
Catalog with Gaia sources observed in the image, after cleaning. |
flux |
numpy.ndarray |
Data array with the flux value of each pixel with substracted background in 1D after removing saturated & bright pixels. in electros / sec. |
flux_err |
numpy.ndarray |
Data array with the flux error value of each pixel with substracted background in 1D after removing saturated & bright pixels. in electros / sec. |
col |
numpy.ndarray |
Data array with the pixel column number in 1D after removing saturated & bright pixels |
row |
numpy.ndarray |
Data array with the pixel row number in 1D after removing saturated & bright pixels |
nsurces |
int |
Total number of sources observed in the image after cleaning. |
npixels |
int |
Total number of pixels in the image |
gf |
numpy.ndarray |
Data array with the Gaia flux value for every source. |
dflux |
scipy.sparse.csr_matrix |
Sparse matrix with pixel flux value within r < 7 pixels of the source coordinates. Has shape [nsources , npixels] |
dx |
scipy.sparse.csr_matrix |
Sparse matrix with distance between the pixel within r < 7 pixels and the source location, in pixel units. Has shape [nsources , npixels] |
dy |
scipy.sparse.csr_matrix |
Sparse matrix with distance between the pixel within r < 7 pixels and the source location, in pixel units. Has shape [nsources , npixels] |
r |
scipy.sparse.csr_matrix |
Sparse matrix with radial distance between pixels within r < 7 and the source location, in polar coordinates. Has shape [nsources , npixels] |
phi |
scipy.sparse.csr_matrix |
Sparse matrix with angle value of pixels within r < 7 and the source location, in polar coordinates. Has shape [nsources , npixels] |
_build_prf_shape(self, n_r_knots=10, n_phi_knots=12, cut_r=6, flux_cut_off=1)
private
Builds a sparse model matrix of shape nsources x npixels to be used when
fitting each source pixels to estimate its PSF photometry
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_r_knots |
int |
Number of radial knots in the spline model. |
10 |
n_phi_knots |
int |
Number of azimuthal knots in the spline model. |
12 |
cut_r |
int |
Distance at which the spline Design matrix has only dependency in the radial axis. |
6 |
flux_cut_off |
float |
The flux in COUNTS at which to stop evaluating the model. |
1 |
_clean_source_list(self, sources)
private
Function to clean surces from the catalog removing sources near the borders,
with 10 pixel tolerance, and to remove blended sources (within 8")
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sources |
pandas.DataFrame |
Catalog with sources to be removed |
required |
Returns:
| Type | Description |
|---|---|
pandas.DataFrame |
Clean catalog |
_create_sparse(self)
private
Function to create sparse matrces (scipy.sparse.csr_matrix) for variables:
dx, dy, dflux, dfluxerr, r, and phy This is extremelly necessary for FFI due to the large number of sources (~10k) and pixels (~1.1M). The sparse matrices contain the pixel data around the sources up to 7 pixels distance from the object location.
_do_big_query(self, ra, dec, epoch)
private
Query Gaia catalogs (EDR3 default) to obtain sources observed in the FFI.
If query finishs ok, result will be saved for future use in the following
directory:
../data/catalogs/ffi/
It does nx*ny small queries to avoid TimeoutError that might happen when doing large (rad > 0.7 deg) queries to Gaia archive. The ouput file has unique objects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ra |
list |
Value of the Right Ascension coordinate used for the query, in deg. |
required |
dec |
list |
Value of the Declination coordinate used for the query, in deg. |
required |
epoch |
float |
Year of the observation (Julian year) used for proper motion correction. |
required |
Returns:
| Type | Description |
|---|---|
pandas.DataFrame |
Clean catalog |
_get_mean_model(self)
private
Convenience function to make the scene PRF model
_get_source_mask(self, upper_radius_limit=7, lower_radius_limit=1.1, flux_cut_off=300, dm_type='rf-quadratic', plot=False)
private
Find the pixel mask that identifies pixels with contributions from ANY NUMBER
of Sources. Fits a simple polynomial model to the log of the pixel flux values, in radial dimension and source flux, to find the optimum circular apertures for every source.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
upper_radius_limit |
float |
The radius limit at which we assume there is no flux from a source of any brightness (arcsec). |
7 |
lower_radius_limit |
float |
The radius limit at which we assume there is flux from a source of any brightness (arcsec). |
1.1 |
flux_cut_off |
float |
The flux at which we assume a source is too faint to model |
300 |
dm_type |
string |
Type of design matrix to be used for modeling. Default is |
'rf-quadratic' |
plot |
bool |
Whether to show diagnostic plot. Default is False. |
False |
_get_uncontaminated_source_mask(self)
private
creates a mask of shape nsources x npixels where targets are not contaminated.
This mask is used to select pixels to build the PSF model.
_mask_bright_sources(self, flux, column, row, sources, mag_limit=10)
private
Finds and removes halos produced by bright stars (<10 mag)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flux |
numpu.ndarray |
Data array with pixel flux value |
required |
column |
numpy.ndarray |
Data array with pixel column value |
required |
row |
numpy.ndarray |
Data array with pixel row value |
required |
sources |
pandas.DataFrame |
Catalog wih observed sources in the image |
required |
mag_limit |
foat |
Magnitude limit at which bright sources are identified. |
10 |
Returns:
| Type | Description |
|---|---|
numpy.ndarray |
Boolean mask with rejected pixels |
_model_bkg(self, data, mask=None)
private
BkgZoomInterpolator:
This class generates full-sized background and background RMS images
from lower-resolution mesh images using the ~scipy.ndimage.zoom
(spline) interpolator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
numpy.ndarray |
Data arra with the pixel flux values. |
required |
mask |
numpy.ndarray |
Boolean array to mask pixels with sources. |
None |
Returns:
| Type | Description |
|---|---|
numpy.ndarray |
Data array with background model |
_saturated_pixels_mask(self, flux, column, row, saturation_limit=150000.0)
private
Finds and removes saturated pixels, including bleed columns.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flux |
numpu.ndarray |
Data array with pixel flux value |
required |
column |
numpy.ndarray |
Data array with pixel column value |
required |
row |
numpy.ndarray |
Data array with pixel row value |
required |
saturation_limit |
foat |
Saturation limit at which pixels are removed. |
150000.0 |
Returns:
| Type | Description |
|---|---|
numpy.ndarray |
Boolean mask with rejected pixels |
build_prf_model(self, n_r_knots=5, n_phi_knots=15)
Function that creates a PRF shape using the sources. In combines all other
helping functions that build the source mask, remove contaminated pixels, estimate PRF edges, and create the final PRF model.
For details see:
self._create_sparse()
self._get_source_mask()
self._get_uncontaminated_source_mask()
self._build_prf_shape()
Default parameters where used for Martinez-Palomera et al. 2021.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_r_knots |
int |
Number of radial knots in the spline model. |
5 |
n_phi_knots |
int |
Number of azimuthal knots in the spline model. |
15 |
download_ffi(fits_name)
staticmethod
Download FFI fits file to a dedicated quarter directory
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fits_name |
string |
Name of FFI fits file |
required |
fit_model(self)
Function to fit the PRF model and do LFD photometry for the sources observed in
the FFIs.
plot_image(self, ax=None, sources=False)
Function to plot the Full Frame Image and the Gaia Sources
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax |
matplotlib.axes |
Matlotlib axis can be provided, if not one will be created and returned |
None |
sources |
boolean |
Whether to overplot or not the source catalog |
False |
Returns:
| Type | Description |
|---|---|
matplotlib.axes |
Matlotlib axis with the figure |
plot_pixel_masks(self, ax=None)
Function to plot the mask used to reject saturated and bright pixels
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax |
matplotlib.axes |
Matlotlib axis can be provided, if not one will be created and returned |
None |
Returns:
| Type | Description |
|---|---|
matplotlib.axes |
Matlotlib axis with the figure |
plot_prf_shape(self)
Function to plot the PRF model in Cartesian and Polar coordinates
save_model(self, path=None)
Function to save the PRF model weights, number of knots for r and phy, and
rmin and rmax to re-build the Design Matrix. The file is a csv table, that contain a multi-index column table. Rows are each channel, and columns are: ["n_r_knots", "n_phi_knots", "rmin", "rmax", ...prf_ws...] This file can be loaded as: pd.read_csv(fname, index_col=0, header=[0, 1])
Note: models with different number of knots lead to different number of weights, and ins necessary to create separete files to preserve the esctructure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path |
string |
Path of the file |
None |