furry_parakeet.pyimcom_interface

Interface functions (mostly to be called from pyimcom, but could be from somewhere else).

Functions

psf_gaussian

Makes a Gaussian spot.

psf_simple_airy

Makes an possibly obstructed Airy spot, convolved with tophat and Gaussian.

psf_cplx_airy

Complex Airy function with some features printed on.

rotation

Rotation matrix in 2D.

shearmatrix

Makes a shear matrix with unit determinant.

get_coadd_matrix

Convert PSF overlap object to transfer matrices.

bilinear_interpolation

Forward bilinear interpolation on a grid.

bilinear_transpose

Transpose bilinear interpolation on a grid.

Classes

PSF_Overlap

Correlation matrices of all the PSFs.

Classes

PSF_Overlap

Correlation matrices of all the PSFs.

Functions

psf_gaussian(n, sigmax, sigmay)

Makes a Gaussian spot.

psf_simple_airy(n, ldp[, obsc, tophat_conv, sigma])

Makes an possibly obstructed Airy spot, convolved with tophat and Gaussian.

psf_cplx_airy(n, ldp[, tophat_conv, sigma, features])

Complex Airy function with some features printed on.

rotmatrix(theta)

Rotation matrix in 2D.

shearmatrix(g1, g2)

Makes a shear matrix with unit determinant.

get_coadd_matrix(psfobj, psf_oversamp_factor, ...[, ...])

Convert PSF overlap object to transfer matrices.

test_psf_inject(psf_in_list, psf_out_list, ...)

Create input postage stamps of point sources of unit flux and coadd them to test the PSF matrices.

bilinear_interpolation(inimage, gain, coords, outimage)

Bilinear interpolation.

bilinear_transpose(inimage, coords, outimage)

Transpose of bilinear interpolation.

Module Contents

psf_gaussian(n, sigmax, sigmay)[source]

Makes a Gaussian spot.

Parameters:

  • n (int) – Size of the spot.

  • sigmax (float) – Standard deviation along the x-axis.

  • sigmay (float) – Standard deviation along the y-axis.

Returns:

2D image, shape =(n, n), normalized to unity.

Return type:

np.array

psf_simple_airy(n, ldp, obsc=0.0, tophat_conv=0.0, sigma=0.0)[source]

Makes an possibly obstructed Airy spot, convolved with tophat and Gaussian.

Parameters:

  • n (int) – Size of the spot.

  • ldp (float) – Diffraction width, lambda / D, in units of the pixel.

  • obsc (float, optional) – Fractional linear obscuration, default = unobstructed.

  • tophat_conv (float, optional) – Full width of square tophat, in units of the pixel.

  • sigma (float, optional) – Standard deviation per axis of the Gaussian contribution, in units of the pixel.

Returns:

2D image, shape =(n, n), normalized to unity if analytically extended.

Return type:

np.array

Notes

The output is centered on (n-1)/2,(n-1)/2 (so on a pixel if n is odd and a corner if n is even).

psf_cplx_airy(n, ldp, tophat_conv=0.0, sigma=0.0, features=0)[source]

Complex Airy function with some features printed on.

Everything is band limited.

Parameters:

  • n (int) – Size of the spot.

  • ldp (float) – Diffraction width, lambda / D, in units of the pixel.

  • obsc (float, optional) – Fractional linear obscuration, default = unobstructed.

  • tophat_conv (float, optional) – Full width of square tophat, in units of the pixel.

  • sigma (float, optional) – Standard deviation per axis of the Gaussian contribution, in units of the pixel.

  • features (int, optional) – If specified, determines what features get added.

Returns:

2D image, shape =(n, n), normalized to unity if analytically extended.

Return type:

np.array

Notes

The output is centered on (n-1)/2,(n-1)/2 (so on a pixel if n is odd and a corner if n is even).

rotmatrix(theta)[source]

Rotation matrix in 2D.

Parameters:

theta (float) – Rotation angle in radians.

Returns:

Shape (2, 2) rotation matrix.

Return type:

np.array of float

Notes

The convention is that X(stacking frame) = (distortion_matrix) @ X(native frame).

In ds9 the native frame is angle theta clockwise from stacking frame (i.e., theta is position angle of the native frame).

shearmatrix(g1, g2)[source]

Makes a shear matrix with unit determinant.

