flint.flagging
==============

.. py:module:: flint.flagging

.. autoapi-nested-parse::

   Utility functions to carry out flagging against ASKAP measurement sets



Classes
-------

.. autoapisummary::

   flint.flagging.AOFlaggerCommand


Functions
---------

.. autoapisummary::

   flint.flagging._nan_zero_extreme_flag
   flint.flagging.cli
   flint.flagging.create_aoflagger_cmd
   flint.flagging.flag_ms_aoflagger
   flint.flagging.flag_ms_by_antenna_ids
   flint.flagging.flag_ms_zero_uvws
   flint.flagging.get_parser
   flint.flagging.nan_zero_extreme_flag_ms
   flint.flagging.run_aoflagger_cmd


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

.. py:class:: AOFlaggerCommand

   Bases: :py:obj:`NamedTuple`


   The command to use when running aoflagger


   .. py:attribute:: cmd
      :type:  str

      The command that will be executed


   .. py:attribute:: ms
      :type:  flint.options.MS

      The MS object that was flagged


   .. py:attribute:: ms_path
      :type:  pathlib.Path

      The path to the MS that will be flagged.


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


      The path to the aoflagging strategy file to use


.. py:function:: _nan_zero_extreme_flag(data: numpy.typing.NDArray[numpy.complex128], flags: numpy.typing.NDArray[numpy.bool], uvws: numpy.typing.NDArray[numpy.float64], flag_extreme_dxy: bool = True, dxy_thresh: float = 4.0) -> tuple[numpy.typing.NDArray[numpy.complex128], numpy.typing.NDArray[numpy.bool], numpy.typing.NDArray[numpy.float64]]

   Used to evaluate the flags that should be applied to the MS based on
   data values (if there are 0's or nans), uvw values (which can be 0's) and
   extreme stokes-v values.

   This is the internal checker for the larger `nan_zero_extreme_flags_in_ms`
   function.

   :param data: Data that is being consider drawn from a `DATA` like column
   :type data: NDArray[np.complex128]
   :param flags: The flags that correspond to the `DATA` column drawn from the `FLAG` column
   :type flags: NDArray[np.bool]
   :param uvws: The (U,V,W) coordinates of the data
   :type uvws: NDArray[np.float64]
   :param flag_extreme_dxy: Whether flagging on extreme stokes-v should be consider. Defaults to True.
   :type flag_extreme_dxy: bool, optional
   :param dxy_thresh: The threshold of the stokes-v flagging. Defaults to 4.0.
   :type dxy_thresh: float, optional

   :returns: Copies of the input `data`, `flags` and `uvws`. The `flags` are updated based on the results of the flagging.
   :rtype: tuple[NDArray[np.complex128], NDArray[np.bool], NDArray[np.float64]]


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

.. py:function:: create_aoflagger_cmd(ms: flint.options.MS) -> AOFlaggerCommand

   Create a command to run aoflagger against a measurement set

   :param ms: The measurement set to flag. The column attached to the MS.column
   :type ms: MS
   :param is flagged.:

   :raises MSError: Raised when the attached column is not found in the MS

   :returns: The aoflagger command that will be run
   :rtype: AOFlaggerCommand


.. py:function:: flag_ms_aoflagger(ms: flint.options.MS, container: pathlib.Path) -> flint.options.MS

   Create and run an aoflagger command in a container

   :param ms: The measurement set with nominated column to flag
   :type ms: MS
   :param container: The container with the aoflagger program
   :type container: Path

   :returns: Measurement set flagged with the appropriate column
   :rtype: MS


.. py:function:: flag_ms_by_antenna_ids(ms: pathlib.Path | flint.options.MS, ant_ids: int | Collection[int]) -> flint.options.MS

   Set the FLAG to True for a collection of rows where ANTENNA1 or ANTENNA2 is in a set of
   antenna IDs to flag. The flagging is performed via the antenna ID as it is in the measurement
   set - it is not by the antenna name.

   :param ms: The measurement set that has antennas to flag
   :type ms: Union[Path, MS]
   :param ant_ids: The set of antenna IDs to flag.
   :type ant_ids: Union[int,Collection[int]]

   :returns: The measurement set with flagged antennas.
   :rtype: MS


.. py:function:: flag_ms_zero_uvws(ms: flint.options.MS, chunk_size: int = 10000) -> flint.options.MS

   Flag out the UVWs in a measurement set that have values of zero.
   This happens when some data are flagged before it reaches the TOS.

   A critical MS interaction scope is created to ensure if things fail
   they are known.

   :param ms: Measurement set to flag
   :type ms: MS
   :param chunk_size: The number of rows to flag at a tim. Defaults to 10000.
   :type chunk_size: int, optional

   :returns: The flagged measurement set
   :rtype: MS


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

   Create the argument parser for the flagging

   :returns: aoflagger argument parser
   :rtype: ArgumentParser


.. py:function:: nan_zero_extreme_flag_ms(ms: pathlib.Path | flint.options.MS, data_column: str | None = None, flag_extreme_dxy: bool = True, dxy_thresh: float = 4.0, nan_data_on_flag: bool = False, chunk_size: int = 100000) -> flint.options.MS

   Will flag a MS based on NaNs or zeros in the nominated data column of a measurement set.
   These NaNs might be introduced into a column via the application of a applysolutions task.
   Zeros might be introduced by the correlator dropping cycles and not appropriately setting the
   corresponding FLAG column (although this might have been fixed).

   There is also an optional component to flag based on extreme Stokes-V values.

   Visibilities that are marked as bad will have the FLAG column updatede appropriately.

   :param ms: The measurement set that will be processed and have visibilities flagged.
   :type ms: Union[Path,MS]
   :param data_column: The column to inspect. This will override the value in the nominated column of the MS. Defaults to None.
   :type data_column: Optional[str], optional
   :param flag_extreme_dxy: Whether Stokes-V will be inspected and flagged. Defaults to True.
   :type flag_extreme_dxy: bool, optional
   :param dxy_thresh: Threshold used in the Stokes-V case. Defaults to 4.0.
   :type dxy_thresh: float, optional
   :param nan_data_on_flag: If True, data whose FLAG is set to True will become NaNs. Defaults to False.
   :type nan_data_on_flag: bool, optional
   :param chunk_size: Number of rows to process at a time. Defaults to 100000.
   :type chunk_size: int, optional

   :returns: The container of the processed MS
   :rtype: MS


.. py:function:: run_aoflagger_cmd(aoflagger_cmd: AOFlaggerCommand, container: pathlib.Path) -> None

   Run the aoflagger command constructed in its singularity container

   :param aoflagger_cmd: The command that will be executed
   :type aoflagger_cmd: AOFlaggerCommand
   :param container: Path to the container that contains aoflagger
   :type container: Path