Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,9 +165,17 @@ released from this line yet.

## Diagnostics

* The printed `summary()` of a `bgm()` or `bgmCompare()` fit no longer shows
the directional flip counts `n0->1` and `n1->0` in its inclusion table. The
columns stay in `summary(fit)$indicator`.
* The pairwise summary table for a `bgm()` fit and the difference summary
tables for a `bgmCompare()` fit no longer include `share_incl`, the proportion
of Monte Carlo variance attributed to uncertainty in inclusion. The reported
effective sample sizes (`n_eff`) are unchanged.

* The inclusion tables of `summary()` for `bgm()` and `bgmCompare()` fits no
longer include the directional transition counts `n0->1` and `n1->0`, either
in the returned object or in the printed output. Their diagnostic columns
are `mean`, `mcse`, `sd`, `n_eff`, and `Rhat`. The co-clustering table under
the stochastic block prior also drops all four transition counts and
`n_eff_mixt`; its diagnostic columns are `mean`, `mcse`, `sd`, and `Rhat`.

* The printed `verdicts()` table closes with the number of verdicts that appear
robust to Monte Carlo error, followed by the number flagged because
Expand Down Expand Up @@ -230,6 +238,11 @@ released from this line yet.

## Deprecations

* `extract_ess(estimator = "mixt")`, the transition-based effective sample size
deprecated in 0.2.0.0, is defunct: the call errors. The transition-based
estimate is no longer computed; `estimator = "rb"`, the default, returns the
effective sample size of the Rao-Blackwellized inclusion draws.

