flint.convol
============

.. py:module:: flint.convol

.. autoapi-nested-parse::

   Tooling related to the convolution of images. Principally
   this is mostly to smooth to a common resolution



Classes
-------

.. autoapisummary::

   flint.convol.BeamShape


Functions
---------

.. autoapisummary::

   flint.convol.check_if_cube_fits
   flint.convol.cli
   flint.convol.convolve_cubes
   flint.convol.convolve_images
   flint.convol.get_common_beam
   flint.convol.get_cube_common_beam
   flint.convol.get_parser


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

.. py:class:: BeamShape

   Bases: :py:obj:`NamedTuple`


   A simple container to represent a fitted 2D gaussian,
   intended for the main lobe of the synthesised beam. This
   class has been defined to avoid issues with the serialisation
   of astropy.units, which can cause strange and wonderful
   errors when being sent over the wire to workers.


   .. py:method:: from_radio_beam(radio_beam: radio_beam.Beam) -> BeamShape
      :classmethod:


      A helper function to convert a radio_beam.Beam into a
      BeamShape. This is prinicpally intended to be used when
      there is a need to exchange a Beam between processes
      that would need to serialise the object.

      :param radio_beam: The Beam to convert to normalised and known units
      :type radio_beam: Beam

      :returns: The normalised container without astropy units.
      :rtype: BeamShape



   .. py:attribute:: bmaj_arcsec
      :type:  float

      The size of the major-axis of the beam, in arcseconds.


   .. py:attribute:: bmin_arcsec
      :type:  float

      The size of the minor-axis of the beam, in arcseconds.


   .. py:attribute:: bpa_deg
      :type:  float

      Rotation of the beam, in degrees.


.. py:function:: check_if_cube_fits(fits_file: pathlib.Path) -> bool

   Check to see whether the data component of a FITS images is a cube.
   Returns ``True`` is the data-shape needs 3-dimensions to be represented.

   Note: Unclear on usefulness

   :param fits_file: FITS file that will be examinined
   :type fits_file: Path

   :returns: Whether the input FITS file is a cube or not.
   :rtype: bool


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

.. py:function:: convolve_cubes(cube_paths: Collection[pathlib.Path], beam_shapes: list[BeamShape], cutoff: float | None = None, convol_suffix: str = 'conv', executor_type: Literal['thread', 'process', 'mpi'] = 'thread') -> Collection[pathlib.Path]

.. py:function:: convolve_images(image_paths: Collection[pathlib.Path], beam_shape: BeamShape, cutoff: float | None = None, convol_suffix: str = 'conv', output_paths: list[pathlib.Path] | None = None) -> list[pathlib.Path]

   Convolve a set of input images to a common resolution as specified
   by the beam_shape. If the major-axis of the native resolution is larger
   than cutoff (in arcseconds) then the racs_tools beamconv_2D task will
   nan it.

   Additionally, some input subject image will simply copied if:

   * the input ``beam_shape`` is not finite, or
   * the beamshape encoded in the FITS header of the subject image is not defined

   :param image_paths: Set of image paths to FITS images to convol
   :type image_paths: Collection[Path]
   :param beam_shape: The specification of the desired final resolution
   :type beam_shape: BeamShape
   :param cutoff: Images whose major-axis is larger than this will be blank. Expected in arcseconds. Defaults to None.
   :type cutoff: Optional[float], optional
   :param convol_suffix: The suffix added to .fits to indicate smoothed image. Defaults to 'conv'.
   :type convol_suffix: str, optional
   :param output_paths: The final output file namesfor each input image. If provided this renamed files created using the `convol_suffix`. Defaults to None.
   :type output_paths: list[Path] | None, optional

   :returns: Set of paths to the smoothed images
   :rtype: Collection[Path]


.. py:function:: get_common_beam(image_paths: Collection[pathlib.Path], cutoff: float | None = None) -> BeamShape

   Return the minimum beam size required to encompass the beams described
   in the FITS header (e.g. BMAJ,BMIN,BPA) of the input images. This is used
   when preparing to convolve to a common resolution.

   :param image_paths: The paths to the FITS images that will be examined.
   :type image_paths: Collection[Path]
   :param cutoff: The maximum beam size an input image is allowed to have. BMAJ's larger than this are ignored from the calculation. Defaults to None.
   :type cutoff: Optional[float], optional

   :returns: Smalled common beam available to be used
   :rtype: BeamShape


.. py:function:: get_cube_common_beam(cube_paths: Collection[pathlib.Path], cutoff: float | None = None) -> list[BeamShape]

   Given a set of input cube FITS files, compute a common beam
   for each channel.

   :param cube_paths: Set of cube FITS files to inspect to derive a common beam
   :type cube_paths: Collection[Path]
   :param cutoff: A cutoff value, in arcsec, that specifies the maximum BMAJ allowed. Defaults to None.
   :type cutoff: Optional[float], optional

   :returns: List of target beam shapes to use, corresponding to each channel
   :rtype: List[BeamShape]


.. py:function:: get_parser() -> argparse.ArgumentParser