FitPSFPerturbations

class macauff.FitPSFPerturbations(psf_fwhm, d_di, d_li, n_pool, data_save_folder, plot_save_folder=None)

Bases: object

Class that derives a parameterisation of the effect of a hidden, blended contaminant within a brighter source in a photometric image, based on fitting the composite object with a single Gaussian PSF in the limit that sky background dominates and noise is constant across the image.

Initialise FitPSFPerturbations with necessary parameters.

Parameters:

psf_fwhmfloat

The full-width at half-maximum of the PSF to simulate fitting for perturbations.

d_difloat

Separation between perturber offsets, setting the precision of the simulated perturbations.

d_lifloat

Separation between relative perturber fluxes, affecting the precision of the derived offset relations.

n_poolinteger

Number of parallel threads to use for multiprocessing calls.

data_save_folderstring

Relative or absolute path into which to save the data created by the fitting process.

plot_save_folderstring

Relative or absolute path, used to save plots generated as part of the PSF algorithm AUF perturbation parameters.

Methods Summary

__call__(run_initial_ld, run_skew_fit, ...)	Call function for FitPSFPerturbations.
dd_combined_fit(p, x, l, l_cut)	Wrapper function for calculating the combined description of the perturber offsets as a linear relation up to a particular offset and a skew-normal distribution beyond that.
dd_fitting_wrapper(iterable)	Wrapper for fitting the parameters for the skew-normal distribution to a position offset-perturber position relationship of a particular flux value of perturber, via basinhopping.
fit_one_skew(p, x, l)	Function used in the fitting of a skew-normal distribution, calculating the value of the skew-normal and its derivative with respect to its parameters at the given value.
fit_poly(p, x)	Wrapper function for evaluating a polynomial with weights p at all x, \(y_j = \sum_{i=0}^N p_i x_j^i\), and its derivative with respect to each parameter p.
fit_polynomial_parameterisations()	Function controlling the derivation of power law polynomial fits to skew-normal distribution parameters as a function of the relative flux of the perturber.
fit_skew_distributions()	Function for fitting sets of position offsets as a function of perturber position with skew-normal distributions, accounting for a break at small offsets where relationship becomes linear, for each value of perturber relative flux.
hess_dd_fit_xy(p, l, xis, yis, lis, sig)	Second-order derivatives of the fit of one PSF model to two or more simulated sources, following the minimisation routine min_dd_fit_xy.
loop_ind_fit(iterable)	Wrapper function for fitting perturbation offset and flux brightening of one PSF model fit to multiple unresolved objects, for arbitrary relative flux and position.
make_initial_ld_perturbations()	Derive full perturbations due to additional blended object within PSF for a matrix of relative flux-positional offset combinations.
min_dd_fit_xy(p, l, xis, yis, lis, sig)	Minimisation function for fitting one PSF model to two or more simulated sources, including the first-order derivatives with respect to position offset and flux brightening of the single PSF.
min_parallel_dd_fit(iterable)	Wrapper for minimisation routine used in fitting for positional offset caused by fitting two blended sources with a single PSF model.
min_parallel_dd_param_fit(iterable)	Wrapper function for calculating the best-fit polynomial parameters for describing skew-normal distribution parameters as a function of relative perturber flux.
plot_fits()	Visualisation function, plotting the various parameterisations fit in FitPSFPerturbations, enabling quality checks to be carried out.
psi(x, sig)	Calculate Psi, the convolution of two PSFs \(\phi\) (equation 2, Plewa & Sari, 2018, MNRAS, 476, 4372).
return_ddparams(li, l_cut, dd_params, n, n_ind)	Convenience function for deriving skew-normal distribution parameters as a function of perturber flux from fit polynomial distributions.

Methods Documentation

__call__(run_initial_ld, run_skew_fit, run_polynomial_fit, make_fit_plots, draw_sim_num=500000)

Call function for FitPSFPerturbations.

Parameters:

run_initial_ldboolean

Flag for whether to run the initial fitting of perturbation at various relative flux-distance combinations if data already exist.

run_skew_fitboolean

Toggle for whether to always run the fitting of each relative flux’s perturbation as a function of perturber position with a skew normal.

run_polynomial_fitboolean

