opticam.utils.helpers
=====================

.. py:module:: opticam.utils.helpers


Functions
---------

.. autoapisummary::

   opticam.utils.helpers.camel_to_snake
   opticam.utils.helpers.sort_dict_by_filters
   opticam.utils.helpers.sort_filters
   opticam.utils.helpers.delete_keys_from_nested_dict
   opticam.utils.helpers.match_dict_keys
   opticam.utils.helpers.propagate_errors
   opticam.utils.helpers.camera_and_filter_key
   opticam.utils.helpers.camera_key
   opticam.utils.helpers.filter_key
   opticam.utils.helpers.save_figure


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

.. py:function:: camel_to_snake(string)

   Convert a camelCase string to snake_case.

   Parameters
   ----------
   string : str
       The camelCase string to convert.

   Returns
   -------
   str
       The converted snake_case string.


.. py:function:: sort_dict_by_filters(d)

   Attempt to sort a dictionary whose keys are filter names in order of increasing wavelength (e.g., u, g, r, i, z). If
   unrecognised filters are passed, no sorting is performed.

   Parameters
   ----------
   d : Dict[str, Any]
       A dictionary with filter names as keys.

   Returns
   -------
   Dict[str, Any]
       The sorted dictionary.


.. py:function:: sort_filters(filters)

   Attempt to sort a list of filters in order of increasing wavelength (e.g., u, g, r, i, z). If unrecognised filters
   are passed, no sorting is performed.

   Parameters
   ----------
   filters : List[str]
       The list of filters.

   Returns
   -------
   List[str]
       The sorted list of filters.


.. py:function:: delete_keys_from_nested_dict(d, keys)

   Delete keys from a dictionary in-place.

   Parameters
   ----------
   d : dict[str, Any]
       The dictionary. May contain nested dictionaries.
   keys : set[str]
       The keys to remove from the dictionary.


.. py:function:: match_dict_keys(d, d_ref)

   Match the keys of `d` to those of `d_ref`.

   Parameters
   ----------
   d : dict[Any, Any]
       The dictionary.
   d_ref : dict[Any, Any]
       The reference dictionary.

   Returns
   -------
   dict[Any, Any]
       A copy of `d` whose keys match those of `d_ref`.


.. py:function:: propagate_errors(data, bias_var, dark_var, flat_var, background_rms, read_noise)

   Compute the propagated error image.

   Parameters
   ----------
   data : NDArray
       The calibrated, background-subtracted image.
   bias_var : float | NDArray[np.float64]
       The bias correction variance term.
   dark_var : float | NDArray[np.float64]
       The dark noise correction variance term.
   flat_var : float | NDArray[np.float64]
       The flat-field correction variance term scaled by the square of the calibrated image.
   background_rms : float | NDArray
       The background RMS.
   read_noise : float
       The read noise [electrons/pixel].

   Returns
   -------
   NDArray[np.float64]
       The propagated error image.


.. py:function:: camera_and_filter_key(camera, fltr)

   Create a unique camera:filter key. This unique key breaks degeneracies in multi-camera, multi-filter instruments,
   such that flat-field corrections can be applied properly.

   Parameters
   ----------
   camera : str
       The camera. For single-camera instruments, this can simply be the name of the instrument. For multi-camera
       instruments, however, this value should be unambiguous (e.g., the individual camera name or number).
   fltr : str
       The filter.

   Returns
   -------
   str
       The unique camera:filter key.


.. py:function:: camera_key(key)

   Given a unique camera:filter key, get the camera. This is used to apply bias and dark noise corrections, which are
   indifferent to the filter used.

   Parameters
   ----------
   key : str
       The unique camera:filter key.

   Returns
   -------
   str
       The camera.


.. py:function:: filter_key(key)

   Given a unique camera:filter key, get the filter.

   Parameters
   ----------
   key : str
       The unique camera:filter key.

   Returns
   -------
   str
       The filter.


.. py:function:: save_figure(fig, path)

   Save a figure to the specified path.

   Parameters
   ----------
   fig : Figure
       The figure.
   path : Path | str
       The path, including the file name and extension.