orca.flagging.flagoperations
============================

.. py:module:: orca.flagging.flagoperations

.. autoapi-nested-parse::

   Low-level flag manipulation operations for measurement sets.

   Provides functions for directly manipulating FLAG columns in CASA
   measurement sets, including flagging antennas, baselines, merging
   flags between observations, and I/O with numpy arrays.

   Originally adapted from Marin Anderson's code (3/8/2019).

   Functions
   ---------
   flag_ants
       Flag all visibilities involving specified antennas.
   merge_flags
       OR-merge flags between two measurement sets.
   merge_group_flags
       OR-merge flags across a group of measurement sets.
   write_to_flag_column
       Apply flags from a numpy array to a measurement set.
   save_to_flag_npy
       Save the FLAG column to a numpy file.
   flag_bls
       Apply baseline flags from a text file.



Attributes
----------

.. autoapisummary::

   orca.flagging.flagoperations.DATA
   orca.flagging.flagoperations.CORRECTED_DATA


Functions
---------

.. autoapisummary::

   orca.flagging.flagoperations.flag_ants
   orca.flagging.flagoperations.merge_flags
   orca.flagging.flagoperations.merge_group_flags
   orca.flagging.flagoperations.write_to_flag_column
   orca.flagging.flagoperations.save_to_flag_npy
   orca.flagging.flagoperations.flag_bls


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

.. py:data:: DATA
   :value: 'DATA'


.. py:data:: CORRECTED_DATA
   :value: 'CORRECTED_DATA'


.. 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:: merge_flags(ms1: str, ms2: str) -> Tuple[str, str]

   OR-merge flags between two measurement sets.

   Updates both measurement sets so their FLAG columns contain the
   logical OR of the original flags from both files.

   :param ms1: Path to the first measurement set.
   :param ms2: Path to the second measurement set.

   :returns: Tuple of (ms1, ms2) paths.


.. py:function:: merge_group_flags(ms_list: List[str]) -> List[str]

   OR-merge flags across a group of measurement sets.

   Updates all measurement sets so they share the same merged FLAG column,
   containing the logical OR of flags from all input files.

   :param ms_list: List of measurement set paths.

   :returns: The input list of paths (all now updated).


.. py:function:: write_to_flag_column(ms: str, flag_npy: str) -> str

   Apply flags from a numpy array to a measurement set.

   The numpy array is OR-merged with existing flags.

   :param ms: Path to the measurement set.
   :param flag_npy: Path to the numpy file containing boolean flag array.

   :returns: Path to the modified measurement set.

   :raises AssertionError: If the flag array shape doesn't match the MS.


.. py:function:: save_to_flag_npy(ms: str, flag_npy: str) -> str

   Save the FLAG column from a measurement set to a numpy file.

   :param ms: Path to the measurement set.
   :param flag_npy: Output path for the numpy file.

   :returns: Path to the saved numpy file.


.. py:function:: flag_bls(msfile: str, blfile: str) -> str

   Apply baseline flags from a text file to a measurement set.

   :param msfile: Path to the measurement set.
   :param blfile: Path to the baseline flag file. Format is one baseline
                  per line as 'ant1&ant2' (0-indexed).

   :returns: Path to the modified measurement set.

   :raises ValueError: If the number of visibilities is unexpected.