:py:mod:`nessai.reparameterisations` ==================================== .. py:module:: nessai.reparameterisations .. autoapi-nested-parse:: Functions and objects related to reparametersiations for use in the ``reparameterisations`` dictionary. See the documentation for an in-depth description of how to use these functions and classes. .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: nessai.reparameterisations.Reparameterisation nessai.reparameterisations.CombinedReparameterisation nessai.reparameterisations.NullReparameterisation nessai.reparameterisations.Rescale nessai.reparameterisations.RescaleToBounds nessai.reparameterisations.Angle nessai.reparameterisations.ToCartesian nessai.reparameterisations.AnglePair Functions ~~~~~~~~~ .. autoapisummary:: nessai.reparameterisations.get_reparameterisation Attributes ~~~~~~~~~~ .. autoapisummary:: nessai.reparameterisations.logger nessai.reparameterisations.default_reparameterisations .. py:data:: logger .. !! processed by numpydoc !! .. py:function:: get_reparameterisation(reparameterisation, defaults=None) Function to get a reparameterisation class from a name :Parameters: **reparameterisation** : str, :obj:`nessai.reparameterisations.Reparameterisation` Name of the reparameterisations to return or a class that inherits from :obj:`~nessai.reparameterisations.Reparameterisation` **defaults** : dict, optional Dictionary of known reparameterisations that overrides the defaults. :Returns: :obj:`nessai.reparameteristaions.Reparameterisation` Reparameterisation class. dict Keyword arguments for the specific reparameterisation. .. !! processed by numpydoc !! .. py:class:: Reparameterisation(parameters=None, prior_bounds=None) Base object for reparameterisations. :Parameters: **parameters** : str or list Name of parameters to reparameterise. **prior_bounds** : list, dict or None Prior bounds for the parameter(s). .. !! processed by numpydoc !! .. py:attribute:: has_prior :annotation: = False .. !! processed by numpydoc !! .. py:attribute:: has_prime_prior :annotation: = False .. !! processed by numpydoc !! .. py:attribute:: requires_prime_prior :annotation: = False .. !! processed by numpydoc !! .. py:attribute:: requires_bounded_prior :annotation: = False .. !! processed by numpydoc !! .. py:attribute:: prior_bounds .. !! processed by numpydoc !! .. py:attribute:: prime_prior_bounds .. !! processed by numpydoc !! .. py:method:: name(self) :property: Unique name of the reparameterisations .. !! processed by numpydoc !! .. py:method:: reparameterise(self, x, x_prime, log_j) :abstractmethod: Apply the reparameterisation to convert from x-space to x'-space. :Parameters: **x** : structured array Array of inputs **x_prime** : structured array Array to be update **log_j** : array_like Log jacobian to be updated :Returns: **x, x_prime** : structured arrays Update version of the x and x_prime arrays **log_j** : array_like Updated log Jacobian determinant .. !! processed by numpydoc !! .. py:method:: inverse_reparameterise(self, x, x_prime, log_j) :abstractmethod: Apply the reparameterisation to convert from x-space to x'-space :Parameters: **x** : structured array Array **x_prime** : structured array Array to be update **log_j** : array_like Log jacobian to be updated :Returns: **x, x_prime** : structured arrays Update version of the x and x_prime arrays **log_j** : array_like Updated log Jacobian determinant .. !! processed by numpydoc !! .. py:class:: CombinedReparameterisation(reparameterisations=None) Bases: :py:obj:`dict` Class to handle multiple reparameterisations :Parameters: **reparameterisations** : list, optional List of reparameterisations to add to the combined reparameterisations. Further reparameterisations can be added using `add_reparameterisations`. .. !! processed by numpydoc !! .. py:method:: has_prime_prior(self) :property: Boolean to check if prime prior can be enabled .. !! processed by numpydoc !! .. py:method:: requires_prime_prior(self) :property: Boolean to check if any of the priors require the prime space .. !! processed by numpydoc !! .. py:method:: add_reparameterisation(self, reparameterisation) Add a reparameterisation .. !! processed by numpydoc !! .. py:method:: add_reparameterisations(self, reparameterisations) Add multiple reparameterisations :Parameters: **reparameterisations** : list of :`obj`:Reparameterisation List of reparameterisations to add. .. !! processed by numpydoc !! .. py:method:: reparameterise(self, x, x_prime, log_j, **kwargs) Apply the reparameterisation to convert from x-space to x'-space :Parameters: **x** : structured array Array **x_prime** : structured array Array to be update **log_j** : array_like Log jacobian to be updated .. !! processed by numpydoc !! .. py:method:: inverse_reparameterise(self, x, x_prime, log_j, **kwargs) Apply the reparameterisation to convert from x-space to x'-space :Parameters: **x** : structured array Array **x_prime** : structured array Array to be update **log_j** : array_like Log jacobian to be updated .. !! processed by numpydoc !! .. py:method:: update_bounds(self, x) Update the bounds used for the reparameterisation .. !! processed by numpydoc !! .. py:method:: reset_inversion(self) Reset edges for boundary inversion .. !! processed by numpydoc !! .. py:method:: log_prior(self, x) Compute any additional priors for auxiliary parameters .. !! processed by numpydoc !! .. py:method:: x_prime_log_prior(self, x_prime) Compute the prior in the prime space .. !! processed by numpydoc !! .. py:class:: NullReparameterisation(parameters=None, prior_bounds=None) Bases: :py:obj:`Reparameterisation` Reparameterisation that does not modify the parameters. :Parameters: **parameters** : list or str Parameters for which the reparameterisation will be used. **prior_bounds** : list, dict or None Prior bounds for parameters. Unused for this reparameterisation. .. !! processed by numpydoc !! .. py:method:: reparameterise(self, x, x_prime, log_j, **kwargs) Apply the reparameterisation to convert from x-space to x'-space :Parameters: **x** : structured array Array **x_prime** : structured array Array to be update **log_j** : Log jacobian to be updated .. .. !! processed by numpydoc !! .. py:method:: inverse_reparameterise(self, x, x_prime, log_j, **kwargs) Apply the reparameterisation to convert from x-space to x'-space :Parameters: **x** : structured array Array **x_prime** : structured array Array to be update **log_j** : Log jacobian to be updated .. .. !! processed by numpydoc !! .. py:class:: Rescale(parameters=None, scale=None, prior_bounds=None) Bases: :py:obj:`Reparameterisation` Reparameterisation that rescales the parameters by a constant factor that does not depend on the prior bounds. :Parameters: **scale** : float Scaling constant. .. !! processed by numpydoc !! .. py:attribute:: requires_bounded_prior :annotation: = False .. !! processed by numpydoc !! .. py:method:: reparameterise(self, x, x_prime, log_j, **kwargs) Apply the reparameterisation to convert from x-space to x'-space :Parameters: **x** : structured array Array **x_prime** : structured array Array to be update **log_j** : Log jacobian to be updated .. .. !! processed by numpydoc !! .. py:method:: inverse_reparameterise(self, x, x_prime, log_j, **kwargs) Apply the reparameterisation to convert from x-space to x'-space :Parameters: **x** : structured array Array **x_prime** : structured array Array to be update **log_j** : Log jacobian to be updated .. .. !! processed by numpydoc !! .. py:class:: RescaleToBounds(parameters=None, prior_bounds=None, prior=None, rescale_bounds=None, boundary_inversion=None, detect_edges=False, inversion_type='split', detect_edges_kwargs=None, offset=False, update_bounds=True, pre_rescaling=None, post_rescaling=None) Bases: :py:obj:`Reparameterisation` Reparameterisation that maps to the specified interval. By default the interval is [-1, 1]. Also includes options for boundary inversion. This reparameterisation can handle multiple parameters. :Parameters: **parameters** : list of str List of the names of parameters **prior_bounds** : dict Dictionary of prior bounds for each parameter. Does not need to be specified by the user. **rescale_bounds** : list of tuples, optional Bounds to rescale to. **update_bounds** : bool, optional Enable or disable updating bounds. **prior** : {'uniform', None} Type of prior used, if uniform prime prior is enabled. **boundary_inversion** : bool, list, dict, optional Configuration for boundary inversion. If a list, inversion is only applied to the parameters in the list based on `inversion_type`. If a `dict` then each item should be a parameter and a corresponding inversion type `{'split', 'inversion'}`. **detect_edges** : bool, optional Enable or disable edge detection for inversion. **detect_edges_kwargs** : dict, optional Dictionary of kwargs used to configure edge detection. **offset** : bool, optional Enable or disable offset subtraction. If `True` then the mean value of the prior is subtract of the parameter before the rescaling is applied. This is computed and applied after the 'pre-rescaling' if it has been specified. **pre_rescaling** : tuple of functions A function that applies a rescaling prior to the main rescaling and its inverse. Each function should return a value and the log-Jacobian determinant. **post_rescaling** : tuple of functions or {'logit} A function that applies a rescaling after to the main rescaling and its inverse. Each function should return a value and the log-Jacobian determinant. For example applying a logit after rescaling to [0, 1]. .. !! processed by numpydoc !! .. py:attribute:: requires_bounded_prior :annotation: = True .. !! processed by numpydoc !! .. py:method:: configure_pre_rescaling(self, pre_rescaling) Configure the rescaling applied before the standard rescaling. Used in :code:`DistanceReparameterisation`. :Parameters: **pre_rescaling** : str or Tuple[Callable, Callable] Name of the pre-rescaling of tuple contain the forward and inverse functions that should return the rescaled value and the Jacobian. .. !! processed by numpydoc !! .. py:method:: configure_post_rescaling(self, post_rescaling) Configure the rescaling applied after the standard rescaling. Used to apply the logit/sigmoid transforms after rescaling to [0, 1] :Parameters: **post_rescaling** : str or Tuple[Callable, Callable] Name of the post-rescaling of tuple contain the forward and inverse functions that should return the rescaled value and the Jacobian. .. !! processed by numpydoc !! .. py:method:: pre_rescaling(self, x) Function applied before rescaling to bounds .. !! processed by numpydoc !! .. py:method:: pre_rescaling_inv(self, x) Inverse of function applied before rescaling to bounds .. !! processed by numpydoc !! .. py:method:: post_rescaling(self, x) Function applied after rescaling to bounds .. !! processed by numpydoc !! .. py:method:: post_rescaling_inv(self, x) Inverse of function applied after rescaling to bounds .. !! processed by numpydoc !! .. py:method:: reparameterise(self, x, x_prime, log_j, compute_radius=False, **kwargs) Rescale inputs to the prime space :Parameters: **x, x_prime** : array_like Arrays of samples in the physical and prime space **log_j** : array_like Array of values of log-Jacobian **compute_radius** : bool, optional If true force duplicate for inversion **kwargs** Parsed to inversion function .. !! processed by numpydoc !! .. py:method:: inverse_reparameterise(self, x, x_prime, log_j, **kwargs) Map inputs to the physical space from the prime space .. !! processed by numpydoc !! .. py:method:: reset_inversion(self) Reset the edges for inversion .. !! processed by numpydoc !! .. py:method:: set_bounds(self, prior_bounds) Set the initial bounds for rescaling .. !! processed by numpydoc !! .. py:method:: update_bounds(self, x) Update the bounds used for the reparameterisation .. !! processed by numpydoc !! .. py:method:: update_prime_prior_bounds(self) Update the prior bounds used for the prime prior .. !! processed by numpydoc !! .. py:method:: x_prime_log_prior(self, x_prime) Compute the prior in the prime space assuming a uniform prior .. !! processed by numpydoc !! .. py:class:: Angle(parameters=None, prior_bounds=None, scale=1.0, prior=None) Bases: :py:obj:`Reparameterisation` Reparameterisation for a single angle. This reparameterisations converts an angle to Cartesian coordinates using either a corresponding radial parameter or an auxiliary radial parameter. When using the auxiliary parameter, samples are drawn from a chi-distribution with two degrees of freedom. :Parameters: **parameters** : str or list Parameter(s) to use for the reparameterisation. Either just an angle or an angle and corresponding radial parameter **prior_bounds** : dict Dictionary of prior bounds. Does not need to be specified when defining `reparameterisations`. **scale** : float, optional Value used to rescale the angle before converting to Cartesian coordinates. If None the scale will be set to 2pi / prior_bounds. **prior** : {'uniform', 'sine', None} Type of prior being used for sampling this angle. If specified, the prime prior is enabled. If None then it is disabled. .. !! processed by numpydoc !! .. py:attribute:: requires_bounded_prior :annotation: = True .. !! processed by numpydoc !! .. py:method:: angle(self) :property: The name of the angular parameter .. !! processed by numpydoc !! .. py:method:: radial(self) :property: The name of the radial parameter .. !! processed by numpydoc !! .. py:method:: radius(self) :property: The name of the radial parameter (equivalent to radial) .. !! processed by numpydoc !! .. py:method:: x(self) :property: The name of x coordinate .. !! processed by numpydoc !! .. py:method:: y(self) :property: The name of y coordinate .. !! processed by numpydoc !! .. py:method:: reparameterise(self, x, x_prime, log_j, **kwargs) Convert the angle to Cartesian coordinates .. !! processed by numpydoc !! .. py:method:: inverse_reparameterise(self, x, x_prime, log_j, **kwargs) Convert from Cartesian to an angle and radial component .. !! processed by numpydoc !! .. py:method:: log_prior(self, x) Prior for radial parameter .. !! processed by numpydoc !! .. py:method:: x_prime_log_prior(self, x_prime) Compute the prior in the prime space assuming a uniform prior .. !! processed by numpydoc !! .. py:class:: ToCartesian(mode='split', scale=np.pi, **kwargs) Bases: :py:obj:`Angle` Convert a parameter to Cartesian coordinates .. !! processed by numpydoc !! .. py:class:: AnglePair(parameters=None, prior_bounds=None, prior=None, convention=None) Bases: :py:obj:`Reparameterisation` Reparameterisation for a pair of angles and a radial component. Converts to three-dimensional Cartesian coordinates. If the radial component is not specified, it is sampled from a chi- distribution with three degrees of freedom. :Parameters: **parameters** : list List of parameters. Must contain at least the two angles and, optionally, also a radial component. **prior_bounds** : dict Dictionary of prior bounds for each parameter **prior** : str, {'isotropic', None} Type of prior, used to enable use of the prime prior. **convention** : str, {'ra-dec', 'az-zen'} Convention used for defining the spherical polar coordinates. If not set, it will be guessed based on either dec or zen. Where it is assumed declination is defined on [-pi/2, pi/2] and zenith on [0, pi]. .. rubric:: Notes The parameters will be reordered such that the first parameter is the angle along the horizon, the second parameter is the vertical angle and the last parameter is the radial parameter. .. !! processed by numpydoc !! .. py:attribute:: requires_bounded_prior :annotation: = True .. !! processed by numpydoc !! .. py:attribute:: known_priors :annotation: = ['isotropic', None] .. !! processed by numpydoc !! .. py:method:: angles(self) :property: Names of the two angles. Order is: angle along the horizon, vertical angle. .. !! processed by numpydoc !! .. py:method:: radial(self) :property: Name of the radial parameter .. !! processed by numpydoc !! .. py:method:: x(self) :property: Name of the first Cartesian coordinate .. !! processed by numpydoc !! .. py:method:: y(self) :property: Name of the second Cartesian coordinate .. !! processed by numpydoc !! .. py:method:: z(self) :property: Name of the third Cartesian coordinate .. !! processed by numpydoc !! .. py:method:: reparameterise(self, x, x_prime, log_j, **kwargs) Convert the spherical polar angles to Cartesian coordinates .. !! processed by numpydoc !! .. py:method:: inverse_reparameterise(self, x, x_prime, log_j, **kwargs) Convert from Cartesian to spherical polar angles .. !! processed by numpydoc !! .. py:method:: log_prior(self, x) Prior for radial parameter .. !! processed by numpydoc !! .. py:method:: x_prime_log_prior(self, x_prime) Log probability of 3d Cartesian coordinates for an isotropic distribution of angles and a radial component drawn from a chi distribution with three degrees of freedom. .. !! processed by numpydoc !! .. py:data:: default_reparameterisations .. !! processed by numpydoc !!