Flag indicating whether to re-run fitting of skew normal parameters as a function of relative perturber flux even if already run previously.

make_fit_plotsboolean

Controls whether summary plot is created for parameterisation run.

draw_sim_numinteger, optional

Number of realisations to draw when plotting summary figure for goodness-of-fit distributions.

dd_combined_fit(p, x, l, l_cut)

Wrapper function for calculating the combined description of the perturber offsets as a linear relation up to a particular offset and a skew-normal distribution beyond that.

Parameters:

plist

The values of the skew-normal distribution (sigma, mean, skewness, amplitude), as well as the cutoff radius inside which to follow a linear relation.

xnumpy.ndarray

Values at which to evaluate the offset due to a blended perturber.

lfloat

Relative flux of the perturber as compared with the central object.

l_cutfloat

Cutoff relative flux, above which no skew-normal distribution is used at all.

Returns:

ynumpy.ndarray

The composite perturbation function, linear within p[-1] and a skew-normal distribution outside.

dd_fitting_wrapper(iterable)

Wrapper for fitting the parameters for the skew-normal distribution to a position offset-perturber position relationship of a particular flux value of perturber, via basinhopping.

Parameters:

iterablelist

List of values passed through multiprocessing, including the index into the relative flux array, the keywords passed through to basinhopping (containing the method used, the arguments to pass to basinhopping, and things like whether to compute the Jacobian), the number of basin hop iterations, starting argument values, and basin hop step size and “temperature”.

Returns:

res~`scipy.optimize.OptimizeResult`

The scipy optimisation output containing the best-fit skew-normal parameters from all basins.

fit_one_skew(p, x, l)

Function used in the fitting of a skew-normal distribution, calculating the value of the skew-normal and its derivative with respect to its parameters at the given value.

Parameters:

plist

List of skew-normal parameters, the Gaussian sigma, mean, skewness and amplitude respectively.

xnumpy.ndarray

Input values at which to evaluate the skew-normal distribution.

lfloat

Relative flux of perturber for which perturbation-position relations are being fit with the skew-normal distribution.

Returns:

fnumpy.ndarray

The skew-normal distribution evaluated at all x.

dfnumpy.ndarray

The derivative of f with respect to its Gaussian sigma, mean, skewness, and amplitude respectively.

fit_poly(p, x)

Wrapper function for evaluating a polynomial with weights p at all x, \(y_j = \sum_{i=0}^N p_i x_j^i\), and its derivative with respect to each parameter p.

Parameters:

plist or numpy.ndarray

The weights of the polynomial.

xnumpy.ndarray

Values at which to calculate the polynomial.

Returns:

ynumpy.ndarray

The evaluation of the polynomial with parameters p at each x.

dylist

The derivative of y with respect to each p_i parameter.

fit_polynomial_parameterisations()

Function controlling the derivation of power law polynomial fits to skew-normal distribution parameters as a function of the relative flux of the perturber.

fit_skew_distributions()

Function for fitting sets of position offsets as a function of perturber position with skew-normal distributions, accounting for a break at small offsets where relationship becomes linear, for each value of perturber relative flux.

hess_dd_fit_xy(p, l, xis, yis, lis, sig)

Second-order derivatives of the fit of one PSF model to two or more simulated sources, following the minimisation routine min_dd_fit_xy.

Parameters:

plist

List of the current values of perturbation offset and flux brightening caused by all perturbers hidden within the central object’s PSF.

lfloat

Flux of the central object.

xisnumpy.ndarray

x-axis positions of all perturbers being fit with a single PSF.

yisnumpy.ndarray

Positions of perturbers in the opposing orthogonal axis.

lisnumpy.ndarray

Flux of perturbers relative to the central source flux l.

sigfloat

The Gaussian sigma of the PSFs being fit.

Returns:

numpy.ndarray

Negative of the Hessian of the log-likelihood fit between one PSF model and multiple injected blended sources.

loop_ind_fit(iterable)

Wrapper function for fitting perturbation offset and flux brightening of one PSF model fit to multiple unresolved objects, for arbitrary relative flux and position.

Parameters:

iterablelist

