cutout_fits.cutout
==================

.. py:module:: cutout_fits.cutout


Attributes
----------

.. autoapisummary::

   cutout_fits.cutout._


Classes
-------

.. autoapisummary::

   cutout_fits.cutout.SpatialIndex
   cutout_fits.cutout.SpectralIndex
   cutout_fits.cutout.StokesIndex


Functions
---------

.. autoapisummary::

   cutout_fits.cutout.cutout_beamtable
   cutout_fits.cutout.format_shape
   cutout_fits.cutout.get_cutout_parser
   cutout_fits.cutout.get_cutout_shape
   cutout_fits.cutout.get_file_parser
   cutout_fits.cutout.get_spatial_indices
   cutout_fits.cutout.get_spectral_indices
   cutout_fits.cutout.get_stokes_indices
   cutout_fits.cutout.main
   cutout_fits.cutout.make_cutout
   cutout_fits.cutout.make_slicer
   cutout_fits.cutout.update_header


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

.. py:class:: SpatialIndex

   Bases: :py:obj:`NamedTuple`


   Start and end indices for spatial axes.

   .. attribute:: start_ra_index

      int | None

   .. attribute:: end_ra_index

      int | None

   .. attribute:: start_dec_index

      int | None

   .. attribute:: end_dec_index

      int | None


   .. py:attribute:: end_dec_index
      :type:  int | None

      End index for Dec axis


   .. py:attribute:: end_ra_index
      :type:  int | None

      End index for RA axis


   .. py:attribute:: start_dec_index
      :type:  int | None

      Start index for Dec axis


   .. py:attribute:: start_ra_index
      :type:  int | None

      Start index for RA axis


.. py:class:: SpectralIndex

   Bases: :py:obj:`NamedTuple`


   Start and end indices for spectral axes.

   .. attribute:: start_freq_index

      int | None

   .. attribute:: end_freq_index

      int | None


   .. py:attribute:: end_freq_index
      :type:  int | None

      End index for frequency axis


   .. py:attribute:: start_freq_index
      :type:  int | None

      Start index for frequency axis


.. py:class:: StokesIndex

   Bases: :py:obj:`NamedTuple`


   Start and end indices for Stokes axes.

   .. attribute:: start_stokes_index

      int | None

   .. attribute:: end_stokes_index

      int | None


   .. py:attribute:: end_stokes_index
      :type:  int | None

      End index for Stokes axis


   .. py:attribute:: start_stokes_index
      :type:  int | None

      Start index for Stokes axis


.. py:function:: cutout_beamtable(hdu: astropy.io.fits.BinTableHDU, image_wcs: astropy.wcs.WCS, freq_start_hz: float | None = None, freq_end_hz: float | None = None) -> astropy.io.fits.BinTableHDU

   Cut out a beam table

   :param hdu: HDU with the beam table
   :type hdu: fits.BinTableHDU
   :param image_wcs: WCS of the image that needs beams
   :type image_wcs: WCS
   :param freq_start_hz: Starting frequency cut in Hz. Defaults to None.
   :type freq_start_hz: float | None, optional
   :param freq_end_hz: End frequnecy cut in Hz. Defaults to None.
   :type freq_end_hz: float | None, optional

   :returns: Cutout beam table
   :rtype: fits.BinTableHDU


.. py:function:: format_shape(wcs: astropy.wcs.WCS, shape: tuple[int, Ellipsis]) -> str

   Produce a string representation of the shape of an cube

   :param wcs: Cube WCS
   :type wcs: WCS
   :param shape: Shape of the cube
   :type shape: tuple[int,...]

   :returns: String representation of the shape
   :rtype: str


.. py:function:: get_cutout_parser(parent_parser: bool = False) -> argparse.ArgumentParser

.. py:function:: get_cutout_shape(wcs: astropy.wcs.WCS, slicer: tuple[slice, Ellipsis]) -> tuple[int, Ellipsis]

   Get the shape of a cutout

   :param wcs: WCS of the cutout
   :type wcs: WCS
   :param slicer: Slicer for the cutout
   :type slicer: tuple[slice, ...]

   :returns: Shape of the cutout
   :rtype: tuple[int, ...]