Parameters:

  • g1 (float) – The “stretch along x-axis” component of shear.

  • g2 (float) – The “stretch along y=x” component of shear.

Returns:

Shape (2, 2) rotation matrix.

Return type:

np.array of float

class PSF_Overlap(psf_in_list, psf_out_list, dsample, nsample, s_in, distort_matrices=None, amp_penalty=None)[source]

Correlation matrices of all the PSFs.

Parameters:

  • psf_in_list (list of np.array) – The list of input PSFs (length n_in).

  • psf_out_list (list of np.array) – The list of output PSFs (length n_out).

  • dsample (float) – Sample spacing of the correlation matrices in terms of input pixels.

  • nsample (int) – Number of output samples on each axis. Must be odd.

  • s_in (float) – Input reference pixel scale.

  • distort_matrices (list of np.array, optional) – The 2x2 distortion matrices associated with the input PSFs (length n_in), in the form X(stacking frame) = (distortion_matrix[j]) @ X(native frame[j]). Default is no distortion.

  • amp_penalty (dict, optional) – Experimental feature to change the weighting of Fourier modes (do not use or set to None unless you are trying to do a test with it). The dictionary should contain “amp” and “sig” attributes for the amplitude and width of region with higher weighting in IMCOM’s error metric.

n_in[source]

Number of input PSFs.

Type:

int

n_out[source]

Number of output PSFs.

Type:

int

n_tot[source]

Total number of PSFs, equal to n_in + n_out.

Type:

int

psfarray

3D array of PSFs, distorted if needed, shape (n_tot, ns2, ns2) (the padding size ns2 is determined internally).

Type:

np.array

overlaparray[source]

4D overlap array, shape (n_tot, n_tot, nsample, nsample)

Type:

np.array

C[source]

Square norms of the output PSFs, shape (n_out).

Type:

np.array

s_in[source]
n_in[source]
n_out[source]
n_tot[source]
dsample[source]
nsample[source]
nc[source]
overlaparray[source]
psf_array[source]
C[source]
get_coadd_matrix(psfobj, psf_oversamp_factor, targetleak, ctrpos, distort_matrices, in_stamp_dscale, in_stamp_shape, out_stamp_dscale, out_stamp_shape, in_mask, tbdy_radius, smax=1.0, flat_penalty=0.0, use_kappa_arr=None, choose_outputs='CKMSTU')[source]

Convert PSF overlap object to transfer matrices.

Parameters:

  • psfobj (furry_parakeet.pyimcom_interface.PSF_Overlap) – The PSF overlap class object.

  • psf_oversamp_factor (float) – The PSF oversampling factor relative to native pixel scale.

  • targetleak (np.array of float) – The target leakage U/C, length n_out (same as number of output PSFs in psfobj).

  • ctrpos (list of (float, float)) – Length n_in list of postage stamp centroids in the stacking frame, in (x,y) ordering.

  • distort_matrices (list of np.array) – List (length n_in) of shape (2, 2) matrices. None can be used if there is no distortion.

  • in_stamp_dscale (float) – Input postage stamp scale.

  • in_stamp_shape ((int, int)) – Input postage stamp shape, length 2 tuple in the form (ny_in, nx_in).

  • out_stamp_dscale (float) – Output postage stamp scale.

  • out_stamp_shape ((int, int)) – Output postage stamp shape, length 2 tuple in the form (ny_out, nx_out).

  • in_mask (np.array of bool) – Mask, True represents a good pixel. The shape is (n_in, ny_in, nx_in). Set to None to accept all pixels.

  • tbdy_radius (float) – Radius of boundary to clip pixels in input images.

  • smax (float, optional) – Maximum allowed value of noise factor Sigma (default = 1 if you want to avoid amplifying noise).

  • flat_penalty (float, optional) – Amount by which to penalize having different contributions to the output from different input images (not recommended).

  • use_kappa_arr (np.array of float, optional) – If supplied, array of kappa must be in ascending order (length nv in Cao et al. 2024) for Cholesky decompositions.

  • choose_outputs (str, optional) – Which outputs to report (see notes for options and defualts), each option is coded by a character in the string.

Returns:

Dictionary containing some or all of the keys ‘A’, ‘mBhalf’, ‘C’, ‘kappa’, ‘fullmask’, ‘Sigma’, ‘T’, and ‘UC’ (see notes for description).

Return type:

dict

Notes

