yippy.util

yippy.util#

Utility functions for the yippy package.

Functions#

convert_to_lod(x[, center_pix, pixel_scale_arcsec, ...])

Convert the x/y position to lambda/D.

convert_to_pix(x, center_pix, pixel_scale_arcsec[, ...])

Convert the x/y position from lambda/D to pixel units.

save_coro_performance_to_fits(sep, throughput, ...[, ...])

Save coronagraph performance (throughput, raw_contrast) to a FITS file.

load_coro_performance_from_fits(filename, indir)

Load (separation, throughput, raw_contrast) from a FITS file.

extract_and_oversample_subarray(psf_img, center_x, ...)

Get oversampled subarray of the PSF image around a given center.

measure_flux_in_oversampled_aperture(subarr_oversamp, ...)

Get flux in a circular aperture of radius radius_os in the oversampled array.

crop_around_peak(arr, radius)

Crop a 2D array to a square region centered on the peak pixel.

create_shift_mask(psf, shift_x, shift_y[, fill_val])

Create a mask to identify valid pixels to average.

Module Contents#

yippy.util.convert_to_lod(x, center_pix=None, pixel_scale_arcsec=None, lam=None, D=None, dist=None)[source]#

Convert the x/y position to lambda/D.

This function has the following assumptions on the x/y values provided:

  • If units are pixels, they follow the 00LL convention. As in the (0,0) point is the lower left corner of the image.

  • If the x/y values are in lambda/D, angular, or length units the

    (0,0) point is the center of the image, where the star is (hopefully) located.

Args:
x (astropy.units.Quantity):

Position. Can be units of pixel, an angular unit (e.g. arcsec), or a length unit (e.g. AU)

center_pix (astropy.units.Quantity):

Center of the image in pixels (for the relevant axis)

pixel_scale_arcsec (astropy.units.Quantity):

Pixel scale of in

lam (astropy.units.Quantity):

Wavelength of the observation

D (astropy.units.Quantity):

Diameter of the telescope

dist (astropy.units.Quantity):

Distance to the system

Parameters:

x (astropy.units.Quantity)

Return type:

astropy.units.Quantity

yippy.util.convert_to_pix(x, center_pix, pixel_scale_arcsec, lam=None, D=None, dist=None)[source]#

Convert the x/y position from lambda/D to pixel units.

This function has the following assumptions on the x/y values provided:

  • If the desired output is in pixels, the (0,0) point is the lower left corner of the image.

  • If the x/y values are in lambda/D, angular, or length units, the (0,0) point is the center of the image, where the star is (hopefully) located.

Args:
x (astropy.units.Quantity):

Position to convert. Should be in units of lambda/D, an angular unit (e.g., arcsec), or a length unit (e.g., AU).

center_pix (astropy.units.Quantity, optional):

Center of the image in pixels (for the relevant axis). Required if converting to pixel units.

pixel_scale_arcsec (astropy.units.Quantity, optional):

Pixel scale in units of lambda/D per pixel. Required if converting to pixel units.

lam (astropy.units.Quantity, optional):

Wavelength of the observation. Required if converting from angular or length units to pixel units.

D (astropy.units.Quantity, optional):

Diameter of the telescope. Required if converting from angular or length units to pixel units.

dist (astropy.units.Quantity, optional):

Distance to the system. Required if converting from length units to pixel units.

Returns:
astropy.units.Quantity:

Position in pixel units.

Raises:
AssertionError:

If required parameters for the conversion are not provided or have incorrect units.

ValueError:

If the input unit type is not supported for conversion.

Parameters:

x (astropy.units.Quantity)

Return type:

astropy.units.Quantity

yippy.util.save_coro_performance_to_fits(sep, throughput, raw_contrast, filename, outdir, overwrite=True)[source]#

Save coronagraph performance (throughput, raw_contrast) to a FITS file.

Parameters:
yippy.util.load_coro_performance_from_fits(filename, indir)[source]#

Load (separation, throughput, raw_contrast) from a FITS file.

Parameters:
yippy.util.extract_and_oversample_subarray(psf_img, center_x, center_y, radius_pix, oversample)[source]#

Get oversampled subarray of the PSF image around a given center.

Extract a subarray of psf_img around (center_x, center_y), then oversample that subarray by the specified factor.

Args:
psf_img (np.ndarray):

The input PSF image

center_x (float):

Position of the center in the x direction

center_y (float):

Position of the center in the y direction

radius_pix (float):

The radius of the subarray in pixels

oversample (int):

The oversampling factor

Returns:
subarr_oversamp (np.ndarray):

The oversampled subarray

center_x_os (float):

center_x in oversampled subarray coords

center_y_os (float):

center_y in oversampled subarray coords

radius_os (float):

radius_pix * oversample

subarr (np.ndarray):

the original subarray (for flux renormalization)

Parameters:
yippy.util.measure_flux_in_oversampled_aperture(subarr_oversamp, center_x_os, center_y_os, radius_os, subarr_original)[source]#

Get flux in a circular aperture of radius radius_os in the oversampled array.

Returns:

flux_in_ap (float): total flux inside the circular mask

Parameters:
Return type:

float

yippy.util.crop_around_peak(arr, radius)[source]#

Crop a 2D array to a square region centered on the peak pixel.

The output is always square with side length 2 * r where r is the largest feasible radius that fits within the array bounds (capped at the requested radius). This function is mostly used in the documentation animations.

Args:

arr (np.ndarray): 2D input array. radius (int): Desired half-width of the output crop in pixels.

Returns:

np.ndarray: Square cropped subarray centered on the peak.

yippy.util.create_shift_mask(psf, shift_x, shift_y, fill_val=1)[source]#

Create a mask to identify valid pixels to average.

This function is useful because when the PSF is shifted there are empty pixels, since they were outside the initial image, and should not be included in the final average.

Args:
psf (np.ndarray):

The PSF image to shift.

shift_x (float):

The shift in the x direction.

shift_y (float):

The shift in the y direction.

fill_val (float, optional):

The value to fill the mask with.

Returns:
np.ndarray:

The mask to identify valid pixels to average.