Importance nested sampler

Importance nested sampler#

In Williams et al. 2023, we proposed importance nested sampling with normalising flows and called the algorithm i-nessai. The algorithm described there is available in nessai alongside the standard algorithm.

Important

The API for the importance nested sampler is still under-development and may change between minor versions.

Basic usage#

The importance nested sampler is implemented in ImportanceNestedSampler and, just like standard nessai, it can be run through the FlowSampler class. To do so, simply set importance_nested_sampler=True when creating the instance of FlowSampler. The sampler is then run using the nessai.flowsampler.FlowSampler.run(), e.g.

from nessai.flowsampler import FlowSampler

sampler = FlowSampler(
    GaussianModel(),
    output="output/",
    nlive=5000,
    importance_nested_sampler=True,
)
sampler.run()

Important

The importance nested sampler requires the user to define the methods to_unit_hypercube and from_unit_hypercube in the model class, see the examples linked below.

Configuration#

All keyword arguments passed to FlowSampler will in turn be passed to either ImportanceNestedSampler or ImportanceFlowProposal. We now highlight some key settings, for a complete list see the documentation for the two classes,

  • nlive: more complex problems will often need larger nlive,

  • threshold_kwargs: dictionary of keyword arguments for determining the likelihood threshold, the most important is q (\(\rho\) in the paper),

  • reparameterisation: either 'logit' or None, the former should be used in most cases, unless the flow has the domain on \([0, 1]^n\),

  • flow_config: identical to the standard sampler, see Normalising flows configuration for details,

  • reset_flow: reset the flow before training every ith iteration,

Stopping criterion#

By default, the stopping criterion is the log-ratio of the evidence above the likelihood threshold and the current evidence, called ratio in the code. The default tolerance is tolerance=0.0 and should be suitable for most applications.

Logging#

By default the sampler will log every iteration and the log will look something like this:

07-01 08:46 nessai.samplers.importancesampler INFO    : Removing 1830/3000 samples to train next proposal
07-01 08:46 nessai.samplers.importancesampler INFO    : Log-likelihood threshold: -487.90392013926345
07-01 08:46 nessai.samplers.importancesampler INFO    : Training next proposal with 1170 samples
07-01 08:46 nessai.samplers.importancesampler INFO    : Drawing 2000 samples from the new proposal
07-01 08:46 nessai.samplers.importancesampler INFO    : Stopping criteria (['ratio']): [0.638027881338866] - Tolerance: [0.0]
07-01 08:46 nessai.samplers.importancesampler INFO    : Update 1 - log Z: -5.804 +/- 0.089 ESS: 123.7 logL min: -3874.530 logL median: -96.682 logL max: -0.015

From top to bottom this shows:

  • the number of samples discarded to train the next proposal (flow),

  • the corresponding log-likelihood threshold,

  • the start of the training stage with n samples,

  • the number of samples being drawn from the new proposal,

  • the current values of all stopping criteria and the corresponding tolerance,

  • a summary of statistics at the end of the current iteration, this shows:

    • the log-evidence,

    • the effective sample size of the posterior,

    • the minimum, median and maximum log-likelihood of the current set of live samples.

Output#

The importance nested sampler returns:

  • a result file, by default result.h5,

    • samples contains the final samples drawn from meta-proposal,

    • log_evidence is the final estimate of the log-evidence,

  • a state plot (state.png), this is similar to the state plot for the standard sampler,

  • a trace plot (trace.png), this is similar to the trace plot from the standard sampler but plots the ratio of the prior and the meta-proposal on the x-axis,

  • a levels plot (levels.png), this shows the log-likelihood distribution for each proposal.

Examples#

For basic examples, see the examples directory.

Gravitational-wave inference#

The importance nested sampler is not currently supported in bilby but will be in a future release.