morphfits.utils.science
=======================

.. py:module:: morphfits.utils.science

.. autoapi-nested-parse::

   Science utility functions for MorphFITS.



Functions
---------

.. autoapisummary::

   morphfits.utils.science.get_pixname_from_scale
   morphfits.utils.science.get_pixscale_from_name
   morphfits.utils.science.get_pixels_from_skycoord
   morphfits.utils.science.get_pixscale
   morphfits.utils.science.get_zeropoint


Module Contents
---------------

.. py:function:: get_pixname_from_scale(pixscale: float) -> str

   Get a resolution name from its corresponding scale.

   :param pixscale: Pixel scale.
   :type pixscale: float

   :returns: Pixel scale as human-readable text.
   :rtype: str


.. py:function:: get_pixscale_from_name(pixname: str) -> float

   Get a resolution scale from its corresponding name.

   :param pixname: Pixel scale as text.
   :type pixname: str

   :returns: Corresponding pixel scale.
   :rtype: float


.. py:function:: get_pixels_from_skycoord(skycoord: astropy.coordinates.SkyCoord, wcs: astropy.wcs.WCS, image_size: int) -> tuple[tuple[int, int], tuple[int, int]]

   TODO May be deleted. Check if unused.

   Calculate corresponding pixels in an image based on sky coordinates and a
   WCS.

   :param skycoord: Position of object in sky.
   :type skycoord: SkyCoord
   :param wcs: Coordinate system from pixel to sky.
   :type wcs: WCS
   :param image_size: Number of pixels along one square image side.
   :type image_size: int

   :returns: Integer pixel coordinates in order of less x, greater x, less y, greater
             y.
   :rtype: tuple[tuple[int, int], tuple[int, int]]


.. py:function:: get_pixscale(science_path: pathlib.Path)

   Get a FICL's pixscale from its science frame.

   Used because not every frame has the same pixel scale. For the most
   part, long wavelength filtered observations have scales of 0.04 "/pix,
   and short wavelength filters have scales of 0.02 "/pix.

   :param science_path: Path to science frame.
   :type science_path: Path

   :raises KeyError: Coordinate transformation matrix element headers missing from frame.


.. py:function:: get_zeropoint(image_path: str | pathlib.Path, magnitude_system: str = 'AB') -> float

   Calculate image zeropoint in passed magnitude system.

   :param image_path: Path to image FITS file.
   :type image_path: str | Path
   :param magnitude_system: Magnitude system to calculate zeropoint from, by default "AB".
   :type magnitude_system: str, optional

   :returns: Zeropoint of image.
   :rtype: float

   :raises NotImplementedError: Magnitude system unknown.

   .. rubric:: Notes

   Image header must contain keys `PHOTFLAM` and `PHOTPLAM`.

   .. rubric:: References

   1. https://www.stsci.edu/hst/instrumentation/acs/data-analysis/zeropoints#:~:text=The%20PHOTFLAM%20and%20PHOTPLAM%20header,TPLAM)%E2%88%92