class harmonic.Evidence(nchains: int, model, shift=Shifting.MEAN_SHIFT)

Compute inverse evidence values from chains, using posterior model.

Multiple chains can be added in sequence (to avoid having to store very long chains).

__init__(nchains: int, model, shift=Shifting.MEAN_SHIFT)

Construct evidence class for computing inverse evidence values from set number of chains and initialised posterior model.

Parameters:

  • nchains (int) – Number of chains that will be used in the computation.

  • model (Model) – An instance of a posterior model class that has been fitted.

  • shift (Shifting) – What shifting method to use to avoid over/underflow during computation. Selected from enumerate class.

Raises:

  • ValueError – Raised if the number of chains is not positive.

  • ValueError – Raised if the number of dimensions is not positive.

  • ValueError – Raised if model not fitted.

add_chains(chains)

Add new chains and calculate an estimate of the inverse evidence, its variance, and the variance of the variance.

Calculations are performed by using running averages of the totals for each chain. Consequently, the method can be called many times with new samples for each chain so that the evidence estimate will improve. The rationale is that not all samples need to be stored in memory for high-dimensional problems. Note that the same number of chains needs to be considered for each call.

Parameters:

chains (Chains) – An instance of the chains class containing the chains to be used in the calculation.

Raises:

  • ValueError – Raised if the input number of chains to not match the number of chains already set up.

  • ValueError – Raised if both max and mean shift are set.

check_basic_diagnostic()

Perform basic diagonstic check on sanity of evidence calculations.

If these tests pass it does not necessarily mean the evidence is accurate and other tests should still be performed.

Returns:

Whether diagnostic tests pass.

Return type:

Boolean

Raises:

Warnings – Raised if the diagnostic tests fail.

compute_evidence()

Compute evidence from the inverse evidence.

Returns:

Tuple containing the following.

  • evidence (double): Estimate of evidence.

  • evidence_std (double): Estimate of standard deviation of evidence.

Return type:

(double, double)

Raises:

ValueError – if inverse evidence or its variance overflows.

compute_ln_evidence()

Compute log_e of evidence from the inverse evidence.

Returns:

Tuple containing the following.

  • ln_evidence (double): Estimate of log_e of evidence.

  • ln_evidence_std (double): Estimate of log_e of standard

    deviation of evidence.

Return type:

(double, double)

compute_ln_inv_evidence_errors()

Compute lower and uppper errors on the log_e of the inverse evidence.

Compute the log-space error \(\hat{\zeta}_\pm\) defined by

\[\log ( \hat{\rho} \pm \hat{\sigma} ) = \log (\hat{\rho}) + \hat{\zeta}_\pm .\]

Computed in a numerically stable way by

\[\hat{\zeta}_\pm = \log(1 \pm \hat{\sigma} / \hat{\rho}) .\]
Returns:

Tuple containing the following.

  • ln_evidence_err_neg (double): Lower error for log_e of inverse evidence.

  • ln_evidence_err_pos (double): Upper error for log_e of inverse evidence.

Return type:

(double, double)

classmethod deserialize(filename)

Deserialize Evidence object from file.

Parameters:

filename (string) – Name of file from which to read evidence object.

Returns:

Evidence object deserialized from file.

Return type:

(Evidence)

get_masks(chain_start_ixs: Array) → Array

Create mask array for a 2D array of concatenated chains of different lengths. :param chain_start_ixs: Start indices of chains

in Chain object.

Returns:

Mask array with each row corresponding to a chain

and entries with boolean values depending on if given sample at that position is in that chain.

Return type:

jnp.ndarray[nchains,nsamples]

process_run()

Use the running totals of realspace running_sum and nsamples_per_chain to calculate an estimate of the inverse evidence, its variance, and the variance of the variance.

This method is ran each time chains are added to update the inverse variance estimates from the running totals.

serialize(filename)

Serialize evidence object.

Parameters:

filename (string) – Name of file to save evidence object.

set_shift(shift_value: float)

Set the shift value of log_e posterior values to aid numerical stability.

Parameters:

shift_value (float) – Shift value.

Raises:

  • ValueError – Raised if shift_value is NaN.

  • ValueError – Raised if one attempts to set shift when another shift is already set.

class harmonic.Shifting(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration to define which log-space shifting to adopt. Different choices may prove optimal for certain settings.

ABS_MAX_SHIFT = 4
MAX_SHIFT = 2
MEAN_SHIFT = 1
MIN_SHIFT = 3
harmonic.evidence.compute_bayes_factor(ev1, ev2)

Compute Bayes factor of two models.

Parameters:

  • ev1 (float) – Evidence value of model 1 with chains added.

  • ev2 (float) – Evidence value of model 2 with chains added.

Returns:

Tuple containing the following.

  • bf12: Estimate of the Bayes factor Z_1 / Z_2.

  • bf12_std: Estimate of the standard deviation of the Bayes factor

    sqrt( var ( Z_1 / Z_2 ) ).

Return type:

(float, float)

Raises:

  • ValueError – Raised if model 1 does not have chains added.

  • ValueError – Raised if model 2 does not have chains added.

  • ValueError – If inverse evidence or its variance for model 1 or model 2 too large to store in non-log space.

harmonic.evidence.compute_ln_bayes_factor(ev1, ev2)

Computes log_e of Bayes factor of two models.

Parameters:

  • ev1 (float) – Evidence object of model 1 with chains added.

  • ev2 (float) – Evidence object of model 2 with chains added.

Returns:

Tuple containing the following.

  • ln_bf12: Estimate of log_e of the Bayes factor ln ( Z_1 / Z_2 ).

  • ln_bf12_std: Estimate of log_e of the standard deviation of the

    Bayes factor ln ( sqrt( var ( Z_1 / Z_2 ) ) ).

Return type:

(float, float)

Raises:

  • ValueError – Raised if model 1 does not have chains added.

  • ValueError – Raised if model 2 does not have chains added.