bebi103.hmc.check_all_diagnostics

bebi103.hmc.check_all_diagnostics(samples, adapt_target=0.801, adapt_target_fraction=0.9, efmi_rule_of_thumb=0.2, max_treedepth=10, min_ess_hat_per_chain=100, xi_hat_threshold=0.25, omit=(), omit_array_entry=(), verbosity=2, return_diagnostics=False)

Check all MCMC diagnostics, both HMC and expectand diagnostics.

Parameters:

  • samples (cmdstanpy.CmdStanMCMC instance or dict) – MCMC samples from which to check expectand diagnostics, either as a cmdstanpy.CmdStanMCMC instance or as a dictionary of two-dimensional arrays for each expectand. For the dictionary, the first dimension of each element indexes the Markov chains and the second dimension indexes the sequential states within each Markov chain.

  • adapt_target (float, default 0.801) – Target acceptance proxy statistic for step size adaptation. This should be approximately the prescribed value of adapt_delta in sampling. The default adapt_delta is 0.8, which is why the default adapt_target is 0.801.

  • adapt_target_fraction (float, default 0.9) – Average target acceptance proxy statistic below adapt_target_fraction * adapt_target is flagged as problematic.

  • efmi_rule_of_thumb (float, default 0.2) – EFMI values greater than efmi_rule_of_thumb are flagged.

  • max_treedepth (int, default 10) – Specification of maximum treedepth allowed in MCMC sampling.

  • min_ess_hat_per_chain (float, default 100) – The minimum empirical effective sample size per chain below which a warning is flagged.

  • xi_hat_threshold (float, default 0.25) – Tail xi_hats at or above this value are flagged as warnings. Also passed through to check_expectand_diagnostics().

  • omit (str, re.Pattern, or iterable thereof) – Glob pattern(s) matched against the base (non-indexed) name of each variable. Any variable whose base name matches an entry is omitted, whether scalar or array valued. For example, omit=’*_pred’ omits every variable whose name ends in ‘_pred’. Compiled re.Pattern entries are matched as regular expressions. A single string or pattern may be given instead of an iterable.

  • omit_array_entry (str or iterable of str) – Specific array entries to omit, e.g. ‘y_pred[1]’ or ‘beta[1,2]’. Each entry must include bracketed, comma-separated integer indices. A single string may be given instead of an iterable.

  • verbosity (int, default 2) – Level of verbosity for messages printed to the screen. 0 prints nothing. 1 prints a summary of the diagnostics. 2 prints the summary followed by descriptions of what the triggered diagnostics mean. 3 prints per-chain detail followed by the descriptions.

  • return_diagnostics (bool, default False) – If True, additionally return a dictionary of diagnostic results.

Returns:

  • warning_code (int) – Warning encoded as a nine-bit binary number, with one bit per diagnostic check, using the bit ordering of decode_warning_code(). A bit is set when the corresponding check triggered a warning.

  • diagnostics (dict, returned if return_diagnostics is True) – The outputs of check_hmc_diagnostics() and check_expectand_diagnostics() merged into a single dictionary, {**hmc_diagnostics, **expectand_diagnostics}. From the HMC diagnostics, it contains per-chain summaries of the number of divergences (‘divergences’), the average proxy acceptance statistic (‘average_accept_proxy’), the E-FMI (‘efmi’), and the number of transitions that saturated the maximum treedepth (‘treedepth’), each paired with a Boolean success flag (‘divergences_success’, ‘average_accept_proxy_success’, ‘efmi_success’, and ‘treedepth_success’) that is True when the check passed. From the expectand diagnostics, it contains the keys ‘xi_hat’, ‘variance’, ‘rhat’, ‘inc_tau_hat’, and ‘ess_hat’, whose values are the dictionaries returned by tail_xi_hat(), check_variance(), split_rhat(), tau_hat(), and ess_hat(), respectively.