orca.utils.flagutils
====================

.. py:module:: orca.utils.flagutils

.. autoapi-nested-parse::

   Flag file utilities for antenna and visibility flagging.

   Provides functions for reading and writing flag data, looking up
   bad antennas from the flag database, and visualizing flag statistics.



Attributes
----------

.. autoapisummary::

   orca.utils.flagutils.FLAG_TABLE
   orca.utils.flagutils.df


Functions
---------

.. autoapisummary::

   orca.utils.flagutils.get_bad_ants
   orca.utils.flagutils.unpack_flag_metadata
   orca.utils.flagutils.plot_flag_metadata_all_polarizations_subplot
   orca.utils.flagutils.get_bad_antenna_names
   orca.utils.flagutils.get_bad_correlator_numbers


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

.. py:data:: FLAG_TABLE
   :value: '/opt/devel/yuping/ant_flags.csv'


.. py:data:: df

.. py:function:: get_bad_ants(date: datetime.date, sources=['AI-VAR', 'AI-LO'])

   Return a list of bad antennas for a given date and kinds of flags.

   :param date: The date
   :param sources: Sources of flags. Default is ['AI-VAR', 'AI-LO'].

   :returns: A list of bad antenna corr numbers.


.. py:function:: unpack_flag_metadata(input_file: str, original_shape: tuple) -> numpy.ndarray

   Unpacks binary flag metadata from a packed binary file into its original FLAG column shape.

   Parameters:
   -----------
   input_file : str
       Path to the binary file containing the packed flag data.
   original_shape : tuple
       The shape of the original FLAG array (e.g., (polarizations, channels, rows)).

   Returns:
   --------
   np.ndarray
       A Boolean array of the same shape as the original FLAG column.


.. py:function:: plot_flag_metadata_all_polarizations_subplot(flags: numpy.ndarray, output_dir: str = None) -> None

   Plots the flag metadata for all polarizations in a single subplot figure.

   Parameters:
   -----------
   flags : np.ndarray
       A Boolean array of shape (polarizations, channels, rows) representing the flag data.
   output_dir : str, optional
       Directory where the plot will be saved. If None, the plot is displayed interactively.


.. py:function:: get_bad_antenna_names(date_time_str)

   Get a list of bad antenna names (e.g., 'LWA-005B') using the 'development' conda environment.

   :param date_time_str: Date and time string in ISO format, e.g. '2025-01-28 19:20:04'
   :type date_time_str: str

   :returns: List of bad antenna names
   :rtype: list


.. py:function:: get_bad_correlator_numbers(date_time_str)