nessai.livepoint
================

.. py:module:: nessai.livepoint

.. autoapi-nested-parse::

   Functions related to creating live points and converting to other common
   data-types.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   nessai.livepoint.add_extra_parameters_to_live_points
   nessai.livepoint.reset_extra_live_points_parameters
   nessai.livepoint.get_dtype
   nessai.livepoint.empty_structured_array
   nessai.livepoint.live_points_to_array
   nessai.livepoint.parameters_to_live_point
   nessai.livepoint.numpy_array_to_live_points
   nessai.livepoint.dict_to_live_points
   nessai.livepoint.live_points_to_dict
   nessai.livepoint.dataframe_to_live_points
   nessai.livepoint.unstructured_view


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

.. py:function:: add_extra_parameters_to_live_points(parameters, default_values=None)

   
   Add extra parameters to the live points dtype.

   Extra parameters will be included in the live points dtype that is used
   for constructing/converting to/from live points.

   :Parameters:

       **parameters: list**
           List of parameters to add.

       **default_values: Optional[Union[List, Tuple]]**
           List of default values for each parameters. If not specified, default
           values will be set to based on :code: `DEFAULT_FLOAT_VALUE` in
           :code:`nessai.config`.














   ..
       !! processed by numpydoc !!

.. py:function:: reset_extra_live_points_parameters()

   
   Reset the extra live points parameters.
















   ..
       !! processed by numpydoc !!

.. py:function:: get_dtype(names, array_dtype=None, non_sampling_parameters=True)

   
   Get a list of tuples containing the dtypes for the structured array


   :Parameters:

       **names** : list of str
           Names of parameters

       **array_dtype** : Optional[str]
           dtype to use

       **non_sampling_parameters** : bool
           Indicates whether non-sampling parameters should be included.



   :Returns:

       numpy.dtype
           A instance of :code:`numpy.dtype`.











   ..
       !! processed by numpydoc !!

.. py:function:: empty_structured_array(n, names=None, dtype=None, non_sampling_parameters=True)

   
   Get an empty structured array with the extra parameters initialised.


   :Parameters:

       **n** : int
           Length of the structured array

       **dtype** : Optional[list]
           Dtype to use. Must contain the non-sampling parameters.

       **names** : Optional[list]
           Names of fields (excluding non-sampling parameters) to construct the
           dtype. Must be specified if :code:`dtype` is not specified.

       **non_sampling_parameters** : bool
           Indicates whether non-sampling parameters should be included.



   :Returns:

       np.ndarray
           Structured array with the all parameters initialised to their
           default values.











   ..
       !! processed by numpydoc !!

.. py:function:: live_points_to_array(live_points, names=None, copy=False)

   
   Converts live points to unstructured arrays for training.


   :Parameters:

       **live_points** : structured_array
           Structured array of live points

       **names** : list of str or None
           If None all fields in the structured array are added to the dictionary
           else only those included in the list are added.

       **copy** : bool
           If true, returns a copy. If false, returns a view. See numpy
           documentation for
           :code:`numpy.lib.recfunctions.structured_to_unstructured` for more
           details.



   :Returns:

       np.ndarray
           Unstructured numpy array











   ..
       !! processed by numpydoc !!

.. py:function:: parameters_to_live_point(parameters, names, non_sampling_parameters=True)

   
   Take a list or array of parameters for a single live point
   and converts them to a live point.

   Returns an empty array with the correct fields if len(parameters) is zero

   :Parameters:

       **parameters** : tuple
           Float point values for each parameter

       **names** : tuple
           Names for each parameter as strings

       **non_sampling_parameters** : bool
           Indicates whether non-sampling parameters should be included.



   :Returns:

       structured_array
           Numpy structured array with fields given by names plus logP and logL











   ..
       !! processed by numpydoc !!

.. py:function:: numpy_array_to_live_points(array, names, non_sampling_parameters=True)

   
   Convert a numpy array to a numpy structure array with the correct fields


   :Parameters:

       **array** : np.ndarray
           Instance of np.ndarray to convert to a structured array

       **names** : tuple
           Names for each parameter as strings

       **non_sampling_parameters** : bool
           Indicates whether non-sampling parameters should be included.



   :Returns:

       structured_array
           Numpy structured array with fields given by names plus logP and logL











   ..
       !! processed by numpydoc !!

.. py:function:: dict_to_live_points(d, non_sampling_parameters=True)

   
   Convert a dictionary with parameters names as keys to live points.

   Assumes all entries have the same length. Also, determines number of points
   from the first entry by checking if the value has `__len__` attribute,
   if not the dictionary is assumed to contain a single point.

   :Parameters:

       **d** : dict
           Dictionary with parameters names as keys and values that correspond
           to one or more parameters

       **non_sampling_parameters** : bool
           Indicates whether non-sampling parameters should be included.



   :Returns:

       structured_array
           Numpy structured array with fields given by names plus logP and logL











   ..
       !! processed by numpydoc !!

.. py:function:: live_points_to_dict(live_points, names=None)

   
   Convert a structured array of live points to a dictionary with
   a key per field.


   :Parameters:

       **live_points** : structured_array
           Array of live points

       **names** : list of str or None
           If None all fields in the structured array are added to the dictionary
           else only those included in the list are added.



   :Returns:

       dict
           Dictionary of live points











   ..
       !! processed by numpydoc !!

.. py:function:: dataframe_to_live_points(df, non_sampling_parameters=True)

   
   Convert and pandas dataframe to live points.

   Adds the non-sampling parameter initialised to their defaults.

   Based on this answer on Stack Exchange:
   https://stackoverflow.com/a/51280608

   :Parameters:

       **df** : :obj:`pandas.DataFrame`
           Pandas DataFrame to convert to live points

       **non_sampling_parameters** : bool
           Indicates whether non-sampling parameters should be included.



   :Returns:

       structured_array
           Numpy structured array with fields given by column names plus logP and
           logL.











   ..
       !! processed by numpydoc !!

.. py:function:: unstructured_view(x, names=None, dtype=None)

   
   Get an unstructured view of a live points containing certain parameters.

   This is quicker than converting to a unstructured array and does not
   create a copy of the array.

   :Parameters:

       **x** : numpy.ndarray
           Structured array.

       **names** : Optional[Iterable]
           Iterable of parameters to include in the view. Must be specified if
           dtype is None.

       **dtype** : Optional[numpy.dtype]
           Dtype for constructing the unstructured view.



   :Returns:

       numpy.ndarray
           View of x as an unstructured array that contains only the
           parameters in names/dtype. Shape is (x.size, # parameters).











   ..
       !! processed by numpydoc !!