orca.transform.cutout
=====================

.. py:module:: orca.transform.cutout

.. autoapi-nested-parse::

   Target photometry with ionospheric-aware search and confusing source masking.

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



Attributes
----------

.. autoapisummary::

   orca.transform.cutout.CASA_AVAILABLE
   orca.transform.cutout.DETECTION_SIGMA
   orca.transform.cutout.MIN_ELEVATION
   orca.transform.cutout.BEAM_SEARCH_MULTIPLIER
   orca.transform.cutout.IONOSPHERE_PAD_ARCSEC_85MHZ
   orca.transform.cutout.IONOSPHERE_REF_FREQ_MHZ
   orca.transform.cutout.DEFAULT_BEAM_ARCSEC
   orca.transform.cutout.CUTOUT_SIZE
   orca.transform.cutout.FIT_SIGMA_THRESHOLD


Functions
---------

.. autoapisummary::

   orca.transform.cutout.get_timestamp_from_header
   orca.transform.cutout.get_beam_size_arcsec
   orca.transform.cutout.robust_measure_flux
   orca.transform.cutout.find_all_images
   orca.transform.cutout.find_image_pairs
   orca.transform.cutout.process_target
   orca.transform.cutout.load_targets


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

.. py:data:: CASA_AVAILABLE
   :value: True


.. py:data:: DETECTION_SIGMA
   :value: 5.0


.. py:data:: MIN_ELEVATION
   :value: 30.0


.. py:data:: BEAM_SEARCH_MULTIPLIER
   :value: 1.0


.. py:data:: IONOSPHERE_PAD_ARCSEC_85MHZ
   :value: 120.0


.. py:data:: IONOSPHERE_REF_FREQ_MHZ
   :value: 85.0


.. py:data:: DEFAULT_BEAM_ARCSEC
   :value: 300.0


.. py:data:: CUTOUT_SIZE

.. py:data:: FIT_SIGMA_THRESHOLD
   :value: 3.0


.. py:function:: get_timestamp_from_header(header)

.. py:function:: get_beam_size_arcsec(header)

.. py:function:: robust_measure_flux(data, cutout_wcs, sky_coord, beam_arcsec, freq_mhz, fits_path=None, confusing_sources=None)

   Measure flux at source position and find peak within beam + ionospheric padding.

   :param data: 2D numpy array (cutout pixel data, already in memory)
   :param cutout_wcs: astropy WCS (celestial, 2D) from Cutout2D
   :param sky_coord: SkyCoord of the target
   :param beam_arcsec: Beam FWHM in arcseconds
   :param freq_mhz: Observing frequency in MHz (for ionospheric scaling)
   :param fits_path: Optional path to cutout FITS for CASA imfit
   :param confusing_sources: Optional list of SkyCoord for known confusing sources
                             to mask within one beam FWHM before measurement.

   Returns dict with keys:
       src_flux, peak_flux, peak_coord, offset_arcmin, rms,
       fit_flux, fit_err, method, n_confusers_masked


.. py:function:: find_all_images(run_dir, fallback_dir=None)

   Find all image sets for target cutouts.

   Returns dict with:
       'freq': float,
       'deep_i': path, 'deep_v': path,
       'snapshots_10min': list of (i_path, v_path, interval_tag) tuples
   Or empty dict if deep pair not found.


.. py:function:: find_image_pairs(run_dir, fallback_dir=None)

   Legacy wrapper: returns list of (freq, i_path, v_path) for deep images only.


.. py:function:: process_target(run_dir, target_name, coord, sample_name, base_out_dir, detections_dir, fallback_dir=None, detection_stokes='IV', confusing_sources=None)

   Extract cutouts for a target from deep and 10min images.

   Deep Stokes I: uses confusing source masking if sources specified.
   10min Stokes I: uses (10min - deep) difference image — no masking needed.
   Stokes V: measured directly for both deep and 10min.


.. py:function:: load_targets(filepath)

   Load targets from CSV. Returns list of (name, coord, detection_stokes, confusers).