orca.transform.transient_search
===============================

.. py:module:: orca.transform.transient_search

.. autoapi-nested-parse::

   OVRO-LWA Transient Search Module.

   Ported from ExoPipe/transient_search.py into the orca package for use
   with the Celery pipeline.  All ``pipeline_config`` imports are replaced
   by ``orca.resources.subband_config``.

   Stokes V: Search each image directly (NO reference subtraction).
   Stokes I: Subtract deep from each 10min snapshot.

   ``run_test()`` returns a list of detection dicts (with ``snr`` key) so
   the caller can sort, filter, and apply a quality gate.



Attributes
----------

.. autoapisummary::

   orca.transform.transient_search.CONFIG_I
   orca.transform.transient_search.CONFIG_V
   orca.transform.transient_search.CUTOUT_SIZE
   orca.transform.transient_search.MAX_CUTOUTS


Functions
---------

.. autoapisummary::

   orca.transform.transient_search.load_catalog
   orca.transform.transient_search.get_midpoint_time
   orca.transform.transient_search.create_static_masks
   orca.transform.transient_search.create_bright_source_mask
   orca.transform.transient_search.calculate_local_rms_map
   orca.transform.transient_search.extract_peaks_flex
   orca.transform.transient_search.filter_bilobed_artifacts
   orca.transform.transient_search.run_test


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

.. py:data:: CONFIG_I

.. py:data:: CONFIG_V

.. py:data:: CUTOUT_SIZE

.. py:data:: MAX_CUTOUTS
   :value: 5


.. py:function:: load_catalog(path)

   Load a source catalog for cross-matching.


.. py:function:: get_midpoint_time(header)

   Get observation midpoint from FITS header.


.. py:function:: create_static_masks(header_tgt, header_ref, wcs, shape, cfg)

   Create horizon and A-team masks.


.. py:function:: create_bright_source_mask(data_ref, wcs, header_for_beam, cfg, search_rms)

   Adaptive masking: mask where Flux_Ref > (Tier * Sigma_Search).


.. py:function:: calculate_local_rms_map(data, mask, cfg)

   Compute a local RMS map using boxcar MAD.


.. py:function:: extract_peaks_flex(data, mask, threshold_sigma, rms_map, wcs, obs_time)

   Extract peaks above (or below) a sigma threshold.


.. py:function:: filter_bilobed_artifacts(candidates, partners, cfg)

   Remove candidates that have a matching opposite-sign partner.


.. py:function:: run_test(ref_path, tgt_path, ref_i_path, catalog_path, output_dir=None, mode=None)

   Main entry point for transient search.

   :param ref_path: Reference image for subtraction (1hr I deep). None for Stokes V.
   :param tgt_path: Target image to search (10min snapshot or deep V).
   :param ref_i_path: Reference Stokes I image for bright-source masking.
   :param catalog_path: Path to source catalog CSV.
   :param output_dir: Directory for cutouts and debug FITS.
   :param mode: Force 'V' or 'I' mode. If None, auto-detected from path.

   :returns: List of detection dicts sorted by descending |SNR|.