orca.transform.photometry
=========================

.. py:module:: orca.transform.photometry

.. autoapi-nested-parse::

   Photometry transforms for FITS image analysis.

   Provides functions for source detection, flux measurement, noise estimation,
   and image quality assessment from radio FITS images.



Attributes
----------

.. autoapisummary::

   orca.transform.photometry.PATCH_SIDE_SIZE
   orca.transform.photometry.logger


Functions
---------

.. autoapisummary::

   orca.transform.photometry.std_and_max_around_coord
   orca.transform.photometry.average_with_rms_threshold
   orca.transform.photometry.estimate_image_noise
   orca.transform.photometry.search_src
   orca.transform.photometry.noise
   orca.transform.photometry.make_fig


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

.. py:data:: PATCH_SIDE_SIZE
   :value: 12


.. py:data:: logger

.. py:function:: std_and_max_around_coord(fits_file, coord, radius=5)

   Calculate the stdev around a given coordinate in a FITS file.

   :param fits_file: Path to the FITS file.
   :type fits_file: str
   :param coord: The coordinate around which to calculate the stdev.
   :type coord: astropy.Coordinates
   :param radius: Radius in pixels.
   :type radius: int, optional


.. py:function:: average_with_rms_threshold(fits_list: List[str], out_fn: str, source_coord: Optional[astropy.coordinates.SkyCoord], radius_px: int, threshold_multiple: float) -> Optional[str]

   Average FITS images while rejecting those with high RMS near a source.

   Calculates RMS in a box around the source coordinate and rejects images
   where RMS exceeds the median RMS times threshold_multiple.

   :param fits_list: List of FITS file paths to average.
   :param out_fn: Output file path.
   :param source_coord: Coordinate for RMS measurement. If None, no filtering.
   :param radius_px: Box half-size in pixels for RMS calculation.
   :param threshold_multiple: Reject images with RMS > median * threshold_multiple.

   :returns: Output file path on success.


.. py:function:: estimate_image_noise(arr: numpy.ndarray) -> float

   Estimate the noise in an image using the median absolute deviation (MAD).

   :param arr: The image data.
   :type arr: np.ndarray

   :returns: The estimated noise.
   :rtype: float


.. py:function:: search_src(fn: str, src: astropy.coordinates.SkyCoord, stats_box_size: int, peak_search_box_size: int) -> Tuple[float, float]

   Search for a source and measure its peak flux and local RMS.

   :param fn: Path to the FITS image.
   :param src: Sky coordinate of the source to measure.
   :param stats_box_size: Box size in pixels for noise estimation.
   :param peak_search_box_size: Box size in pixels for peak search.

   :returns: Tuple of (peak_flux, rms) values.


.. py:function:: noise(im: numpy.ndarray, stats_box_size: int, src: astropy.coordinates.SkyCoord, w: astropy.wcs.WCS) -> float

   Estimate noise level around a source position.

   :param im: Image data array.
   :param stats_box_size: Box size in pixels for noise estimation.
   :param src: Sky coordinate of the source.
   :param w: WCS object for coordinate transformation.

   :returns: Estimated noise level using MAD estimator.


.. py:function:: make_fig(v_fns: List[str], src: astropy.coordinates.SkyCoord, stats_box_size: int, out_dir: str)

   Generate diagnostic figures showing Stokes I and V images.

   Creates side-by-side plots of Stokes I and V cutouts around a source
   with calibrator positions marked.

   :param v_fns: List of Stokes V FITS file paths.
   :param src: Source coordinate for cutout center.
   :param stats_box_size: Box size for noise estimation.
   :param out_dir: Output directory for figures.