Documentation for Machine

Class for calculating fast PRF photometry on a collection of images and

a list of in image sources.

This method is discussed in detail in Hedges et al. 2021.

This method solves a linear model to assuming Gaussian priors on the weight of each linear components as explained by Luger, Foreman-Mackey & Hogg, 2017

__init__(self, time, flux, flux_err, ra, dec, sources, column, row, limit_radius=24.0, time_mask=None, n_r_knots=10, n_phi_knots=15, time_nknots=10, time_resolution=200, time_radius=8, rmin=1, rmax=16, cut_r=6, sparse_dist_lim=40, sources_flux_column='phot_g_mean_flux') special

Parameters:

Name	Type	Description	Default
time	numpy.ndarray	Time values in JD	required
flux	numpy.ndarray	Flux values at each pixels and times in units of electrons / sec	required
flux_err	numpy.ndarray	Flux error values at each pixels and times in units of electrons / sec	required
ra	numpy.ndarray	Right Ascension coordinate of each pixel	required
dec	numpy.ndarray	Declination coordinate of each pixel	required
sources	pandas.DataFrame	DataFrame with source present in the images	required
column	np.ndarray	Data array containing the "columns" of the detector that each pixel is on.	required
row	np.ndarray	Data array containing the "rows" of the detector that each pixel is on.	required
limit_radius	numpy.ndarray	Radius limit in arcsecs to select stars to be used for PRF modeling	24.0
time_mask	np.ndarray of booleans	A boolean array of shape time. Only values where this mask is True will be used to calculate the average image for fitting the PSF. Use this to e.g. select frames with low VA, or no focus change	None
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.	15
time_nknots	int	Number og knots for cartesian DM in time model.	10
time_resolution	int	Number of time points to bin by when fitting for velocity aberration.	200
time_radius	float	The radius around sources, out to which the velocity aberration model will be fit. (arcseconds)	8
rmin	float	The minimum radius for the PRF model to be fit. (arcseconds)	1
rmax	float	The maximum radius for the PRF model to be fit. (arcseconds)	16
cut_r	float	Radius distance whithin the shape model only depends on radius and not angle.	6
sparse_dist_lim	float	Radial distance used to include pixels around sources when creating delta arrays (dra, ddec, r, and phi) as sparse matrices for efficiency. Default is 40" (recommended for kepler). (arcseconds)	40
sources_flux_column	str	Column name in sources table to be used as flux estimate. For Kepler data gaia.phot_g_mean_flux is recommended, for TESS use gaia.phot_rp_mean_flux.	'phot_g_mean_flux'

Attributes:

Name	Type	Description
nsources	int	Number of sources to be extracted
nt	int	Number of onservations in the time series (aka number of cadences)
npixels	int	Total number of pixels with flux measurements
source_flux_estimates	numpy.ndarray	First estimation of pixel fluxes assuming values given by the sources catalog (e.g. Gaia phot_g_mean_flux)
dra	numpy.ndarray	Distance in right ascension between pixel and source coordinates, units of degrees
ddec	numpy.ndarray	Distance in declination between pixel and source coordinates, units of degrees
r	numpy.ndarray	Radial distance between pixel and source coordinates (polar coordinates), in units of arcseconds
phi	numpy.ndarray	Angle between pixel and source coordinates (polar coordinates), in units of radians
source_mask	scipy.sparce.csr_matrix	Sparce mask matrix with pixels that contains flux from sources
uncontaminated_source_mask	scipy.sparce.csr_matrix	Sparce mask matrix with selected uncontaminated pixels per source to be used to build the PSF model
mean_model	scipy.sparce.csr_matrix	Mean PSF model values per pixel used for PSF photometry
cartesian_knot_spacing	string	Defines the type of spacing between knots in cartessian space to generate the design matrix, options are "linear" or "sqrt".
quiet	booleans	Quiets TQDM progress bars.
contaminant_mag_limit	float	The limiting magnitude at which a sources is considered as contaminant

build_shape_model(self, plot=False, flux_cut_off=1, frame_index='mean', bin_data=False, **kwargs)

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
plot	boolean	Make a diagnostic plot	False
flux_cut_off	float	the flux in COUNTS at which to stop evaluating the model!	1
frame_index	string or int	The frame index used to build the shape model, if "mean" then use the mean value across time	'mean'
bin_data	boolean	Bin flux data spatially to increase SNR before fitting the shape model	False
**kwargs	None	Keyword arguments to be passed to _get_source_mask()	{}

build_time_model(self, plot=False, bin_method='bin', poly_order=3, segments=False, focus=False, focus_exptime=50, pca_ncomponents=0, pca_smooth_time_scale=0, positions=False, other_vectors=None)

Builds a time model that moves the PRF model to account for the scene movement

