orca.transform.ionospheric_dewarping
====================================

.. py:module:: orca.transform.ionospheric_dewarping

.. autoapi-nested-parse::

   Ionospheric dewarping via VLSSr cross-match.

   Ported from ExoPipe/extractor_pb_75.py into the orca package.

   Computes pixel-level warp screens by cross-matching extracted LWA sources
   against the VLSSr catalog and interpolating positional offsets over the
   full image grid using scipy.interpolate.griddata.

   Functions
   ---------
   parse_vlssr_text
       Parse the OVRO-LWA VLSSr text catalog into a dict.
   load_ref_catalog
       Load a reference catalog (FITS or VLSSr text format).
   generate_warp_screens
       Build 2-D warp screens from LWA↔catalog cross-match.
   apply_warp
       Apply pre-computed warp screens to an image array.



Attributes
----------

.. autoapisummary::

   orca.transform.ionospheric_dewarping.logger
   orca.transform.ionospheric_dewarping.MATCH_RADIUS
   orca.transform.ionospheric_dewarping.DEFAULT_ALPHA
   orca.transform.ionospheric_dewarping.FLUX_RATIO_MIN
   orca.transform.ionospheric_dewarping.FLUX_RATIO_MAX
   orca.transform.ionospheric_dewarping.VLSS_MAX_SIZE_DEG
   orca.transform.ionospheric_dewarping.NVSS_MAX_SIZE_DEG
   orca.transform.ionospheric_dewarping.LWA_SIZE_TOLERANCE


Functions
---------

.. autoapisummary::

   orca.transform.ionospheric_dewarping.parse_vlssr_text
   orca.transform.ionospheric_dewarping.load_ref_catalog
   orca.transform.ionospheric_dewarping.generate_warp_screens
   orca.transform.ionospheric_dewarping.apply_warp


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

.. py:data:: logger

.. py:data:: MATCH_RADIUS

.. py:data:: DEFAULT_ALPHA
   :value: -0.7


.. py:data:: FLUX_RATIO_MIN
   :value: 0.8


.. py:data:: FLUX_RATIO_MAX
   :value: 1.2


.. py:data:: VLSS_MAX_SIZE_DEG
   :value: 0.020833333333333332


.. py:data:: NVSS_MAX_SIZE_DEG
   :value: 0.0125


.. py:data:: LWA_SIZE_TOLERANCE
   :value: 1.2


.. py:function:: parse_vlssr_text(path)

   Parse the OVRO-LWA VLSSr text catalog.

   The text format has columns: RAh RAm RAs DECd DECm DECs ... flux ...
   where flux is in Jy and positions are sexagesimal.

   :param path: Path to the VLSSr text file.

   :returns: Dict with keys 'coords', 'flux', 'maj', 'ra', 'dec', 'type',
             or None on failure.


.. py:function:: load_ref_catalog(path, name='VLSSr')

   Load a reference catalog (FITS table or VLSSr text).

   :param path: Filesystem path to the catalog.
   :param name: Catalog name (used to identify format).

   :returns: Dict with keys 'coords', 'flux', 'maj', 'ra', 'dec', 'type',
             or None on failure.


.. py:function:: generate_warp_screens(img_sources, cat_data, wcs_obj, shape, freq_mhz, cat_freq_mhz, lwa_bmaj_deg, clip_sigma, base_name='')

   Build 2-D ionospheric warp screens from LWA↔catalog cross-match.

   :param img_sources: DataFrame with columns 'ra', 'dec', 'flux_peak_I_app',
                       optionally 'maj'.
   :param cat_data: Dict from :func:`load_ref_catalog`.
   :param wcs_obj: ``astropy.wcs.WCS`` (celestial) of the reference image.
   :param shape: (ny, nx) of the image.
   :param freq_mhz: Observing frequency (MHz).
   :param cat_freq_mhz: Reference catalog frequency (MHz), e.g. 74.
   :param lwa_bmaj_deg: Beam FWHM of the LWA image (degrees).
   :param clip_sigma: Sigma-clipping threshold (not currently applied —
                      kept for API compatibility).
   :param base_name: Prefix for diagnostic file names.

   :returns: Tuple ``(screen_x, screen_y, anchors_diag, raw_coords)``
             where screens are 2-D arrays of pixel offsets, or
             ``(None, None, None, None)`` on failure.


.. py:function:: apply_warp(data, screen_x, screen_y)

   Apply pre-computed warp screens to an image array.

   :param data: 2-D numpy array of image pixels.
   :param screen_x: X-offset screen (same shape as *data*).
   :param screen_y: Y-offset screen (same shape as *data*).

   :returns: Dewarped 2-D array, or None on shape mismatch.