# Harmonic

We resurrect the infamous harmonic mean estimator for computing the marginal likelihood (Bayesian evidence) and solve its problematic large variance. The marginal likelihood is a key component of Bayesian model selection since it is required to evaluate model posterior probabilities; however, its computation is challenging. The original harmonic mean estimator, first proposed in 1994 by Newton and Raftery, involves computing the harmonic mean of the likelihood given samples from the posterior. It was immediately realised that the original estimator can fail catastrophically since its variance can become very large and may not be finite. A number of variants of the harmonic mean estimator have been proposed to address this issue although none have proven fully satisfactory.

We present the learnt harmonic mean estimator, a variant of the original estimator that solves its large variance problem. This is achieved by interpreting the harmonic mean estimator as importance sampling and introducing a new target distribution. The new target distribution is learned to approximate the optimal but inaccessible target, while minimising the variance of the resulting estimator. Since the estimator requires samples of the posterior only it is agnostic to the strategy used to generate posterior samples.

For an accessible overview of the learnt harmonic mean estimator please see this Towards Data Science article.

## How to use this guide

To get started, follow the installation guide. For a brief background of the learnt harmonic mean estimator please see the background section of this guide, which provides sufficient background to inform the practioner. For further background details please see the related paper (McEwen et al. 2021). We have also provided tutorials, comprised of a number of interactive notebooks that provide a step-by-step guide to get harmonic up and running for your particular application. An up-to-date catalog of the software functionality can be found on the API page.

## Basic usage

First you will want to install harmonic, which is as simple as running:

```pip install harmonic
```

Now, suppose you have collected many posterior samples, perhaps drawn using emcee or another sampler, and a posteriori wish to compute the evidence, you would do something like:

```import numpy as np
import harmonic as hm

# Instantiate harmonic's chains class
chains = hm.Chains(n)

# Split the chains into the ones which will be used to train the machine learning model and for inference
chains_train, chains_infer = hm.utils.split_data(chains, training_proportion=0.5)

# Select a machine learning model and train it
model = hm.model.[select a model](model hyper-parameters)
fit_success = model.fit(chains_train.samples, chains_train.ln_posterior)

# Instantiate harmonic's evidence class
ev = hm.Evidence(chains_infer.nchains, model)

# Pass the evidence class the inference chains and compute the evidence!