nessai.utils.sampling
=====================

.. py:module:: nessai.utils.sampling

.. autoapi-nested-parse::

   Utilities related to drawing samples.

   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   nessai.utils.sampling.NDimensionalTruncatedGaussian


Functions
---------

.. autoapisummary::

   nessai.utils.sampling.compute_radius
   nessai.utils.sampling.draw_surface_nsphere
   nessai.utils.sampling.draw_nsphere
   nessai.utils.sampling.draw_uniform
   nessai.utils.sampling.draw_gaussian
   nessai.utils.sampling.draw_truncated_gaussian


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

.. py:function:: compute_radius(n, q=0.95)

   
   Compute the radius that contains a fraction of the total probability          in an n-dimensional unit Gaussian.

   Uses the inverse CDF of a chi-distribution with n degrees of freedom.

   :Parameters:

       **n** : int
           Number of dimensions

       **q** : float
           Fraction of the total probability



   :Returns:

       float
           Radius











   ..
       !! processed by numpydoc !!

.. py:function:: draw_surface_nsphere(dims, r=1, N=1000, rng=None)

   
   Draw N points uniformly from  n-1 sphere of radius r using Marsaglia's
   algorithm. E.g for 3 dimensions returns points on a 'regular' sphere.

   See Marsaglia (1972)

   :Parameters:

       **dims** : int
           Dimension of the n-sphere

       **r** : float, optional
           Radius of the n-sphere, if specified it is used to rescale the samples

       **N** : int, optional
           Number of samples to draw



   :Returns:

       ndarray
           Array of samples with shape (N, dims)











   ..
       !! processed by numpydoc !!

.. py:function:: draw_nsphere(dims, r=1, N=1000, fuzz=1.0, rng=None)

   
   Draw N points uniformly within an n-sphere of radius r


   :Parameters:

       **dims** : int
           Dimension of the n-sphere

       **r** : float, optional
           Radius of the n-ball

       **N** : int, optional
           Number of samples to draw

       **fuzz** : float, optional
           Fuzz factor by which to increase the radius of the n-ball



   :Returns:

       ndarray
           Array of samples with shape (N, dims)











   ..
       !! processed by numpydoc !!

.. py:function:: draw_uniform(dims, r=(1, ), N=1000, fuzz=1.0, rng=None)

   
   Draw from a uniform distribution on [0, 1].

   Deals with extra input parameters used by other draw functions

   :Parameters:

       **dims** : int
           Dimension of the n-sphere

       **r** : float, optional
           Radius of the n-ball. (Ignored by this function)

       **N** : int, ignored
           Number of samples to draw

       **fuzz** : float, ignored
           Fuzz factor by which to increase the radius of the n-ball. (Ignored by
           this function)



   :Returns:

       ndarraay
           Array of samples with shape (N, dims)











   ..
       !! processed by numpydoc !!

.. py:function:: draw_gaussian(dims, r=1, N=1000, fuzz=1.0, rng=None, temperature=1)

   
   Wrapper for numpy.random.randn that deals with extra input parameters
   r and fuzz


   :Parameters:

       **dims** : int
           Dimension of the n-sphere

       **r** : float, optional
           Radius of the n-ball

       **N** : int, ignored
           Number of samples to draw

       **fuzz** : float, ignored
           Fuzz factor by which to increase the radius of the n-ball



   :Returns:

       ndarray
           Array of samples with shape (N, dims)











   ..
       !! processed by numpydoc !!

.. py:function:: draw_truncated_gaussian(dims, r, N=1000, fuzz=1.0, var=1, rng=None)

   
   Draw N points from a truncated gaussian with a given a radius


   :Parameters:

       **dims** : int
           Dimension of the n-sphere

       **r** : float
           Radius of the truncated Gaussian

       **N** : int, ignored
           Number of samples to draw

       **fuzz** : float, ignored
           Fuzz factor by which to increase the radius of the truncated Gaussian



   :Returns:

       ndarray
           Array of samples with shape (N, dims)











   ..
       !! processed by numpydoc !!

.. py:class:: NDimensionalTruncatedGaussian(dims: int, radius: float, fuzz: float = 1.0, rng: numpy.random.Generator = None)

   
   Class for sampling from a radially truncated n-dimensional Gaussian


   :Parameters:

       **dims**
           The number of dimensions

       **radius**
           The radius for the truncation

       **fuzz** : float
           The fuzz factor














   ..
       !! processed by numpydoc !!

   .. py:method:: sample(N: int) -> numpy.ndarray

      
      Sample from the distribution.


      :Parameters:

          **n** : int
              Number of samples to draw



      :Returns:

          numpy.ndarray
              Array of samples of shape [n, dims].











      ..
          !! processed by numpydoc !!