eloy.utils
==========

.. py:module:: eloy.utils

.. autoapi-nested-parse::

   General utilities for astronomical image analysis.

   This module provides helper functions for cutouts, statistical metrics,
   binning, and generating synthetic images.



Functions
---------

.. autoapisummary::

   eloy.utils.cutout
   eloy.utils.std_diff_metric
   eloy.utils.stability_aperture
   eloy.utils.index_binning
   eloy.utils.binned_nanstd
   eloy.utils.fake_image
   eloy.utils.share_data


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

.. py:function:: cutout(data, coords, shape, wcs=None, fill_value=np.nan)

   Extract cutouts from data at given coordinates.

   :param data: 2D image data.
   :type data: np.ndarray
   :param coords: List of (x, y) coordinates.
   :type coords: array-like
   :param shape: Shape of the cutout.
   :type shape: tuple
   :param wcs: World Coordinate System object.
   :type wcs: WCS or None, optional

   :returns: Array of cutout images.
   :rtype: np.ndarray


.. py:function:: std_diff_metric(fluxes)

   Compute the standard deviation of the difference along the last axis.

   :param fluxes: Fluxes array.
   :type fluxes: np.ndarray

   :returns: Standard deviation of the differences.
   :rtype: np.ndarray


.. py:function:: stability_aperture(fluxes)

   Compute the mean absolute difference between consecutive fluxes.

   :param fluxes: Fluxes array.
   :type fluxes: np.ndarray

   :returns: Mean absolute difference for each aperture.
   :rtype: np.ndarray


.. py:function:: index_binning(x, size)

   Bin indices of x into bins of given size.

   :param x: Array to bin.
   :type x: array-like
   :param size: Bin size.
   :type size: int or float

   :returns: List of arrays of indices for each bin.
   :rtype: list


.. py:function:: binned_nanstd(x, bins: int = 12)

   Return a function to compute the mean of the standard deviation in bins.

   :param x: Array to bin.
   :type x: np.ndarray
   :param bins: Number of bins.
   :type bins: int, optional

   :returns: Function that computes the mean of the standard deviation in bins.
   :rtype: callable


.. py:function:: fake_image(shape=50, seed=0, stars=30)

   Generate a fake image with random stars.

   :param shape: Size of the image (shape x shape).
   :type shape: int, optional
   :param seed: Random seed.
   :type seed: int, optional
   :param stars: Number of stars.
   :type stars: int, optional

   :returns: Tuple (image, coords) where image is the generated image and coords are the star positions.
   :rtype: tuple


.. py:function:: share_data(master_files)

   Save master calibration arrays to disk as memory-mapped files and return read-only memmap objects.

   This function writes each array in `master_files` to a `.array` file using numpy's memmap,
   allowing efficient concurrent access from multiple processes. The returned dictionary contains
   read-only memmap objects for each calibration file.

   :param master_files: Dictionary mapping string keys (e.g., 'bias', 'dark', 'flat') to numpy.ndarray calibration arrays.
   :type master_files: dict

   :returns: Dictionary mapping the same keys to numpy.memmap objects opened in read-only mode.
   :rtype: dict