starred.psf package

Submodules

starred.psf.psf module

class starred.psf.psf.PSF(image_size=64, number_of_sources=2, upsampling_factor=2, gaussian_fwhm=2, convolution_method='scipy', gaussian_kernel_size=None, include_moffat=True, elliptical_moffat=False, field_distortion=False)

Bases: object

Narrow Point Spread Function class. Coordinates and FWHM are given in the original pixel grid.

Parameters:

• image_size (int) – input images size in pixels

• number_of_sources (int) – number of input images (each containing a point source)

• upsampling_factor (int) – the rate at which the sampling frequency increases in the PSF with respect to the input images

• gaussian_fwhm (int) – the Gaussian’s FWHM in pixels. Default is 2.

• convolution_method (str) – method to use to calculate the convolution, choose between ‘fft’, ‘scipy’, and ‘lax. Recommended if jax>=0.4.9 : ‘scipy’

• gaussian_kernel_size (int) – dimensions of the Gaussian kernel, not used if method = ‘fft’. None will select the recommended size for each method.

• include_moffat (bool) – True for the PSF to be expressed as the sum of a Moffat and a grid of pixels. False to not include the Moffat. Default: True

• elliptical_moffat (bool) – Allow elliptical Moffat.

• field_distortion (bool) – Add distortion (dilation and shear) parametrized by a 2nd order polynomial in star position

dump(path, kwargs, norm, data=None, sigma_2=None, masks=None, save_output_level=4, format='hdf5')

Stores information in a given file in pickle or hdf5 format (recommended).

Parameters:

• path – Filename of the output.

• kwargs – Dictionary containing the fitted value of the model

• norm – Normalisation factor of your data. This is an important to save if you want to get the correct photometry.

• data – (Nstar x image_size x image_size) array containing the data

• sigma_2 – (Nstar x image_size x image_size) array containing the noise maps

• masks – (Nstar x image_size x image_size) array containing the noise maps

• save_output_level – Int. Level of output product to save: 1-just the parameters of the model, 2- add the input data, 3- add the output products (background, narrow PSF, full PSF) 4- add the output products for every image.

export(output_folder, kwargs_final, data, sigma_2, format='fits', full_psf_position=array([0., 0.]), star_positions=None)

Saves all the output files in fits or npy format.

Parameters:

• output_folder (str) – path to the output folder

• kwargs_final – dictionary containing all keyword arguments

• data – array containing the images

• sigma_2 – array containing the noise maps

• format (str) – output format. Choose between npy or fits

• full_psf_position – array containing the position of the full PSF within the original field of view.