due to velocity aberration. It has two methods to choose from using the attribute self.time_corrector, if "polynomial" (default) will use a polynomial in time, if "poscorr" will use the pos_corr vectos that can be found in the TPFs. The time polynomial gives a more flexible model vs the pos_corr option, but can lead to light curves with "weird" long-term trends. Using pos_corr is recomended for Kepler data.

Parameters:

Name	Type	Description	Default
plot	boolean	Plot a diagnostic figure.	False
bin_method	string	Type of bin method, options are "bin" and "downsample".	'bin'
poly_order	int	Degree of the time polynomial used for the time model. Default is 3.	3
segments	boolean	If True will split the light curve into segments to fit different time models with a common pixel normalization. If False will fit the full time series as one segment. Segments breaks are infered from time discontinuities.	False
focus	boolean	Add a component that models th focus change at the begining of a segment.	False
focus_exptime	int	Characteristic decay for focus component modeled as exponential decay when focus is True. In the same units as PerturbationMatrix3D.time.	50
pca_ncomponents	int	Number of PCA components used in PerturbationMatrix3D. The components are derived from pixel light lighrcurves.	0
pca_smooth_time_scale	float	Smooth time sacel for PCA components.	0
positions	boolean or string	If one of strings "poscorr", "centroid" then the perturbation matrix will add other vectors accounting for position shift.	False
other_vectors	list or numpy.ndarray	Set of other components used to include in the perturbed model. See psfmachine.perturbation.PerturbationMatrix object for details. Posible use case are using Kepler CBVs or engeneering data. Shape has to be (ncomponents, ntimes). Default is None.	None

compute_aperture_photometry(self, aperture_size='optimal', target_complete=0.9, target_crowd=0.9)

Computes aperture photometry for all sources in the scene. The aperture shape

follow the PRF profile.

Parameters:

Name	Type	Description	Default
aperture_size	string or int	Size of the aperture to be used. If "optimal" the aperture will be optimized using the flux metric targets. If int between [0, 100], then the boundaries of the aperture are calculated from the normalized flux value of the given ith percentile.	'optimal'
target_complete	float	Target flux completeness metric (FLFRCSAP) used if aperture_size is "optimal".	0.9
target_crowd	float	Target flux crowding metric (CROWDSAP) used if aperture_size is "optimal".	0.9

create_aperture_mask(self, percentile=50)

Function to create the aperture mask of a given source for a given aperture

size. This function can compute aperutre mask for all sources in the scene.

It creates three new attributes: * self.aperture_mask has the aperture mask, shape is [n_surces, n_pixels] * self.FLFRCSAP has the completeness metric, shape is [n_sources] * self.CROWDSAP has the crowdeness metric, shape is [n_sources]

Parameters:

Name	Type	Description	Default
percentile	float or list of floats	Percentile value that defines the isophote from the distribution of values in the PRF model of the source. If float, then all sources will use the same percentile value. If list, then it has to have lenght that matches self.nsources, then each source has its own percentile value.	50

fit_model(self, fit_va=False)

Finds the best fitting weights for every source, simultaneously

Parameters:

Name	Type	Description	Default
fit_va	boolean	Fitting model accounting for velocity aberration. If True, then a time model has to be built previously with build_time_model.	False

get_psf_metrics(self, npoints_per_pixel=10)

Computes three metrics for the PSF model:

source_psf_fraction: the amount of PSF in the data. Tells how much of a sources is used to estimate the PSF, values are in between [0, 1]. perturbed_ratio_mean: the ratio between the mean model and perturbed model for each source. Usefull to find when the time model affects the mean value of the light curve. perturbed_std: the standard deviation of the perturbed model for each source. USeful to find when the time model introduces variability in the light curve.

If npoints_per_pixel > 0, it creates high npoints_per_pixel shape models for each source by dividing each pixels into a grid of [npoints_per_pixel x npoints_per_pixel]. This provides a better estimate of source_psf_fraction.

Parameters:

Name	Type	Description	Default
npoints_per_pixel	int	Value in which each pixel axis is split to increase npoints_per_pixel. Default is 0 for no subpixel npoints_per_pixel.	10

perturbed_model(self, time_index)

Computes the perturbed model at a given time

Parameters:

Name	Type	Description	Default
time_index	int or np.ndarray	Time index where to evaluate the perturbed model.	required

plot_shape_model(self, frame_index='mean', bin_data=False)

Diagnostic plot of shape model.

Parameters:

Name	Type	Description	Default
frame_index	string or int	The frame index used to plot the shape model, if "mean" then use the mean value across time	'mean'
bin_data	bool	Bin or not the pixel data in a 2D historgram, default is False.	False

Returns:

Type	Description
matplotlib.Figure	Figure.

plot_time_model(self)

Diagnostic plot of time model.

Returns:

Type	Description
matplotlib.Figure	Figure.