flint.imageset
==============

.. py:module:: flint.imageset

.. autoapi-nested-parse::

   The images and auxiliary products made by an imager, and operations on sets of them



Classes
-------

.. autoapisummary::

   flint.imageset.ImageSet


Functions
---------

.. autoapisummary::

   flint.imageset.combine_image_set_to_cube
   flint.imageset.form_stokes_i
   flint.imageset.merge_image_sets
   flint.imageset.split_and_get_image_set
   flint.imageset.split_image_set
   flint.imageset.transpose_and_sort_channel_images
   flint.imageset.write_stokes_i


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

.. py:class:: ImageSet(/, **data: Any)

   Bases: :py:obj:`flint.options.BaseOptions`


   A structure to represent the images and auxiliary products produced by an imager


   .. py:attribute:: dirty
      :type:  list[pathlib.Path] | None
      :value: None


      Dirty images.


   .. py:attribute:: image
      :type:  list[pathlib.Path]

      Images produced.


   .. py:attribute:: model
      :type:  list[pathlib.Path] | None
      :value: None


      Model images.


   .. py:attribute:: prefix
      :type:  str

      Prefix of the images and other output products. For wsclean this is its -name argument


   .. py:attribute:: psf
      :type:  list[pathlib.Path] | None
      :value: None


      References to the PSFs produced by the imager.


   .. py:attribute:: residual
      :type:  list[pathlib.Path] | None
      :value: None


      Residual images.


   .. py:attribute:: source_list
      :type:  pathlib.Path | None
      :value: None


      Path to a source list that accompanies the image data


.. py:function:: combine_image_set_to_cube(image_set: ImageSet, fitscube_options: flint.options.FitsCubeOptions) -> ImageSet

   Combine wsclean subband channel images into a cube. Each collection attribute
   of the input `image_set` will be inspected. The MFS images will be ignored.

   A output file name will be generated based on the  prefix and mode (e.g. `image`, `residual`, `psf`, `dirty`).

   :param image_set: Collection of wsclean image productds
   :type image_set: ImageSet
   :param fitscube_options: Options to control the cube creation, forwarded to ``combine_images_to_cube`` for each mode
   :type fitscube_options: FitsCubeOptions

   :returns: Updated iamgeset describing the new outputs
   :rtype: ImageSet


.. py:function:: form_stokes_i(image_set: ImageSet) -> ImageSet

   Replace the XX and YY images of an image set by Stokes I.

   Each XX image pairs with the YY image named the same but for its ``xx`` field,
   and I is named with ``i`` there. The prefix and the PSF, which XX and YY share,
   are renamed likewise. Raises ``NamingException`` if the images are not all in
   pairs. The XX and YY images are left for the caller.


.. py:function:: merge_image_sets(image_sets: list[ImageSet]) -> ImageSet

   Merge the image sets from multiple wsclean results into a single image set.

   :param wsclean_results: The results of multiple wsclean imaging runs
   :type wsclean_results: List[WSCleanResult]

   :returns: The merged image set
   :rtype: ImageSet


.. py:function:: split_and_get_image_set(image_set: ImageSet, get: str, by: str = 'pol', mode: str = 'image') -> list[pathlib.Path]

   Split an ImageSet by a given field and return the images that match the field of interest.

   :param image_set: The ImageSet to split
   :type image_set: ImageSet
   :param get: The field to extract from the split images
   :type get: str
   :param by: The field to split by. Defaults to "pol".
   :type by: str, optional
   :param mode: The mode to extract from ImageSet. Defaults to "image".
   :type mode: str, optional

   :raises NamingException: If the field to split by is not found in the ImageSet

   :returns: The images that match the field of interest
   :rtype: list[Path]


.. py:function:: split_image_set(image_set: ImageSet, by: str = 'pol', mode: str = 'image') -> dict[str, list[pathlib.Path]]

   Split an ImageSet by a given field.

   :param image_set: The ImageSet to split
   :type image_set: ImageSet
   :param by: Field to split images by. Defaults to "pol".
   :type by: str, optional
   :param mode: Type of images to extract from ImageSet. Defaults to "image".
   :type mode: str, optional

   :raises NamingException: If the field to split by is not found in the ImageSet

   :returns: _description_
   :rtype: dict[str, list[Path]]


.. py:function:: transpose_and_sort_channel_images(beam_channel_images: list[list[pathlib.Path]]) -> list[list[pathlib.Path]]

   Regroup per-beam lists of sub-band channel images into per-channel lists
   of beam images, ready to be co-added one channel at a time.

   Each beam's images are sorted by their channel range, and every beam must
   contribute the same number of channels.

   :param beam_channel_images: For each beam, the list of its per-channel images.
   :type beam_channel_images: list[list[Path]]

   :returns: For each channel, the list of beam images at that channel.
   :rtype: list[list[Path]]


.. py:function:: write_stokes_i(xx_path: pathlib.Path, yy_path: pathlib.Path, i_path: pathlib.Path) -> pathlib.Path

   Write I = (XX + YY) / 2 to ``i_path``, raising ``ValueError`` if the restoring beams differ