This is only relevant when the correction for field distortions is activated (field_distortion was set to ``True`). By default, it is set to (0, 0), i.e. the center of the field of view. :type full_psf_position: array of shape (2,) :param star_positions: array containing the position of the stars that were used for correcting field distortions. It is ignored if field_distortion was set to False. :type star_positions: array of shape (N, 2)

get_amplitudes(kwargs_moffat=None, kwargs_gaussian=None, kwargs_background=None, kwargs_distortion=None)

Returns the photometry of the stars.

Parameters:

• kwargs_moffat – dictionary containing keyword arguments corresponding to the analytic term of the PSF

• kwargs_gaussian – dictionary containing keyword arguments corresponding to the Gaussian deconvolution kernel

• kwargs_background – dictionary containing keyword arguments corresponding to the grid of pixels

• kwargs_distortion – dictionary, default None, not used but listed, so we can do get_amplitudes(**kwargs)

Returns:

list containing the relative photometry

get_astrometry(kwargs_moffat=None, kwargs_gaussian=None, kwargs_background=None, kwargs_distortion=None)

Returns the astrometry. In units of ‘big’ pixel.

Parameters:

• kwargs_moffat – dictionary containing keyword arguments corresponding to the analytic term of the PSF

• kwargs_gaussian – dictionary containing keyword arguments corresponding to the Gaussian deconvolution kernel

• kwargs_background – dictionary containing keyword arguments corresponding to the grid of pixels

• kwargs_distortion – dictionary, default None, not used but listed, so we can do get_amplitudes(**kwargs)

Returns:

list of tuples with format [(x1,y1), (x2,y2), …]

get_background(kwargs_background)

Returns the numerical part of the PSF. This does not include an eventual constant sky background correction stored in kwargs_background[‘mean’].

Parameters:

kwargs_background – dictionary containing keyword arguments corresponding to the grid of pixels

Returns:

array containing the background correction

get_full_psf(kwargs_moffat=None, kwargs_background=None, kwargs_gaussian=None, kwargs_distortion=None, norm=True, high_res=True, position=None)

Returns the PSF of the original image, i.e., the convolution between s, the narrow PSF, and r, the Gaussian kernel.

Parameters:

• kwargs_moffat – dictionary containing keyword arguments corresponding to the analytic term of the PSF

• kwargs_background – dictionary containing keyword arguments corresponding to the grid of pixels

• kwargs_gaussian – dictionary containing keyword arguments related to the gaussian

• kwargs_distortion – dictionary with distortion keywords.

• norm – whether the sum of the pixels in the PSF model should be 1 (default True)

• high_res – whether to return the PSF model in “small pixels” (default True, False is resolution of data)

• position – array of shape (2, ) or tuple (x,y) in case one uses distortion.

Returns:

array containing the full PSF

get_gaussian(init, kwargs_gaussian, kwargs_moffat)

Returns a Gaussian function, adjusted to the star of index init.

Parameters:

• init (int) – stamp index

• kwargs_gaussian – dictionary containing keyword arguments corresponding to the Gaussian deconvolution kernel

• kwargs_moffat – dictionary of arguments in relation to the moffat component.

Returns:

array containing the Gaussian kernel

get_gaussians_vectorized(kwargs_gaussian, kwargs_moffat)

Same as get_gaussian, but doing all the slices at once.

Parameters:

• kwargs_gaussian – dictionary containing keyword arguments corresponding to the Gaussian deconvolution kernel

• kwargs_moffat – dictionary of the arguments of the Moffat. necessary for normalization purposes.

Returns:

2D array containing slices, each with Gaussian kernel at the positions given in kwargs_gaussian. (so, slices of a flattened 2D array, hence 2D)

get_moffat(kwargs_moffat, norm=True)

Returns the analytical part of the PSF.

Parameters:

• kwargs_moffat – dictionary containing keyword arguments corresponding to the analytic term of the PSF

• norm (bool) – normalizes the Moffat

Returns:

array containing the Moffat (2D array)

get_narrow_psf(kwargs_moffat=None, kwargs_background=None, kwargs_gaussian=None, kwargs_distortion=None, norm=True, position=None)

Returns the narrow PSF s, the main model without field distortion. Used by PSF.model

Parameters:

• kwargs_moffat – dictionary containing keyword arguments corresponding to the analytic term of the PSF

• kwargs_background – dictionary containing keyword arguments corresponding to the grid of pixels

• kwargs_gaussian – dictionary with gaussian arguments, listed s.t. we can call get_narrow_psf(**kwargs)

• kwargs_distortion – dictionary of named params related to distortion.

• norm – default (and should always be) True, whether we divide the model by the sum of its pixels

• position – array of shape (2, ) containing x and y coordinates. (Or tuple (x, y))

Returns:

array containing the narrow PSF

get_photometry(kwargs_moffat=None, kwargs_gaussian=None, kwargs_background=None, kwargs_distortion=None, positions=None, high_res=False)

Returns the PSF photometry of all the stars.

Parameters:

• kwargs_moffat – dictionary containing keyword arguments corresponding to the analytic term of the PSF

• kwargs_gaussian – dictionary containing keyword arguments corresponding to the Gaussian deconvolution kernel

• kwargs_background – dictionary containing keyword arguments corresponding to the grid of pixels.

• kwargs_distortion – dictionary, default None, not used but listed, so we can do get_amplitudes(**kwargs)

• positions – array of shape (N, 2), default None: positions of the stars in the original astronomical image, relative to the center of the image, in pixels.

• high_res – bool, whether to use the up-sampled model or not. (should make little difference)

Returns:

array containing the photometry

model(kwargs_moffat, kwargs_gaussian, kwargs_background, kwargs_distortion, positions=None, high_res=False)

Creates the 2D narrow Point Spread Function (PSF) image. star_coordinates is not used if PSF.field_distortion is False. The loss function will handle passing an array of zeros in this case.

Parameters:

• kwargs_moffat – dictionary containing keyword arguments corresponding to the analytic term of the PSF

• kwargs_gaussian – dictionary containing keyword arguments corresponding to the Gaussian deconvolution kernel

• kwargs_background – dictionary containing keyword arguments corresponding to the grid of pixels

• kwargs_distortion – dictionary with keyword arguments corresponding to PSF variation in the field.

• positions – jax array of shape (N, 2): N pairs of coordinate (x,y), one per star. Default None works when PSF instance initialized with field_distortion=False.

• high_res (bool) – returns the up-sampled version of the PSF

Returns:

array containing the model

shifted_gaussians(i, x0, y0)

Generates a 2D array with point sources. Normalized to 1.

Parameters:

• i (int) – current point source index

• x0 – 1D array containing the x positions of the point sources, shift are given in unit of ‘big’ pixels

• y0 – 1D array containing the y positions of the point sources, shift are given in unit of ‘big’ pixels

Returns:

2D array

shifted_gaussians_vectorized(x0, y0)

shifted_gaussian method above vectorized over ‘i’ using broadcasting.

smart_guess(data, fixed_background=True, guess_method='barycenter', masks=None, offset_limit=None, guess_fwhm_pixels=3.0, adjust_sky=False)

Returns an initial guess of the kwargs, given the input data.

Parameters:

• data – array of shape (nimage, npix, npix) containing the input data

• fixed_background (bool) – fixes the background to 0

• guess_method (str) – Method to guess the position of the point sources. Choose between ‘barycenter’ and ‘max’

• masks – array of shape (nimage, npix, npix), booleans. 1 for pixel to use, 0 for pixel to ignore.

• offset_limit (float) – Upper and lower bounds for the center of the star in “big” pixel. Will be used in the kwargs_down/up[‘kwargs_gaussian’][‘x0’], kwargs_down/up[‘kwargs_gaussian’][‘y0’].

• guess_fwhm_pixels (float) – the estimated FWHM of the PSF, is used to initialize the moffat. Default 3.

• adjust_sky (bool) – if True, the constant background is adjusted for each star. Use if you expect that the sky was not uniformely subtracted. Default False. It is still recommended to subtract the sky before using this function.

Returns:

kwargs containing an initial guess of the parameters

starred.psf.psf.apply_distortion(narrow_psf, kwargs_distortion, star_xy_coordinates)

Function used in PSF class above for distortions. Given some coefficients in kwargs_field_distortion, applies to narrow_psf the shear and stretch effective at the star_xy_coordinates position.

Parameters:

• narrow_psf (2d jax array) – the 2d image containing the narrow PSF.

• kwargs_distortion – dictionary with polynomial coefficients, function of image coordinates.

• star_xy_coordinates – array of shape (2, ), i.e. (x, y).

Returns:

the transformed narrow_psf.

starred.psf.psf.load_PSF_model(input_file, format='hdf5')

Load PSF model class from hdf5 or pickle file

starred.psf.psf.shear_stretch_transformation_from_polynomial(kwargs_distortion, star_xy_coordinates)

Function used in PSF class above for distortions. Given the polynomial coefficients in kwargs_field_distortion and the coordinates of the star at hand, yields what the amount of shear and stretch is.

Parameters:

• kwargs_distortion – dictionary with polynomial coefficients, function of image coordinates.

• star_xy_coordinates – tuple or array, (x,y).

Returns:

array of length 3, [dilation_x, dilation_y, shear].

starred.psf.loss module

class starred.psf.loss.Loss(data, psf_class, param_class, sigma_2, N, masks=None, star_positions=None, regularization_terms='l1_starlet', regularization_strength_scales=0, regularization_strength_hf=0, regularization_strength_positivity=0, regularize_full_psf=True, W=None, prior=None)

Bases: object

Class that manages the (auto-differentiable) loss function, defined as: L = - log(likelihood) - log(regularization)

Note that gradient, hessian, etc. are computed in the InferenceBase class.

Parameters:

• data – array containing the observations

• psf_class – Point Spread Function (PSF) class from starred.psf.psf

• param_class – parameters class from starred.psf.parameters

• sigma_2 – array containing the square of the noise maps

• N (int) – number of observations stamps

• masks – array containing the masks for the PSF (if given)

• star_positions – default None, array of shape (N, 2) containing pixel coordinates of the stars (center of the image: (0,0)).

• regularization_terms (str) – information about the regularization terms

• regularization_strength_scales (float) – Lagrange parameter that weights intermediate scales in the transformed domain.

• regularization_strength_hf (float) – Lagrange parameter weighting the highest frequency scale

• regularization_strength_positivity (float) – Lagrange parameter weighting the positivity of the full PSF. 0 means no positivity constraint (recommended).

• regularize_full_psf (bool) – True if you want to regularize the Moffat and the background. False regularizes only the background (recommended)

• W (np.ndarray or jnp.ndarray) – weight matrix. Shape (n_scale, n_pix*subsampling_factor, n_pix*subsampling_factor)

• prior (Prior object) – Prior object, Gaussian prior on parameters to be applied at each step

property data

Returns the observations array.

loss(args)

Defined as the negative log(likelihood*regularization)

property masks

Returns the masks array.

reduced_chi2(kwargs)

Return the reduced chi2, given some model parameters

Parameters:

kwargs – dictionary containing all keyword arguments

property sigma_2

Returns the noise map array.

update_dataset(newdata, newsigma2, newW, newparam_class)

Updates the dataset.

class starred.psf.loss.Prior(prior_gaussian=None, prior_background=None, prior_moffat=None)

Bases: object

Parameters:

• prior_gaussian – list of [param_name, mean, 1-sigma priors]

• prior_background – list of [param_name, mean, 1-sigma priors]

• prior_moffat – list of [param_name, mean, 1-sigma priors]

logL(kwargs)

static prior_kwargs(kwargs, prior)

Return gaussian prior weights

Parameters:

• kwargs – keyword argument

• prior – List containing [param_name, mean, 1-sigma priors]

Returns:

logL

starred.psf.parameters module

class starred.psf.parameters.ParametersPSF(kwargs_init, kwargs_fixed, kwargs_up=None, kwargs_down=None, include_moffat=True)

Bases: Parameters

Point Spread Function parameters class.

Parameters:

• kwargs_init – dictionary with information on the initial values of the parameters

• kwargs_fixed – dictionary containing the fixed parameters

• kwargs_up – dictionary with information on the upper bounds of the parameters

• kwargs_down – dictionary with information on the lower bounds of the parameters

args2kwargs(args)

Obtain a dictionary of keyword arguments from positional arguments.

get_all_free_param_names(kwargs)

get_param_names_for_model(kwargs_key)

Returns the names of the parameters according to the key provided.

kwargs2args(kwargs)

Obtain an array of positional arguments from a dictionary of keyword arguments.

param_names_background = ['background', 'mean']

param_names_distortion = ['dilation_x', 'dilation_y', 'shear']

param_names_gaussian = ['a', 'x0', 'y0']

param_names_moffat = ['fwhm_x', 'fwhm_y', 'phi', 'beta', 'C']

Module contents

This subpackage contains the PSF generation class/es