yippy.util ========== .. py:module:: yippy.util .. autoapi-nested-parse:: Utility functions for the yippy package. Functions --------- .. autoapisummary:: yippy.util.convert_to_lod yippy.util.convert_to_pix yippy.util.save_coro_performance_to_fits yippy.util.load_coro_performance_from_fits yippy.util.extract_and_oversample_subarray yippy.util.measure_flux_in_oversampled_aperture yippy.util.crop_around_peak yippy.util.create_shift_mask Module Contents --------------- .. py:function:: convert_to_lod(x, center_pix=None, pixel_scale_arcsec=None, lam=None, D=None, dist=None) 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 .. py:function:: convert_to_pix(x, center_pix, pixel_scale_arcsec, lam=None, D=None, dist=None) 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. .. py:function:: save_coro_performance_to_fits(sep, throughput, raw_contrast, filename, outdir, overwrite=True) Save coronagraph performance (throughput, raw_contrast) to a FITS file. .. py:function:: load_coro_performance_from_fits(filename, indir) Load (separation, throughput, raw_contrast) from a FITS file. .. py:function:: extract_and_oversample_subarray(psf_img, center_x, center_y, radius_pix, oversample) 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) .. py:function:: measure_flux_in_oversampled_aperture(subarr_oversamp, center_x_os, center_y_os, radius_os, subarr_original) 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 .. py:function:: crop_around_peak(arr, radius) 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. .. py:function:: create_shift_mask(psf, shift_x, shift_y, fill_val=1) 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.