petitRADTRANS.utils
===================

.. py:module:: petitRADTRANS.utils

.. autoapi-nested-parse::

   Stores useful generic functions.



Classes
-------

.. autoapisummary::

   petitRADTRANS.utils.LockedDict


Functions
---------

.. autoapisummary::

   petitRADTRANS.utils.check_all_close
   petitRADTRANS.utils.class_init_args2class_args
   petitRADTRANS.utils.class_init_args2dict
   petitRADTRANS.utils.class2hdf5
   petitRADTRANS.utils.dataset2obj
   petitRADTRANS.utils.dict2hdf5
   petitRADTRANS.utils.copy_array_like
   petitRADTRANS.utils.copy_mask_array
   petitRADTRANS.utils.copy_parameter_value
   petitRADTRANS.utils.fill_object
   petitRADTRANS.utils.flatten_object
   petitRADTRANS.utils.hdf52dict
   petitRADTRANS.utils.intersection_indices
   petitRADTRANS.utils.list_str2str
   petitRADTRANS.utils.load_csv
   petitRADTRANS.utils.remove_mask
   petitRADTRANS.utils.savez_compressed_record
   petitRADTRANS.utils.topological_sort
   petitRADTRANS.utils.tuple_init
   petitRADTRANS.utils.user_input


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

.. py:class:: LockedDict

   Bases: :py:obj:`dict`


   Derivative of dict with a lock.
   Can be used to ensure that no new key is added once the lock is on, to prevent errors due to key typos.


   .. py:attribute:: _locked
      :value: False



   .. py:method:: __copy__()

      Override the copy.copy method. Necessary to allow locked LockedDict to be copied.



   .. py:method:: __deepcopy__(memo)

      Override the copy.deepcopy method. Necessary to allow locked LockedDict to be copied.



   .. py:method:: __setitem__(key, value)

      Prevent a key to be added if the lock is on.



   .. py:method:: build_and_lock(dictionary=None, **kwargs)
      :classmethod:


      Instantiate a LockedDict and lock it.



   .. py:method:: lock()


   .. py:method:: update(__m=None, **kwargs) -> None

      Ensure that update takes the lock into account and do not remove keys.



   .. py:method:: unlock()


   .. py:method:: tree_flatten()


   .. py:method:: tree_unflatten(aux_data, children)
      :classmethod:



.. py:function:: check_all_close(a, b, **kwargs)

.. py:function:: class_init_args2class_args(string)

   Convenience code-writing function to convert a series of arguments into lines of initialization for a class.
   Useful to quickly write the __init__ function of a class from its arguments.
   Example:
       >>> s = "arg1, arg2=0.3, arg3='a'"
       >>> print(class_init_args2class_args(s))
       output:
           self.arg1 = arg1
           self.arg2 = arg2
           self.arg3 = arg3


.. py:function:: class_init_args2dict(string)

   Convenience code-writing function to convert a series of arguments into a dictionary.
   Useful to quickly write a dictionary from a long list of arguments.
   Example:
       >>> s = "arg1, arg2=0.3, arg3='a'"
       >>> print(class_init_args2class_args(s))
       output:
           {
               'arg1': ,
               'arg2': ,
               'arg3': ,
           }


.. py:function:: class2hdf5(obj, filename=None)

   Convert an instance of a class into a HDF5 dataset.


.. py:function:: dataset2obj(obj)

   Convert a HDF5 dataset into a list of objects (float, int or str).


.. py:function:: dict2hdf5(dictionary, hdf5_file, group='/')

   Convert a dictionary into a HDF5 dataset.


.. py:function:: copy_array_like(array)

   Copy a numpy or masked array without recursive Python deepcopy overhead.


.. py:function:: copy_mask_array(array)

   Copy the boolean mask associated with a masked array-like object.


.. py:function:: copy_parameter_value(value)

   Copy nested parameter values while leaving immutable scalars untouched.


.. py:function:: fill_object(array, value)

   Fill a numpy object array with a value.


.. py:function:: flatten_object(array)

   Flatten a numpy object array.


.. py:function:: hdf52dict(hdf5_file)

.. py:function:: intersection_indices(array1: numpy.typing.NDArray, array2: numpy.typing.NDArray)

   Get the indices of the intersection between two sorted arrays in increasing order.

   For example, if array1 is [0.1, ..., 0.3, ..., 3] and array2 is interval [0.3, ..., 3, ..., 28], then the output
   indices will be the indices corresponding to [0.3, ..., 3] in both arrays.

   Args:
       array1: the first array
       array2: the second array

   Returns:
       The indices of the intersection between both arrays, for the first and the second array.


.. py:function:: list_str2str(list_str, separator: str = ', ')

   Convert a list of strings into a string in which each input string is quoted and separated by 'separator'.
   Example:
       >>> list_str2str(('AA', 'BBB', 'C'))
       >>> "'AA', 'BBB', 'C'"


.. py:function:: load_csv(file, **kwargs)

.. py:function:: remove_mask(data, data_uncertainties)

   Remove masked values of 3D data and linked uncertainties. TODO generalize this
   An array of objects is created if the resulting array is jagged.

   Args:
       data: 3D masked array
       data_uncertainties: 3D masked array

   Returns:
       The data and errors without the data masked values, and the mask of the original data array.


.. py:function:: savez_compressed_record(file, numpy_record_array)

   Apply numpy.savez_compressed on a record array.


.. py:function:: topological_sort(source)

   Perform topological sort on a dictionary.

   Source: https://stackoverflow.com/questions/11557241/python-sorting-a-dependency-list

   Args:
       source: dictionary of {name: [list of dependencies]} pairs

   Returns:
       list of names, with dependencies listed first


.. py:function:: tuple_init(arg)

.. py:function:: user_input(introduction_message: str, input_message: str, failure_message: str, cancel_message: str, mode: str, max_attempts: int = 5, list_length: int = None) -> str | int | None