Multichain diagnostics

All three functions consume numerical observations rather than run objects. See Fidelity, diagnostics and uncertainty for the workflow and Observable compilation, decoding and statistics for the algorithms.

Input shape and unresolved values

values must convert to a finite float64 array with shape (chains,records), at least two chains and four records per chain. Ragged, nonfinite, one-dimensional or insufficient input raises. Each method splits chains internally once; for odd lengths it uses the first and last floor(records/2) values. An admitted input can still yield an unresolved estimate.

rank_normalized_split_rhat

hcphases.rank_normalized_split_rhat(values)

Computes the maximum of rank-normalized split Rhat and its folded version. Folding uses absolute deviations from the pooled median. Ranks pool all split chains and average ties. The returned dictionary includes rhat, status, components (rank/folded), within_chain_variance and between_chain_variance. Those variance fields are on the rank-normalized scale, not physical observable units.

If rank or folded within-chain variation vanishes, rhat is None and status is "unresolved_degenerate_rank_or_folded". Otherwise status is "estimated". The finite-sample estimate can be slightly below one. The function imposes no convergence threshold.

bulk_ess

hcphases.bulk_ess(values)

Rank-normalizes the once-split chains and estimates multichain effective sample size using FFT autocovariances and an initial-positive/monotone sequence. An estimated result includes ess, integrated_autocorrelation_time, status="estimated", within/between-chain variances, positive_pairs, sample_count_after_one_split and tau_lower_bound_applied.

Insufficient split length returns zero ESS with "unresolved_insufficient_split_length". Zero within-chain or total variance returns zero ESS with "unresolved_zero_within_chain_variance". Zero is an unresolved sentinel in these cases, not a physical sample-size certificate. Antithetic histories can have estimated ESS above the retained record count.

tail_ess

hcphases.tail_ess(values, probability=0.05)

probability=0.05 must be finite and strictly between zero and 0.5. The function estimates ESS for indicators x<=q_p and x<=q_(1-p), with pooled empirical quantiles and internal splitting. It returns the minimum of the two when both are estimated, otherwise ess=None and status="unresolved_degenerate_tail". The dictionary also records lower_quantile, upper_quantile, the full lower/upper ESS reports, probability and the precise indicator definition.

Discrete values or ties can make a tail indicator constant even when the original series varies. Such unavailability must remain explicit. None of these three methods produces a confidence interval or a scientific pass/fail decision for the original expectation.