* The `step_size` argument of `sample_ggm_prior()` is deprecated and ignored:
the NUTS warmup sets its own initial step size. The returned `step_size`
field has been removed.
Expand Down
147 changes: 37 additions & 110 deletions R/extractor_functions.R
Original file line number Diff line number Diff line change
Expand Up @@ -225,14 +225,13 @@ extract_indicators.bgmCompare = function(bgms_object) {
#' continuous, the standard MCSE/ESS/split-R-hat machinery applies to it, and
#' the fit summary's inclusion table reports `mcse`, `n_eff`, and `Rhat` on the
#' RB draws. They quantify precision *conditional on exploration*: a stuck chain
#' can show a beautifully converged `J` chain with a high `n_eff`, so read them
#' beside the per-direction flip counts (`n0->1`, `n1->0`), which record the
#' exploration itself and whose asymmetry no symmetric summary recovers. The RB
#' draws vary on almost every edge, including edges whose indicator never
#' flipped; the three columns are `NA` only where the RB draws are constant to
#' double precision, which places the inclusion probability at its numerical
#' bound and the verdict beyond any threshold. All of this is in the fit
#' summary's inclusion table, `summary(fit)$indicator`.
#' can produce apparently converged Rao-Blackwellized inclusion draws with a
#' high `n_eff`. The RB draws vary on
#' almost every edge, including edges whose indicator never flipped; the three
#' columns are `NA` only where the RB draws are constant to double precision,
#' which places the inclusion probability at its numerical bound and the
#' verdict beyond any threshold. All of this is in the fit summary's inclusion
#' table, `summary(fit)$indicator`.
#'
#' @param bgms_object A fitted model object of class `bgms` (from [bgm()])
#' or `bgmCompare` (from [bgmCompare()]).
Expand Down Expand Up @@ -1359,9 +1358,7 @@ extract_pairwise_thresholds = function(bgms_object) {
#'
#' @details
#' The `indicator` element is the split-R-hat of the Rao-Blackwellized
#' inclusion draws, matching the default of [extract_ess()]; the indicator
#' chain's transition-based effective sample size remains available as
#' `extract_ess(fit, estimator = "mixt")` (deprecated).
#' inclusion draws, matching [extract_ess()].
#'
#' One failure mode these diagnostics may miss: chains can agree that an edge
#' is included while disagreeing about the magnitude of its weight, for
Expand Down Expand Up @@ -1469,76 +1466,27 @@ extract_rhat.bgmCompare = function(bgms_object) {
# ------------------------------------------------------------------------------
# indicator_ess_column
# ------------------------------------------------------------------------------
# Resolve the indicator ESS that extract_ess() returns. The default "rb" is the
# continuous ESS of the Rao-Blackwellized inclusion draws, read from the summary
# table, so the NA masking summarize_rb_inclusion() applies carries over
# unchanged. The deprecated "mixt" is the indicator chain's transition-based
# ESS, no longer a summary column; it is recomputed from the raw indicator draws
# for as long as it is accepted. The deprecation warning is raised in the
# generic, where the caller is the user rather than bgms itself.
# The indicator ESS that extract_ess() returns: the continuous ESS of the
# Rao-Blackwellized inclusion draws, read from the summary table, so the NA
# masking summarize_rb_inclusion() applies carries over unchanged. Fits without
# Rao-Blackwellized draws (bgms < 0.2.0.0) carry no n_eff column and error, as
# in extract_posterior_inclusion_probabilities().
#
# Fits without Rao-Blackwellized draws (bgms < 0.2.0.0) carry no n_eff column,
# so a default call falls back to the transition ESS while an explicit
# estimator = "rb" errors, as in
# extract_posterior_inclusion_probabilities().
#
# @param fit The fit object (for the raw indicator draws).
# @param summary_indicator The fit's posterior_summary_indicator table.
# @param estimator Character: "rb" or "mixt" (or the unevaluated
# default vector).
# @param estimator_missing Logical: TRUE if the caller did not supply one.
#
# Returns: numeric vector of ESS values, one per indicator.
# ------------------------------------------------------------------------------
indicator_ess_column = function(fit, summary_indicator, estimator, estimator_missing) {
indicator_ess_column = function(summary_indicator) {
# names(), not $, because $ partial-matches n_eff to a legacy table's
# n_eff_mixt.
has_rb = "n_eff" %in% names(summary_indicator)
estimator = if(estimator_missing && !has_rb) {
"mixt"
} else {
match.arg(estimator, choices = c("rb", "mixt"))
}
if(estimator == "rb") {
if(!has_rb) {
stop(
"This fit carries no Rao-Blackwellized inclusion draws, so the ",
"Rao-Blackwellized effective sample size is unavailable. Refit with ",
"bgms >= 0.2.0.0."
)
}
return(summary_indicator$n_eff)
}

if("n_eff_mixt" %in% names(summary_indicator)) {
return(summary_indicator$n_eff_mixt)
}
indicator_transition_ess(fit)
}


# ------------------------------------------------------------------------------
# indicator_transition_ess
# ------------------------------------------------------------------------------
# Transition-based ESS of the binary indicator chains, recomputed from the raw
# draws. Retained only to keep the deprecated extract_ess(estimator = "mixt")
# working; the quantity is no longer a summary column.
#
# @param fit A bgms or bgmCompare object.
#
# Returns: numeric vector of transition ESS values, one per indicator.
# ------------------------------------------------------------------------------
indicator_transition_ess = function(fit) {
cache = get_fit_cache(fit)
raw = if(is.null(cache)) NULL else cache$raw
if(is.null(raw) || is.null(raw[[1]][["indicator_samples"]])) {
if(!"n_eff" %in% names(summary_indicator)) {
stop(
"This fit carries no raw indicator draws, so the transition-based ",
"effective sample size cannot be recomputed."
"This fit carries no Rao-Blackwellized inclusion draws, so the ",
"Rao-Blackwellized effective sample size is unavailable. Refit with ",
"bgms >= 0.2.0.0."
)
}
ind_stats = .compute_indicator_ess_cpp(combine_chains(raw, "indicator_samples"))
unname(ind_stats[, "n_eff_mixt"])
summary_indicator$n_eff
}


Expand All @@ -1550,11 +1498,11 @@ indicator_transition_ess = function(fit) {
#'
#' @param bgms_object A fitted model object of class `bgms` (from [bgm()])
#' or `bgmCompare` (from [bgmCompare()]).
#' @param estimator Character; which effective sample size to return for the
#' edge (or difference) indicators. `"rb"` (default) returns the ESS of the
#' Rao-Blackwellized inclusion draws. `"mixt"`
#' `r lifecycle::badge("deprecated")` returns the indicator chain's
#' transition-based ESS. Ignored for all other parameter types.
#' @param estimator Character; `"rb"`, the only accepted value, returns the ESS
#' of the Rao-Blackwellized inclusion draws for the edge (or difference)
#' indicators. `"mixt"` `r lifecycle::badge("deprecated")`, the indicator
#' chain's transition-based ESS, was deprecated in bgms 0.2.0.0 and now
#' errors. Ignored for all other parameter types.
#'
#' @return A named list with ESS values for each parameter type present in
#' the model (e.g., `main`, `pairwise`, `indicator`).
Expand All @@ -1569,36 +1517,23 @@ indicator_transition_ess = function(fit) {
#' Rao-Blackwellized draws are constant to double precision, where the
#' inclusion probability is at its numerical bound.
#'
#' `estimator = "mixt"`, the transition-based ESS of the binary indicator chain,
#' is deprecated and no longer a summary column; a call recomputes it from the
#' raw indicator draws and warns. It converts flip counts to an effective sample
#' size through a two-state first-order Markov model that a substantial share of
#' edge chains violate, and the precision of the inclusion probability and its
#' Bayes factor is carried by the Rao-Blackwellized ESS and Monte Carlo standard
#' error. The directional flip counts themselves (`n0->1`, `n1->0`) remain in
#' the inclusion table.
#'
#' Fits made with bgms < 0.2.0.0 carry no Rao-Blackwellized draws; a default
#' call falls back to the transition ESS without warning, while an explicit
#' `estimator = "rb"` errors.
#' For older fits without Rao-Blackwellized inclusion draws, `extract_ess()`
#' stops when extracting indicator ESS. Refit with bgms 0.2.0.0 or later.
#'
#' @seealso [bgm()], [bgmCompare()], [extract_rhat()] for the
#' Rao-Blackwellized indicator R-hat,
#' [extract_posterior_inclusion_probabilities()]
#' @family extractors
#' @export
extract_ess = function(bgms_object, estimator = c("rb", "mixt")) {
if(!missing(estimator) && identical(estimator, "mixt")) {
lifecycle::deprecate_warn(
extract_ess = function(bgms_object, estimator = "rb") {
estimator = match.arg(estimator, choices = c("rb", "mixt"))
if(identical(estimator, "mixt")) {
lifecycle::deprecate_stop(
"0.2.0.0", "extract_ess(estimator = 'no longer supports \"mixt\"')",
details = paste(
"The transition-based effective sample size no longer bears on any",
"inclusion verdict: the two-state model behind it is rejected on a",
"substantial share of edge chains, and the precision of the inclusion",
"probability and its Bayes factor is carried by the Rao-Blackwellized",
"effective sample size and Monte Carlo standard error. Use the default",
"estimator = \"rb\"; the directional flip counts remain in",
"summary(fit)$indicator."
"The transition-based effective sample size is no longer available.",
"Use extract_ess(fit) to obtain the effective sample size of the",
"Rao-Blackwellized inclusion draws."
)
)
}
Expand All @@ -1608,8 +1543,7 @@ extract_ess = function(bgms_object, estimator = c("rb", "mixt")) {
#' @inheritParams extract_ess
#' @exportS3Method
#' @noRd
extract_ess.bgms = function(bgms_object, estimator = c("rb", "mixt")) {
estimator_missing = missing(estimator)
extract_ess.bgms = function(bgms_object, estimator = "rb") {
ensure_summaries(bgms_object)
result = list()

Expand All @@ -1633,10 +1567,7 @@ extract_ess.bgms = function(bgms_object, estimator = c("rb", "mixt")) {

# Indicator ESS (if edge selection was used)
if(!is.null(bgms_object$posterior_summary_indicator)) {
result$indicator = indicator_ess_column(
bgms_object, bgms_object$posterior_summary_indicator,
estimator, estimator_missing
)
result$indicator = indicator_ess_column(bgms_object$posterior_summary_indicator)
names(result$indicator) = rownames(bgms_object$posterior_summary_indicator)
}

Expand All @@ -1650,8 +1581,7 @@ extract_ess.bgms = function(bgms_object, estimator = c("rb", "mixt")) {
#' @inheritParams extract_ess
#' @exportS3Method
#' @noRd
extract_ess.bgmCompare = function(bgms_object, estimator = c("rb", "mixt")) {
estimator_missing = missing(estimator)
extract_ess.bgmCompare = function(bgms_object, estimator = "rb") {
ensure_summaries(bgms_object)
result = list()

Expand Down Expand Up @@ -1681,10 +1611,7 @@ extract_ess.bgmCompare = function(bgms_object, estimator = c("rb", "mixt")) {

# Indicator ESS (if difference selection was used)
if(!is.null(bgms_object$posterior_summary_indicator)) {
result$indicator = indicator_ess_column(
bgms_object, bgms_object$posterior_summary_indicator,
estimator, estimator_missing
)
result$indicator = indicator_ess_column(bgms_object$posterior_summary_indicator)
names(result$indicator) = rownames(bgms_object$posterior_summary_indicator)
}

Expand Down
42 changes: 12 additions & 30 deletions R/mcmc_summary.R
Original file line number Diff line number Diff line change
Expand Up @@ -233,12 +233,11 @@ summarize_indicator = function(fit, component = c("indicator_samples"), param_na
if(is.null(array3d)) array3d = combine_chains(fit, component)
nparam = dim(array3d)[3]

# Batch indicator ESS + transition counts via C++
# Batch indicator mean and MCSE via C++
ind_stats = .compute_indicator_ess_cpp(array3d)
batch_rhat = .compute_rhat_cpp(split_chains(array3d))

result = cbind(ind_stats[, c("mean", "mcse", "sd", "n00", "n01", "n10", "n11", "n_eff_mixt"), drop = FALSE], Rhat = batch_rhat)
colnames(result)[4:7] = c("n0->0", "n0->1", "n1->0", "n1->1")
result = cbind(ind_stats[, c("mean", "mcse", "sd"), drop = FALSE], Rhat = batch_rhat)

if(is.null(param_names)) {
data.frame(parameter = paste0("indicator [", seq_len(nparam), "]"), result, check.names = FALSE)
Expand Down Expand Up @@ -277,21 +276,10 @@ summarize_rb_inclusion = function(raw, param_names, keep_parameter_col = FALSE)
mat[keep, ] = as.matrix(sub[, cols, drop = FALSE])
}

ind_stats = .compute_indicator_ess_cpp(combine_chains(raw, "indicator_samples"))

full = cbind(
mat[, c("mean", "mcse", "sd", "n_eff", "Rhat"), drop = FALSE],
ind_stats[, c("n01", "n10"), drop = FALSE]
)
# Keep the directional transition counts whole; their asymmetry is
# decision-relevant and no symmetric summary recovers it.
colnames(full)[colnames(full) == "n01"] = "n0->1"
colnames(full)[colnames(full) == "n10"] = "n1->0"

if(keep_parameter_col) {
data.frame(parameter = param_names, full, check.names = FALSE, row.names = NULL)
data.frame(parameter = param_names, mat, check.names = FALSE, row.names = NULL)
} else {
out = as.data.frame(full, check.names = FALSE)
out = as.data.frame(mat, check.names = FALSE)
rownames(out) = param_names
out
}
Expand Down Expand Up @@ -345,9 +333,7 @@ summarize_slab = function(fit, component = c("pairwise_samples"), param_names =
# inclusion-dominated cells). The composite MCSE^2 splits into an inclusion part
# (mu_cond^2 * var_p, with var_p the RB J-chain MCSE^2 of the inclusion
# probability) and a slab part (p_hat^2 * var_mu, from the included-only draws).
# share_incl is the inclusion part's share of the composite MCSE^2 -- the
# bottleneck: whether the Monte Carlo error is dominated by inclusion or slab
# uncertainty. Inputs may be vectors (one entry per edge).
# Inputs may be vectors (one entry per edge).
derived_weight_ess = function(post_var, p_hat, var_p, mu_cond, var_mu) {
# A constant / never-updated inclusion chain contributes no inclusion error.
var_p[!is.finite(var_p)] = 0
Expand All @@ -357,8 +343,7 @@ derived_weight_ess = function(post_var, p_hat, var_p, mu_cond, var_mu) {
ok = is.finite(mcse2) & mcse2 > 0
list(
mcse = ifelse(ok, sqrt(mcse2), NA_real_),
n_eff = ifelse(ok & is.finite(post_var), post_var / mcse2, NA_real_),
share_incl = ifelse(ok, part_incl / mcse2, NA_real_)
n_eff = ifelse(ok & is.finite(post_var), post_var / mcse2, NA_real_)
)
}

Expand Down Expand Up @@ -413,7 +398,7 @@ summarize_pair = function(fit,
data.frame(
parameter = names_out,
mean = eap, mcse = comp$mcse, sd = sqrt(post_var),
n_eff = comp$n_eff, share_incl = comp$share_incl, Rhat = rhat,
n_eff = comp$n_eff, Rhat = rhat,
check.names = FALSE
)
}
Expand Down Expand Up @@ -495,12 +480,11 @@ summarize_indicator_compare = function(fit, component = "indicator_samples", par
array3d = combine_chains(fit, component)
nparam = dim(array3d)[3]

# Batch indicator ESS + transition counts via C++
# Batch indicator mean and MCSE via C++
ind_stats = .compute_indicator_ess_cpp(array3d)
batch_rhat = .compute_rhat_cpp(split_chains(array3d))

result = cbind(ind_stats[, c("mean", "mcse", "sd", "n00", "n01", "n10", "n11", "n_eff_mixt"), drop = FALSE], Rhat = batch_rhat)
colnames(result)[4:7] = c("n0->0", "n0->1", "n1->0", "n1->1")
result = cbind(ind_stats[, c("mean", "mcse", "sd"), drop = FALSE], Rhat = batch_rhat)

if(is.null(param_names)) {
data.frame(parameter = paste0("indicator [", seq_len(nparam), "]"), result, check.names = FALSE)
Expand All @@ -511,10 +495,9 @@ summarize_indicator_compare = function(fit, component = "indicator_samples", par


# Summarize one effect with spike-and-slab draws. n_eff is the derived composite
# ESS for the model-averaged weight (see derived_weight_ess); share_incl is the
# inclusion part's share of the composite MCSE^2. The inclusion Monte Carlo error
# comes from the RB J-chain (draws_rb) when available, else from the binary
# indicator's transition-based MCSE.
# ESS for the model-averaged weight (see derived_weight_ess). The inclusion
# Monte Carlo error comes from the RB J-chain (draws_rb) when available, else
# from the binary indicator's transition-based MCSE.
summarize_mixture_effect = function(draws_pw, draws_id, name, draws_rb = NULL) {
# Handle case where single-chain extraction returns a vector
# (dimension gets dropped when extracting [, , idx] from array with nchains=1)
Expand Down Expand Up @@ -573,7 +556,6 @@ summarize_mixture_effect = function(draws_pw, draws_id, name, draws_rb = NULL) {
mcse = comp$mcse,
sd = sqrt(post_var),
n_eff = comp$n_eff,
share_incl = comp$share_incl,
Rhat = rhat,
check.names = FALSE
)
Expand Down
3 changes: 1 addition & 2 deletions R/mcmc_summary_sbm.R
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,9 @@ summarize_alloc_pairs = function(allocations, node_names = NULL) {
batch_rhat = .compute_rhat_cpp(split_chains(array3d))

result = cbind(
ind_stats[, c("mean", "mcse", "sd", "n00", "n01", "n10", "n11", "n_eff_mixt"), drop = FALSE],
ind_stats[, c("mean", "mcse", "sd"), drop = FALSE],
Rhat = batch_rhat
)
colnames(result)[4:7] = c("n0->0", "n0->1", "n1->0", "n1->1")
if(is.null(node_names)) {
rn = paste0(Pairs[, 1], "-", Pairs[, 2])
dimn = as.character(seq_len(no_variables))
Expand Down
Loading
Loading