orca.transform.calibration
==========================

.. py:module:: orca.transform.calibration

.. autoapi-nested-parse::

   Visibility calibration operations.

   Provides functions for direction-independent calibration of OVRO-LWA
   measurement sets, including bandpass solving and application.

   Functions
   ---------
   di_cal
       Solve for bandpass calibration from a single MS.
   di_cal_multi_v2
       Solve for bandpass from multiple concatenated MS files (with auto-retry).
   di_cal_multi
       Solve for bandpass from multiple concatenated MS files.
   flag_bad_sol
       Flag bad solutions in a bandpass table.
   applycal_data_col
       Apply calibration and write to a new measurement set.
   applycal_data_col_nocopy
       Apply calibration in-place without copying.
   applycal_in_mem
       Apply bandpass calibration to data array in memory.
   applycal_in_mem_cross
       Apply bandpass calibration to cross-correlation data in memory.



Attributes
----------

.. autoapisummary::

   orca.transform.calibration.logger


Functions
---------

.. autoapisummary::

   orca.transform.calibration.di_cal
   orca.transform.calibration.di_cal_multi_v2
   orca.transform.calibration.di_cal_multi
   orca.transform.calibration.flag_bad_sol
   orca.transform.calibration.applycal_data_col
   orca.transform.calibration.applycal_data_col_nocopy
   orca.transform.calibration.applycal_in_mem
   orca.transform.calibration.applycal_in_mem_cross


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

.. py:data:: logger

.. py:function:: di_cal(ms, out=None, do_polcal=False, refant='199') -> str

   Perform DI calibration and solve for cal table.

   :param ms: Measurement set to solve with
   :param out: Output path for the derived cal table (incl the table name). Default is None.
   :param do_polcal: Do polarization calibration. Default is False.

   Returns: Path to the derived cal table.



.. py:function:: di_cal_multi_v2(ms_list, scrach_dir, out, do_polcal=False, refant='199', flag_ant=True) -> Optional[str]

   Perform DI calibration on multiple integrations. Copy, concat, then solve.

   :param ms_list: List of measurement sets to solve with
   :param scrach_dir: Directory to store temporary files
   :param out: Output path for the derived cal table.
   :param do_polcal: Do polarization calibration. Default is False.

   Returns: List of paths to the derived cal tables.


.. py:function:: di_cal_multi(ms_list, scrach_dir, out, do_polcal=False, refant='199', flag_ant=True) -> Optional[str]

   Perform DI calibration on multiple integrations. Copy, concat, then solve.

   :param ms_list: List of measurement sets to solve with
   :param scrach_dir: Directory to store temporary files
   :param out: Output path for the derived cal table.
   :param do_polcal: Do polarization calibration. Default is False.

   Returns: List of paths to the derived cal tables.


.. py:function:: flag_bad_sol(bcal: str) -> str

   Flag bad solutions in a bandpass calibration table.

   Flags solutions with amplitudes below 1% of the median, which would
   cause excessive amplification when applied.

   :param bcal: Path to the bandpass calibration table.

   :returns: Path to the modified calibration table.


.. py:function:: applycal_data_col(ms: str, gaintable: str, out_ms: str) -> str

   Apply calibration and write to a new measurement set.

   Copies the MS, applies calibration to CORRECTED_DATA, then replaces
   DATA with the calibrated values.

   :param ms: Input measurement set.
   :param gaintable: Calibration table to apply.
   :param out_ms: Output path for the calibrated measurement set.

   :returns: Path to the calibrated measurement set.


.. py:function:: applycal_data_col_nocopy(ms: str, gaintable: str) -> str

   Apply calibration in-place without copying the measurement set.

   Uses Numba-accelerated in-memory calibration for performance.

   :param ms: Path to the measurement set (modified in-place).
   :param gaintable: Path to the bandpass calibration table.

   :returns: Path to the calibrated measurement set.


.. py:function:: applycal_in_mem(data: numpy.ndarray, bcal: numpy.ndarray) -> numpy.ndarray

   Apply bandpass calibration to visibility data in memory.

   Numba-JIT compiled function for efficient calibration application.
   Handles the full visibility matrix including both autocorrelations
   and cross-correlations.

   :param data: Visibility data with shape (n_bl, n_chan, 4).
   :param bcal: Bandpass gains with shape (n_ant, n_chan, 2).

   :returns: Calibrated visibility data with same shape as input.


.. py:function:: applycal_in_mem_cross(data: numpy.ndarray, bcal: numpy.ndarray) -> numpy.ndarray

   Apply bandpass calibration to cross-correlation visibility data.

   Numba-JIT compiled function for efficient calibration of cross-correlations
   only (excludes autocorrelations). Uses the same algorithm as applycal_in_mem
   but only iterates over baselines where antenna i < j.

   :param data: Visibility data with shape (n_cross_bl, n_chan, 4).
   :param bcal: Bandpass gains with shape (n_ant, n_chan, 2).

   :returns: Calibrated visibility data with same shape as input.