bilby.core.sampler.ptemcee.check_iteration

bilby.core.sampler.ptemcee.check_iteration(iteration, samples, sampler, convergence_inputs, search_parameter_keys, time_per_check, beta_list, tau_list, tau_list_n, gelman_rubin_list, mean_log_posterior, verbose=True)[source]

Per-iteration logic to calculate the convergence check.

To check convergence, this function does the following: 1. Calculate the autocorrelation time (tau) for each dimension for each walker,

corresponding to those dimensions in search_parameter_keys that aren’t specifically excluded in ci.ignore_keys_for_tau.

Store the average tau for each dimension, averaged over each walker.

Calculate the Gelman-Rubin statistic (see get_Q_convergence), measuring the convergence of the ensemble of walkers.
Calculate the number of effective samples; we aggregate the total number of burned-in samples (amongst all walkers), divided by a multiple of the current maximum average autocorrelation time. Tuned by ci.burn_in_nact and ci.thin_by_nact.
If the Gelman-Rubin statistic < ci.Q_tol and ci.nsamples < the number of effective samples, we say that our ensemble is converged, setting converged = True.
For some number of the latest steps (set by the autocorrelation time and the GRAD_WINDOW_LENGTH parameter), we find the maxmium gradient of the autocorrelation time over all of our dimensions, over all walkers (autocorrelation time is already averaged over walkers) and the maximum value of the gradient of the mean log posterior over iterations, over all walkers.
If the maximum gradient in tau is less than ci.gradient_tau and the maximum gradient in the mean log posterior is less than ci.gradient_mean_log_posterior, we set tau_usable = True.
If both converged and tau_usable are true, we return stop = True, indicating that our ensemble is converged + burnt in on this iteration.
Also prints progress! (see print_progress)

Parameters:

iteration: int: Number indexing the current iteration, at which we are checking convergence.
samples: np.ndarray: Array of ensemble MCMC samples, shaped like (number of walkers, number of MCMC steps, number of dimensions).
sampler: bilby.core.sampler.Ptemcee: Bilby Ptemcee sampler object; in particular, this function uses the list of walker temperatures stored in sampler.betas.
convergence_inputs: bilby.core.sampler.ptemcee.ConvergenceInputs: A named tuple of the convergence checking inputs
search_parameter_keys: list: A list of the search parameter keys
time_per_check, tau_list, tau_list_n: list: Lists used for tracking the run
beta_list: list: List of floats storing the walker inverse temperatures.
tau_list: list: List of average autocorrelation times for each dimension, averaged over walkers, at each checked iteration. So, an effective shape of (number of iterations so far, number of dimensions).
tau_list_n: list: List of iteration numbers, enumerating the first “axis” of tau_list. E.g. if tau_list_n[1] = 5, this means that the list found at tau_list[1] was calculated on iteration number 5.
gelman_rubin_list: list (floats): list of values of the Gelman-Rubin statistic; the value calculated in this call of check_iteration is appended to the gelman_rubin_list.
mean_log_posterior: np.ndarray: Float array shaped like (number of walkers, number of MCMC steps), with the log of the posterior, averaged over the dimensions.
verbose: bool: Whether to print the output

Returns:

stop: bool: A boolean flag, True if the stopping criteria has been met
burn: int: The number of burn-in steps to discard
thin: int: The thin-by factor to apply
tau_int: int: The integer estimated ACT
nsamples_effective: int: The effective number of samples after burning and thinning

Notes

The gradient of tau is computed with a Savgol-Filter, over windows in sample number of length GRAD_WINDOW_LENGTH. This value must be an odd integer. For ndim > 3, we calculate this as the nearest odd integer to ndim. For ndim <= 3, we calculate this as the nearest odd integer to nwalkers, as typically a much larger window length than polynomial order (default 2) leads to more stable smoothing.