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 if points are
   array-like by checking if the first value has `__len__` attribute and
   the number of dimensions is not zero, if not the dictionary is assumed to
   contain a single live 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 !!