Reparameterisations

In nessai three spaces are defined:

  • the sampling space \(\mathcal{X}\),

  • the reparameterised sampling space \(\mathcal{X}'\) (or prime space),

  • the latent space \(\mathcal{Z}\).

The key to efficient sampling with nessai is to reparameterise the sampling space such that the prime space is simpler for normalising flow to learn.

There are two main methods for configuring reparameterisations in nessai. The first is simpler but more limited and the second is more complex but allows for greater control of the specific reparameterisations used.

Method 1: general reparameterisation

This method is limited to the following types of reparameterisation:

  • rescaling to a fixed range,

  • applying inversion along a bound.

These can be applied on parameter by parameter basis using keyword arguments. The relevant arguments:

  • rescale_parameters: This is either a bool or list of parameters. If True, then all of the parameters in the model are rescaled. If a list is provided only those parameters are rescaled. It’s generally recommend to rescale parameters to a common range to improve the efficiency of training. The inputs are rescaled to the range defined by rescale_bounds.

  • rescale_bounds: A list of length two containing the upper and lower bounds of the range for rescaling, the default value is [-1, 1].

  • update_bounds: A boolean, if True the minimum and maximum values of parameters are update each time the normalising flow is trained. If False the parameters are always rescaled using the initial prior bounds. It’s recommended to enable this option.

  • boundary_inversion: This is either a bool or list and determines if boundary inversion is applied to any of the parameters. If True it is applied to all parameters and if a list is specified it is only applied to those parameters. This forces the samples for the parameters and one of the bounds to be mirrored along that bound. The bounds is chosen based on the density of samples. It’s not recommended to enable this setting unless there are parameters for which the posterior distributions will consistently rail against the prior bounds. NOTE: this forces update_bounds=True.

  • detect_edges: This setting is only relevant when using boundary_inversion and it allows the sampler to detect hard bounds in the samples (or lack thereof)

Method 2: specific reparameterisations

This methods allows for use of the all the reparameterisations included in nessai. However it requires parameters to be configured individually. All the reparameterisations are configure using the keyword argument reparameterisations which is an instance of dict.

When using this method reparameterisations are added to the proposal method based on the dictionary. Each entry in the reparameterisations dictionary is interpreted and add to the combined reparameterisation that is applied to all parameters. These the following key-value pairs are understood:

  • Parameter & Reparameterisation: the key is the parameter to which the reparameterisation is applied and the reparameterisation to apply. For example reparameterisations={'x': 'default'}, this tells the sampler to use the default reparameterisation for x, which rescales to [-1, 1].

  • Parameter & Kwargs: the key is the same as in the previous case but instead of the name of the reparameterisation, a dictionary with the configuration is specified. For example: reparamterisations={'x': {'reparameterisation': 'default', 'rescale_bounds': [0, 1]}}, this tells the sampler to use the default reparameterisation but with a specific keyword argument rescale_bounds. The resulting reparameterisation will rescale to [0, 1] instead of [-1, 1].

  • Reparameterisation & Kwargs: here the key is the name of reparameterisation and the kwargs are the used to configure the reparameterisation. This dictionary MUST contain the name of the parameter(s) to which the reparameterisation is applied. For example: reparameterisation={'default': {'parameters': ['x'], 'rescale_bounds':[0, 1]}. This applied the default reparameterisation to x but with rescaling to [0, 1]. This method also supports specifying multiple parameters for reparameterisations that support it, for example: reparameterisation={'default': 'parameters': ['x', 'y']}. This is necessary for reparameterisations that are applied to groups of parameters, such as the pairs of angles.

See the examples directory for an example of using this method of defining the reparmeterisations.

Note

Missing section on use of x prime prior

Available reparameterisations

There are a number of pre-configured reparameterisations included in nessai:

  • default: Default rescaling which rescales to [-1, 1] and has :code`update_bounds=True`

  • rescaletobounds: Alias for default

  • inversion: Default rescaling but with inversion and detect_edges enabled for the parameter, uses split inversion.

  • inversion-duplicate: Same as inversion but uses duplicate inversion

  • offset: Equivalent to default but includes an offset before rescaling. This is usual when dealing with parameters which have small prior ranges but are offset from zero by some large constant. For example time, which is typically of order \(10^{9}\)

  • logit: Parameters are rescaled to [0, 1] and a logit is applied. A sigmoid is used for the inverse. Note: update_bounds is disabled by default.

  • angle: Reparameterisation for angles. This reparameterisation introduces an auxiliary radial parameter and converts the angle to Cartesian coordinates.

  • angle-pi: Same as angle but specifically for angles defined on [0, \(\pi\)]

  • angle-sine: Same as angle but for angles with sine priors

  • angle-2pi: Same as angle-pi but for angles defined on [0, \(2\pi\)]

  • angle-pair: Reparameterisation for pairs of angles, see nessai.reparameterisations.AnglePair for details.

  • 'none': No reparameterisation is applied.

For details on each of these reparameterisations see reparameterisations.