List passed through multiprocessing, containing the index of the fit, as well as PSF FWHM and Gaussian sigma, maximum relative flux at which skew-normal distributions still describe perturbation offsets, the array of skew-normal parameters as a function of relative flux, the polynomial order being fit, and an index into the polynomial order array.

Returns:

iinteger

The index of the fit, looping through the number of simulations to draw.

dxfloat

The derived perturbation offset, normalised to the PSF sigma.

lifloat

The randomly drawn relative flux of the perturbing object.

xfloat

Position of the perturbing object relative to the central source.

ddparamsnumpy.ndarray

The calculated skew-normal distribution parameters evaluated at the simulated li for the chosen polynomial order.

make_initial_ld_perturbations()

Derive full perturbations due to additional blended object within PSF for a matrix of relative flux-positional offset combinations.

min_dd_fit_xy(p, l, xis, yis, lis, sig)

Minimisation function for fitting one PSF model to two or more simulated sources, including the first-order derivatives with respect to position offset and flux brightening of the single PSF.

Parameters:

plist

List of the current values of perturbation offset and flux brightening caused by all perturbers hidden within the central object’s PSF.

lfloat

Flux of the central object.

xisnumpy.ndarray

x-axis positions of all perturbers being fit with a single PSF.

yisnumpy.ndarray

Positions of perturbers in the opposing orthogonal axis.

lisnumpy.ndarray

Flux of perturbers relative to the central source flux l.

sigfloat

The Gaussian sigma of the PSFs being fit.

Returns:

numpy.ndarray

Negative log-likelihood and its derivative with respect to position and flux offsets.

min_parallel_dd_fit(iterable)

Wrapper for minimisation routine used in fitting for positional offset caused by fitting two blended sources with a single PSF model.

Parameters:

iterablelist

List of inputs from multiprocessing, including indices into perturber position and flux arrays, the perturber parameter arrays, and the width of the Gaussian used in modelling the PSF.

Returns:

iinteger

The index into the relative flux array for this particular call.

jinteger

The perturber positional offset array index.

res~`scipy.optimize.OptimizeResult`

The scipy optimisation output.

min_parallel_dd_param_fit(iterable)

Wrapper function for calculating the best-fit polynomial parameters for describing skew-normal distribution parameters as a function of relative perturber flux.

Parameters:

iterablelist

The parameters passed through multiprocessing, including index of polynomial order, the list of polynomial orders being fit across all parallel threads, the set of skew-normal distribution parameters at all fluxes, the fluxes evaluated for perturbation offsets, and the maximum perturber position.

Returns:

jinteger

The index into the polynomial order array.

ninteger

The polynomial order being fit.

resseslist

A list containing the best-fit polynomial weights for each parameters in the skew-normal distributuon (Gaussian sigma, mean, skewness, amplitude) and linear-regime radius cutoff.

plot_fits()

Visualisation function, plotting the various parameterisations fit in FitPSFPerturbations, enabling quality checks to be carried out.

psi(x, sig)

Calculate Psi, the convolution of two PSFs \(\phi\) (equation 2, Plewa & Sari, 2018, MNRAS, 476, 4372).

Parameters:

xnumpy.ndarray

Separation at which to evaluate the phi convolution. The first axis should contain the cartesian x- and y-axis positions, with each unique object filling the subsequent axes.

sigfloat

Gaussian sigma of the PSFs being convolved.

Returns:

numpy.ndarray

The convolution of two PSFs \(\phi\) evaluated at x.

return_ddparams(li, l_cut, dd_params, n, n_ind)

Convenience function for deriving skew-normal distribution parameters as a function of perturber flux from fit polynomial distributions.

Parameters:

lifloat

The flux of the perturber relative to the flux of the central source.

l_cutlist or numpy.ndarray

List of key cut-off relative fluxes, at which parameterisations of perturber effects change.

dd_paramsnumpy.ndarray

Array of polynomial weights for each skew-normal distribution parameter, for multiple polynomial orders, for parameterisations above and below l_cut[1].

ninteger

Number of polynomial terms being used to calculate the skew-normal distribution values.

n_indinteger

Index of the chosen number of polynomial terms in dd_params.

Returns:

dd_skew_paramsnumpy.ndarray

Values of the skew-normal sigma, mean, skewness, and amplitude, evaluated at li, from a polynomial of order N+1.