flint.source_finding.aegean
===========================

.. py:module:: flint.source_finding.aegean

.. autoapi-nested-parse::

   A basic interface into aegean source finding routines.



Classes
-------

.. autoapisummary::

   flint.source_finding.aegean.AegeanOptions
   flint.source_finding.aegean.AegeanOutputs
   flint.source_finding.aegean.BANEOptions


Functions
---------

.. autoapisummary::

   flint.source_finding.aegean._bane_output_callback
   flint.source_finding.aegean._get_aegean_command
   flint.source_finding.aegean._get_bane_command
   flint.source_finding.aegean.cli
   flint.source_finding.aegean.get_parser
   flint.source_finding.aegean.run_bane_and_aegean


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

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

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


   Container for basic aegean options. Only a subclass of aegean options are supported.

   Of note is the lack of a tables option (corresponding to --tables). This is dependent on knowing the base output name
   and relying on aegean to also append a suffix of sorts to the outputs. For that reason
   the aegean command generated will always create the table option.


   .. py:attribute:: autoload
      :type:  bool
      :value: True


      Attempt to load precomputed background and rms maps.


   .. py:attribute:: maxsummits
      :type:  int
      :value: 4


      The maximum number of components an island is allowed to have before it is ignored.


   .. py:attribute:: nocov
      :type:  bool
      :value: True


      Whether aegean should attempt to model the co-variance of pixels. If true aegean does not.


.. py:class:: AegeanOutputs

   Bases: :py:obj:`NamedTuple`


   Somple structure to represent output aegean products


   .. py:attribute:: beam_shape
      :type:  tuple[float, float, float]

      The `BMAJ`, `BMIN` and `BPA` that were stored in the image header that Aegen searched


   .. py:attribute:: bkg
      :type:  pathlib.Path

      Background map created by BANE


   .. py:attribute:: comp
      :type:  pathlib.Path

      Source component catalogue created by Aegean


   .. py:attribute:: image
      :type:  pathlib.Path

      The input image that was used to source find against


   .. py:attribute:: rms
      :type:  pathlib.Path

      RMS map created by BANE


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

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


   Container for basic BANE related options. Only a subclass of BANE options are supported.


   .. py:attribute:: box_size
      :type:  tuple[int, int] | None
      :value: (196, 196)


      The size of the box in pixels


   .. py:attribute:: cores
      :type:  int
      :value: 12


      Number of cores to use. The number of stripes will be less than this number.


   .. py:attribute:: grid_size
      :type:  tuple[int, int] | None
      :value: (16, 16)


      The step interval of each box, in pixels


.. py:function:: _bane_output_callback(line: str) -> None

   Callback handler for the BANE program. Will raise an error
   on the 'deadlock' issue.


.. py:function:: _get_aegean_command(image: pathlib.Path, base_output: str, aegean_options: AegeanOptions) -> str

   Create the aegean command to run


.. py:function:: _get_bane_command(image: pathlib.Path, bane_options: BANEOptions) -> str

   Create the BANE command to run


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

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

.. py:function:: run_bane_and_aegean(image: pathlib.Path, aegean_container: pathlib.Path, bane_options: BANEOptions | None = None, aegean_options: AegeanOptions | None = None, update_bane_options: dict[str, Any] | None = None, update_aegean_options: dict[str, Any] | None = None) -> AegeanOutputs

   Run BANE, the background and noise estimator, and aegean, the source finder,
   against an input image. This function attempts to hook into the AegeanTools
   module directly, which does not work with dask daemon processes.

   :param image: The input image that BANE will calculate a background and RMS map for
   :type image: Path
   :param aegean_container: Path to a singularity container that was the AegeanTools packages installed.
   :type aegean_container: Path
   :param bane_options: The options that are provided to BANE. If None defaults of BANEOptions are used. Defaults to None.
   :type bane_options: Optional[BANEOptions], optional
   :param aegean_options: The options that are provided to Aegean. if None defaults of AegeanOptions are used. Defaults to None.
   :type aegean_options: Optional[AegeanOptions], optional
   :param update_bane_options: Over-ride any default options of BANEOptions. If None defaults are used. Defaults to None.
   :type update_bane_options: dict[str, Any] | None, optional
   :param update_aegean_options: Over-ride any default options of AegeanOptions. If None defaults are used. Defaults to None.
   :type update_aegean_options: dict[str, Any] | None, optional

   :returns: The newly created BANE products
   :rtype: AegeanOutputs