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.

The reparameterisations are controlled via three keyword arguments:

  • reparameterisations: dict|str|None: either a dictionary specifying various reparameterisations, a string specifying a single reparameterisation for all parameters or None to use the defaults/fallback. See configuring reparameterisations for more details.

  • fallback_reparameterisations: None|str: reparameterisation use if a reparameterisation has not been specified for a parameter. If None, no reparameterisation is used.

  • use_default_reparameterisations: bool|None: if True any default reparameterisations included in the proposal class, e.g. those in GWFlowProposal will be used for any parameters not specified in reparameterisations. If False, these defaults will be ignored. If None, the behaviour will depende on the proposal class.

  • reverse_reparameterisations: bool: if True, the order of the reparmeterisations will be reversed.

Configuring reparameterisations

The reparameterisations keyword allows for fine-grained configuration of the reparameterisations using a dictionary. Each entry in the reparameterisations dictionary is interpreted and add to the combined reparameterisation that is applied to all parameters. 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. This methods also supports regex for configuring multiple parameters.

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

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.