.. py:function:: get_file_parser(parent_parser: bool = False) -> argparse.ArgumentParser

.. py:function:: get_spatial_indices(wcs: astropy.wcs.WCS, centre: astropy.coordinates.SkyCoord, radius: astropy.units.Quantity) -> SpatialIndex

   Get the start and end indices for spatial axes

   :param wcs: WCS for HDU
   :type wcs: WCS
   :param centre: Centre of cutout
   :type centre: SkyCoord
   :param radius: Radius of cutout
   :type radius: u.Quantity

   :returns: start_ra_index, end_ra_index, start_dec_index, end_dec_index
   :rtype: SpatialIndex


.. py:function:: get_spectral_indices(wcs: astropy.wcs.WCS, start_freq: astropy.units.Quantity | None = None, end_freq: astropy.units.Quantity | None = None) -> SpectralIndex

   Get the start and end indices for spectral axes

   :param wcs: WCS for HDU
   :type wcs: WCS
   :param start_freq: Starting frequency. Defaults to None.
   :type start_freq: u.Quantify | None, optional
   :param end_freq: End frequency. Defaults to None.
   :type end_freq: u.Quantify | None, optional

   :returns: start_freq_index, end_freq_index
   :rtype: SpectralIndex


.. py:function:: get_stokes_indices(wcs: astropy.wcs.WCS) -> StokesIndex

   Get the start and end indices for Stokes axes

   :param wcs: WCS for HDU
   :type wcs: WCS

   :returns: start_stokes_index, end_stokes_index
   :rtype: StokesIndex


.. py:function:: main() -> None

.. py:function:: make_cutout(infile: str, outfile: str, ra_deg: float, dec_deg: float, radius_arcmin: float, freq_start_hz: float | None = None, freq_end_hz: float | None = None, overwrite: bool = False) -> astropy.io.fits.HDUList

   Make a cutout of a FITS file

   :param infile: Path to FITS file - can be a remote URL
   :type infile: str
   :param outfile: Path to output file - must be local
   :type outfile: str
   :param ra_deg: Centre RA in degrees
   :type ra_deg: float
   :param dec_deg: Centre Dec in degrees
   :type dec_deg: float
   :param radius_arcmin: Cutout radius in arcminutes
   :type radius_arcmin: float
   :param freq_start_hz: Start frequency in Hz. Defaults to None.
   :type freq_start_hz: float | None, optional
   :param freq_end_hz: End frequency in Hz. Defaults to None.
   :type freq_end_hz: float | None, optional
   :param overwrite: Whether to overwrite the output file.
   :type overwrite: bool

   :returns: Cutout HDUList
   :rtype: fits.HDUList


.. py:function:: make_slicer(wcs: astropy.wcs.WCS, centre: astropy.coordinates.SkyCoord, radius: astropy.units.Quantity, start_freq: astropy.units.Quantity | None = None, end_freq: astropy.units.Quantity | None = None) -> tuple[slice, Ellipsis]

   Create a slicer for a given WCS, centre, radius, and frequency range

   :param wcs: WCS for HDU
   :type wcs: WCS
   :param centre: Centre of cutout
   :type centre: SkyCoord
   :param radius: Radius of cutout
   :type radius: u.Quantity
   :param start_freq: Starting frequency. Defaults to None.
   :type start_freq: u.Quantity | None, optional
   :param end_freq: End frequnecy. Defaults to None.
   :type end_freq: u.Quantity | None, optional

   :returns: Tuple of slices for each axis - in numpy order
   :rtype: Tuple[slice,...]


.. py:function:: update_header(old_header: astropy.io.fits.Header, slicer: tuple[slice, Ellipsis]) -> astropy.io.fits.Header

   Update the header to reflect the cutout

   :param old_header: Original header
   :type old_header: fits.Header
   :param slicer: Slicer for the cutout
   :type slicer: tuple[slice, ...]

   :returns: Cutout header
   :rtype: fits.Header


.. py:data:: _
   :value: False