orca.transform.qa_plotting
==========================

.. py:module:: orca.transform.qa_plotting

.. autoapi-nested-parse::

   QA plotting utilities for calibration diagnostics.

   Provides functions for generating diagnostic plots of bandpass calibration
   solutions, gain variations, and other calibration quality metrics.
   Supports multi-page PDF output with per-antenna visualizations.



Functions
---------

.. autoapisummary::

   orca.transform.qa_plotting.plot_bandpass_to_pdf_amp_phase
   orca.transform.qa_plotting.plot_delay_vs_antenna
   orca.transform.qa_plotting.plot_delay_difference_vs_antenna


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

.. py:function:: plot_bandpass_to_pdf_amp_phase(calfile, pdf_path='bandpass_QA_all.pdf', msfile=None, amp_scale='log', amp_limits=None)

   Generate a multi-page PDF visualizing bandpass calibration solutions per antenna.

   Each antenna is shown with two vertically stacked subplots:
   - Amplitude (log or lin scale) vs frequency
   - Phase (in degrees) vs frequency

   :param calfile: Path to the CASA bandpass calibration table (e.g. '.bandpass').
                   Must contain the 'CPARAM' column.
   :type calfile: str
   :param pdf_path: Path to the output PDF file (default: 'bandpass_QA_all.pdf').
   :type pdf_path: str, optional
   :param msfile: Optional path to the associated measurement set ('.ms').
                  Used to extract frequency values in MHz from the SPECTRAL_WINDOW table.
                  If unavailable, channel indices are used instead.
   :type msfile: str, optional
   :param amp_scale: Scale to use for amplitude plots: "log" (default) or "linear".
   :type amp_scale: str, optional
   :param amp_limits: Tuple specifying fixed y-axis limits for amplitude plots (ymin, ymax).
                      If not set, default fixed limits are applied:
                          - [1e-4, 2e0] for log scale if all data fits
                          - [1e-4, 1e-2] for linear scale if all data fits
                      If data does not fit within the specified or default range, y-axis is scaled automatically.
   :type amp_limits: tuple of float, optional

   .. admonition:: Notes

      - Each page shows 16 antennas (4 columns × 4 rows).
      - Flagged data points are shown in red.
      - Amplitude plots use log scale with fixed limits [1e-4, 2e0] if all unflagged values fit.
      - Phase plots are fixed to [-180, 180] degrees.
      - Legends show Pol 0, Pol 1, and Flagged in every amplitude subplot.
      - Antenna labels include both correlator number and LWA antenna name if available.


.. py:function:: plot_delay_vs_antenna(delay_table_path, output_pdf='delay_vs_antenna.pdf', use_antenna_labels=False, ymin=None, ymax=None)

   Plot delay (in ns) vs antenna (correlator number or integer antenna number).
   If use_antenna_labels=True, x-axis uses parsed antenna numbers and data is sorted accordingly.
   Y-axis limits can be customized via `ymin` and `ymax`.

   :param delay_table_path: Path to the CASA .delay table.
   :type delay_table_path: str
   :param output_pdf: Output PDF filename.
   :type output_pdf: str
   :param use_antenna_labels: If True, plot against integer antenna numbers instead of correlator numbers.
   :type use_antenna_labels: bool
   :param ymin: Custom lower Y-axis limit (ns), or None for auto/computed default.
   :type ymin: float or None
   :param ymax: Custom upper Y-axis limit (ns), or None for auto/computed default.
   :type ymax: float or None


.. py:function:: plot_delay_difference_vs_antenna(new_delay_table, output_pdf='delay_difference_vs_antenna.pdf', reference_delay_table='/lustre/pipeline/calibration/delay/2025-01-28/20250128_delay.delay', use_antenna_labels=False, ymin=None, ymax=None)

   Plot delay difference (new - reference) per antenna from CASA .delay tables.
   Flagged points shown in red.
   Y-axis limited to [-100, 100] ns if all differences fit, otherwise automatic.
   You can override Y-axis limits by setting `ymin` and `ymax`.
   Output saved as a PDF.

   :param new_delay_table: Path to the new CASA delay table (.delay file).
   :type new_delay_table: str
   :param output_pdf: Path to output PDF file (default: 'delay_difference_vs_antenna.pdf').
   :type output_pdf: str, optional
   :param reference_delay_table: Path to the reference CASA delay table (default: 2025-01-28 table).
   :type reference_delay_table: str, optional
   :param use_antenna_labels: If True, sort and label x-axis by integer antenna numbers instead of correlator IDs.
   :type use_antenna_labels: bool, optional
   :param ymin: Custom lower Y-axis limit (ns), or None for auto/computed default.
   :type ymin: float or None
   :param ymax: Custom upper Y-axis limit (ns), or None for auto/computed default.
   :type ymax: float or None