github ↗
docs menu

Module Norn.Summary

Summaries of draws, with their findings.

A summary has a row per element of the draws, such as theta[3], and a column per statistic: the mean, the standard deviation, the 5%, 50% and 95% quantiles, the Monte Carlo standard error of the mean, the bulk and tail effective sample sizes and R-hat (Norn.Diag). Its findings are the problems those numbers and the transitions' statistics show, as data: there are no warnings. A summary of weighted draws (of_weighted) has the columns that weights allow, and judges the weights instead of the chains.

ocaml
Format.printf "%a@." Norn.Summary.pp (Norn.Summary.v schools ~stats post)
#type t

The type for summaries.

#type finding =
  1. #| Rhat_high of {
    1. #path : Nx.Ptree.Path.t;
    2. #index : int array;
    3. #rhat : float;
    }
    (*

    R-hat above 1.01: split R-hat without superchains, nested R-hat with them.

    *)
  2. #| Ess_low of {
    1. #path : Nx.Ptree.Path.t;
    2. #index : int array;
    3. #bulk : float;
    4. #tail : float;
    }
    (*

    A bulk or tail effective sample size below 100 per chain, or below 400 in total with superchains.

    *)
  3. #| Not_finite of {
    1. #path : Nx.Ptree.Path.t;
    2. #index : int array;
    3. #count : int;
    }
    (*

    count of the element's draws are NaN or infinite: it has no diagnostic.

    *)
  4. #| Constant of {
    1. #path : Nx.Ptree.Path.t;
    2. #index : int array;
    }
    (*

    Every draw of the element is equal: it has no R-hat nor effective size.

    *)
  5. #| Divergent of {
    1. #count : int;
    2. #total : int;
    3. #regions : region list;
    }
    (*

    count of the total transitions diverged.

    *)
  6. #| Saturated of {
    1. #count : int;
    2. #total : int;
    }
    (*

    count of the total transitions reached their maximum length before they turned.

    *)
  7. #| Ebfmi_low of {
    1. #chain : int;
    2. #ebfmi : float;
    }
    (*

    A chain's E-BFMI is below 0.3.

    *)
  8. #| Pareto_k of {
    1. #khat : float;
    2. #threshold : float;
    }
    (*

    The k̂ of the raw weights (Norn.Diag.psis) is above threshold, min (1 - 1 / log10 S, 0.7) for S draws, or NaN, so that estimates from them are unreliable or cannot be judged.

    *)

The type for findings. A finding about an element names it by the path of its tensor and its index in the tensor.

#and region = {
  1. #path : Nx.Ptree.Path.t;
  2. #index : int array;
  3. #shift : float;
}

The type for where divergences gather: an element whose draws from transitions that diverged have a mean shift standard deviations from its mean, by more than one (Norn.Diag.divergent_shift).

#val v : ('u, 'd) Nx.Ptree.t -> ?stats:('f, 'd) Stats.t Draws.t -> ?superchains:int -> 'u Draws.t -> t

v u ?stats ?superchains d summarises the draws d of u. stats, the transitions' statistics, adds the findings on divergences, depth and E-BFMI. superchains takes the chains as that many consecutive groups for Norn.Diag.nested_rhat, which then fills the rhat column.

The statistics are computed at float64, whatever the draws' dtype.

Raises Invalid_argument if the chains have fewer than 4 draws, if superchains does not divide the chains, and as Norn.Diag does for a tensor that is not of a float dtype.

#val of_weighted : ('u, 'd) Nx.Ptree.t -> ('u, 'f, 'd) Weighted.t -> t

of_weighted u w summarises the weighted draws w of u, their log weights raw: it smooths them as Norn.Diag.psis does, and judges them by the raw weights' k̂. With x_s an element's draws and w̃_s the smoothed weights normalised, its columns are the mean μ = Σ w̃_s x_s, the standard deviation sqrt (Σ w̃_s (x_s - μ)²), the 5%, 50% and 95% quantiles, the Monte Carlo standard error of the mean of independent draws sqrt (Σ w̃_s² (x_s - μ)²), and the mean's effective sample size, the variance over that error squared. A quantile interpolates linearly between the draws of positive weight in order, the j-th at the middle of its weight, w̃_1 + ... + w̃_(j-1) + w̃_j / 2. Its findings are each element's Not_finite and Constant, in row order, then Pareto_k. The statistics are computed at float64.

Raises Invalid_argument if w.log_weights is not of shape [n], or if a tensor of w.values has no leading axis of n, naming the path.

#val concat : t list -> t

concat ss is the rows and findings of ss, in order: derived quantities summarised beside parameters.

Raises Invalid_argument if the summaries' columns differ, as those of chains and of weighted draws do.

#val findings : t -> finding list

findings s is s's findings, the elements' in row order, then the transitions'.

#val labels : t -> string array

labels s is s's row labels: an element's path, then its index in brackets for a tensor that is not a scalar, as theta[3] or b[1,0]. At the root path, a tensor is labelled by its index alone, and a scalar value.

#val columns : t -> (string * Nx.host Nx.float64_t) list

columns s is s's columns, each a vector with one element per row: mean, sd, q5, median, q95, mcse, then ess_bulk, ess_tail and rhat for chains, ess for weighted draws.

#val pp_finding : Stdlib.Format.formatter -> finding -> unit

pp_finding ppf f formats f as a sentence.

#val pp : Stdlib.Format.formatter -> t -> unit

pp ppf s formats s as a table, then its findings, one per line.