eloy.flux
=========

.. py:module:: eloy.flux

.. autoapi-nested-parse::

   Differential photometry and flux optimization routines.

   This module provides functions for computing differential fluxes,
   optimizing comparison star weights, and selecting optimal flux indices.



Functions
---------

.. autoapisummary::

   eloy.flux.weights
   eloy.flux.diff
   eloy.flux.auto_diff_1d
   eloy.flux.auto_diff
   eloy.flux.optimal_flux


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

.. py:function:: weights(fluxes: numpy.ndarray, tolerance: float = 0.001, max_iteration: int = 200, bins: int = 5)

   Returns the weights computed using Broeg 2005.

   :param fluxes: Fluxes matrix with dimensions (star, flux) or (aperture, star, flux).
   :type fluxes: np.ndarray
   :param tolerance: Minimum standard deviation of weights difference to attain (weights are stable).
   :type tolerance: float, optional
   :param max_iteration: Maximum number of iterations to compute weights.
   :type max_iteration: int, optional
   :param bins: Binning size (in number of points) to compute the white noise.
   :type bins: int, optional

   :returns: Broeg weights.
   :rtype: np.ndarray


.. py:function:: diff(fluxes: numpy.ndarray, weights: numpy.ndarray = None)

   Returns differential fluxes.

   If weights are specified, they are used to produce an artificial light curve by which all flux are differentiated (see Broeg 2005).

   :param fluxes: Fluxes matrix with dimensions (star, flux) or (aperture, star, flux).
   :type fluxes: np.ndarray
   :param weights: Weights matrix with dimensions (star) or (aperture, star).
   :type weights: np.ndarray, optional

   :returns: Differential fluxes if weights is provided, else normalized fluxes.
   :rtype: np.ndarray


.. py:function:: auto_diff_1d(fluxes, i=None)

   Automatically compute differential fluxes and optimal weights for 1D flux array.

   :param fluxes: Fluxes array.
   :type fluxes: np.ndarray
   :param i: Index of the target star.
   :type i: int or None, optional

   :returns: Tuple (differential fluxes, weights).
   :rtype: tuple


.. py:function:: auto_diff(fluxes: numpy.array, i: int = None)

   Automatically compute differential fluxes and optimal weights for 2D or 3D flux array.

   :param fluxes: Fluxes array.
   :type fluxes: np.ndarray
   :param i: Index of the target star.
   :type i: int or None, optional

   :returns: Differential fluxes and weights.
   :rtype: tuple or tuple of arrays


.. py:function:: optimal_flux(diff_fluxes, method='stddiff', sigma=4)

   Select the optimal flux index based on a given criterion.

   :param diff_fluxes: Differential fluxes array.
   :type diff_fluxes: np.ndarray
   :param method: Criterion method: "binned", "stddiff", or "stability".
   :type method: str, optional
   :param sigma: Sigma clipping threshold.
   :type sigma: float, optional

   :returns: Index of the optimal flux.
   :rtype: int