The option characters for choose_outputs, the corresponding keys in the output dictionaries, and desciptions are:

  • A : 'A', np.array, IMCOM system matrices (input-input overlap)

    Shape (n_all, n_all), where n_all is the total number of accepted pixels

  • B : 'mBhalf', np.array, IMCOM transfer matrices (input-output overlap), -0.5*B in Rowe et al. 2011.

    Shape (n_out, nx_out * ny_out, n_all)

  • C : 'C', np.array, IMCOM target normalizations (output-output overlap)

    Shape (n_out)

  • K : 'kappa', np.array, Lagrange multiplier

    Shape (n_out, ny_out, nx_out)

  • M : 'fullmask', np.array, coaddition input pixel mask

    Shape (n_in, ny_in, nx_in)

  • S : 'Sigma', np.array, IMCOM noise amplification map

    Shape (n_out, ny_out, nx_out)

  • T = coaddition matrix, np.array, IMCOM transfer matrix

    Shape (n_out, ny_out, nx_out, n_in, ny_in, nx_in)

  • U : 'UC', np.array PSF leakage map (U_alpha/C)

    Shape (n_out, ny_out, nx_out)

A and B are large and you probably only want them for test cases. The default choice is 'CKMSTU'.

test_psf_inject(psf_in_list, psf_out_list, psf_oversamp_factor, ctrpos, distort_matrices, T, in_mask, in_stamp_dscale, out_stamp_dscale, srcpos)[source]

Create input postage stamps of point sources of unit flux and coadd them to test the PSF matrices.

Parameters:

  • psf_in_list (list of np.array) – List of input PSFs (length n_in, each is a 2D array).

  • psf_out_list (list of np.array) – List of output PSFs (length n_out, each is a 2D array).

  • psf_oversamp_factor (float) – PSF oversampling factor relative to native pixel scale (usually >1).

  • ctrpos (list of (float, float)) – List (length n_in) of postage stamp centroids in stacking frame, (x,y) ordering.

  • distort_matrices (list of np.array) – List (length n_in) of shape (2, 2) matrices.

  • T (np.array) – Coaddition matrix, shape = (n_out, ny_out, nx_out, n_in, ny_in, nx_in).

  • in_mask (np.array of bool) – Mask, True represents a good pixel. The shape is (n_in, ny_in, nx_in). Set to None to accept all pixels.

  • in_stamp_dscale (float) – Input postage stamp scale.

  • out_stamp_dscale (float) – Output postage stamp scale.

  • srcpos ((float, float)) – Position of the point source to inject, (x,y) ordering.

Returns:

  • in_array (np.array) – Input postage stamps, shape = (n_in, ny_in, nx_in)

  • out_array (np.array) – output postage stamp, shape = (n_out, ny_out, nx_out)

  • diff_array (np.array) – output postage stamp error, shape = (n_out, ny_out, nx_out)

bilinear_interpolation(inimage, gain, coords, outimage)[source]

Bilinear interpolation.

The basic idea is (in pseudocode):

``outimage[j, i]`` += interpolation of `inimage` * `gain` to position

y = coords[j, i, 0]
x = coords[j, i, 1]

Skips a point if (x, y) is off the edge of the image.

Parameters:

  • inimage (np.ndarray of float) – The input image as a 2D array. Shape (nrows, ncols).

  • gain (np.ndarray of float) – The gain map, same shape as inimage.

  • coords (np.ndarray of float) – The coordinate grid, shape (nrows * ncols, 2) or (nrows, ncols, 2). The last axis has length 2 (y first, then x).

  • outimage (np.ndarray of float) – The output image to add to. Same shape as inimage.

Return type:

None

bilinear_transpose(inimage, coords, outimage)[source]

Transpose of bilinear interpolation.

The basic idea is (in pseudocode):

`inimage` at (x, y) interpolated onto ``outimage[j, i]`` by cloud-in-cell

y = coords[j, i, 0]
x = coords[j, i, 1]

Skips a point if (x, y) is off the edge of the image.

Parameters:

  • inimage (np.ndarray of float) – The input image as a 2D array. Shape (nrows, ncols).

  • coords (np.ndarray of float) – The coordinate grid, shape (nrows * ncols, 2) or (nrows, ncols, 2). The last axis has length 2 (y first, then x).

  • outimage (np.ndarray of float) – The output image to add to. Same shape as inimage.

Return type:

None