orca.transform.flagging
=======================

.. py:module:: orca.transform.flagging

.. autoapi-nested-parse::

   Flagging transforms for measurement sets.

   Provides high-level flagging operations that combine detection and application,
   including AOFlagger integration and autocorrelation-based antenna flagging.

   Functions
   ---------
   flag_with_aoflagger
       Run AOFlagger RFI detection on a measurement set.
   flag_ants
       Flag specified antennas in a measurement set.
   flag_ant_chan_from_autocorr
       Flag antennas and channels based on autocorrelation anomalies.
   flag_on_autocorr
       Identify and flag bad antennas from autocorrelation statistics.
   identify_bad_ants
       Identify bad antennas without applying flags.
   save_flag_metadata
       Save flag statistics in a compact binary format.



Attributes
----------

.. autoapisummary::

   orca.transform.flagging.log
   orca.transform.flagging.FLAG_COUNT_FACTOR


Functions
---------

.. autoapisummary::

   orca.transform.flagging.flag_with_aoflagger
   orca.transform.flagging.flag_ants
   orca.transform.flagging.flag_ant_chan_from_autocorr
   orca.transform.flagging.flag_on_autocorr
   orca.transform.flagging.identify_bad_ants
   orca.transform.flagging.save_flag_metadata


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

.. py:data:: log

.. py:data:: FLAG_COUNT_FACTOR
   :value: 10


.. py:function:: flag_with_aoflagger(ms: str, strategy: str = '/opt/share/aoflagger/strategies/nenufar-lite.lua', in_memory: bool = False, n_threads: int = 5) -> str

   Run AOFlagger RFI detection on a measurement set.

   :param ms: Path to the measurement set.
   :param strategy: Path to the AOFlagger Lua strategy file.
   :param in_memory: If True, load data into memory for processing.
   :param n_threads: Number of threads for AOFlagger.

   :returns: Path to the flagged measurement set.

   :raises RuntimeError: If AOFlagger returns a non-zero exit code.


.. py:function:: flag_ants(ms: str, ants: List[int]) -> str

   Flag all visibilities involving specified antennas.

   :param ms: Path to the measurement set.
   :param ants: List of antenna indices (0-indexed) to flag.

   :returns: Path to the modified measurement set.


.. py:function:: flag_ant_chan_from_autocorr(ms: str, threshold: float = 5.0) -> str

   Flag antennas and channels based on autocorrelation anomalies.

   :param ms: Path to the measurement set.
   :param threshold: Sigma threshold for outlier detection.

   :returns: Path to the flagged measurement set.

   .. note:: Currently only works on single spectral window data.


.. py:function:: flag_on_autocorr(ms, date: Optional[datetime.date] = None, thresh: float = 7.0, column='DATA') -> str

   Identify and flag bad antennas from autocorrelation statistics.

   Optionally loads a priori bad antenna list for the given date before
   performing autocorrelation-based detection.

   :param ms: Path to the measurement set.
   :param date: Observation date for loading a priori bad antennas.
   :param thresh: Sigma threshold for flagging (default 7.0).
   :param column: Data column to analyze ('DATA' or 'CORRECTED_DATA').

   :returns: Path to the flagged measurement set.


.. py:function:: identify_bad_ants(t: casacore.tables.table, thresh: float = 7, column='DATA') -> List[int]

   Identify bad antennas from autocorrelation statistics.

   Compares each antenna's autocorrelation bandpass to a median template
   for core and outrigger antennas separately. Antennas with normalized
   deviations exceeding the threshold are flagged.

   :param t: Open casacore table object for the measurement set.
   :param thresh: Sigma threshold for flagging (default 7.0).
   :param column: Data column to analyze ('DATA' or 'CORRECTED_DATA').

   :returns: List of antenna indices identified as bad.

   :raises AssertionError: If data contains multiple timestamps or spectral windows.


.. py:function:: save_flag_metadata(ms: str, output_dir: str = '/lustre/pipeline/slow-averaged/') -> str

   Save FLAG column in a compact bit-packed binary format.

   Creates a binary file containing the packed flag data, which can be
   unpacked later using numpy.unpackbits().

   :param ms: Path to the measurement set.
   :param output_dir: Directory for output file.

   :returns: Path to the measurement set (unchanged).