diff --git a/NEWS.md b/NEWS.md index 60c24801..8acde2e2 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,6 +5,11 @@ released from this line yet. ## Breaking changes +* The middle evidence verdict is now `inconclusive` throughout plots, printed + summaries, and returned verdicts. Code comparing verdict values or factor + levels with `"undecided"` should use `"inconclusive"` instead. Evidence + thresholds and classifications are unchanged. + * bgms requires R (>= 4.0). The package uses `tools::R_user_dir()` and builds with C++20, both of which arrived in R 4.0; the declared floor was 3.5. diff --git a/R/centrality.R b/R/centrality.R index 2b47acb6..5eb13e6a 100644 --- a/R/centrality.R +++ b/R/centrality.R @@ -36,7 +36,7 @@ #' edge excluded at a given iteration contributes exactly zero. Structural #' uncertainty therefore propagates into the centrality without any extra step: #' a node whose edges are themselves uncertain gets a wide centrality -#' posterior, which is the honest summary. Conditioning on the included-only +#' posterior. Conditioning on the included-only #' draws instead would report each node's centrality in the models where its #' edges happen to be present, which is a different and generally larger #' quantity. diff --git a/R/extractor_functions.R b/R/extractor_functions.R index ac21fc7d..8bef83d9 100644 --- a/R/extractor_functions.R +++ b/R/extractor_functions.R @@ -442,8 +442,7 @@ rb_bf_scale = function(log_bf, log) { #' inclusion odds and it gets a finite (possibly very large) Bayes factor. An #' unselected main-effect difference in [bgmCompare()] #' (`main_difference_selection = FALSE`) is never proposed at all, so no -#' Rao-Blackwellized quantity exists for it and `NA` is the honest entry -#' rather than a lost number. +#' Rao-Blackwellized quantity exists for it, so the returned value is `NA`. #' #' @examples #' \donttest{ diff --git a/R/plot_bgms.R b/R/plot_bgms.R index 14145f02..7db6b68d 100644 --- a/R/plot_bgms.R +++ b/R/plot_bgms.R @@ -33,7 +33,7 @@ network_unit = function(kind = c("edge", "difference")) { panels = c( presence = "evidence of presence", absence = "evidence of absence", - undecided = "undecided" + inconclusive = "inconclusive" ) )) } @@ -43,7 +43,7 @@ network_unit = function(kind = c("edge", "difference")) { panels = c( presence = "difference supported", absence = "difference ruled out", - undecided = "undecided" + inconclusive = "inconclusive" ) ) } @@ -69,7 +69,7 @@ threshold_rules = function(evidence_threshold) { c( presence = sprintf("BF > %s", high), absence = sprintf("BF < %s", low), - undecided = sprintf("%s < BF < %s", low, high) + inconclusive = sprintf("%s < BF < %s", low, high) ) } @@ -79,12 +79,9 @@ threshold_rules = function(evidence_threshold) { # ------------------------------------------------------------------ # The square matrix qgraph is given for one evidence panel. # -# A weighted edgelist would be the direct expression of "draw these edges", but -# qgraph derives the node set from the edgelist and its nNodes argument does not -# reliably override that, so a network that leaves a node out fails rather than -# drawing the node alone. A square matrix states the node set in its dimensions, -# and an empty panel is a matrix of zeros, which draws the nodes on their own -- -# which is what an all-decided fit's undecided panel should look like. +# qgraph can omit isolated nodes when given an edgelist, even with nNodes set. +# A square adjacency matrix preserves all nodes. If no edges belong to a panel, +# the matrix contains only zeros and qgraph draws the nodes without edges. # # @param value Value per selected pair (a weight, or 1 for a panel # drawn at uniform width). @@ -305,10 +302,9 @@ draw_network_panel = function(m, variables, shared, title, rule = NULL, # to say. Because there is an inclusion Bayes factor for every pair, the choice # does not have to be made: the two kinds of blank get a panel each. # -# Only the supported panel is weighted. There, line width is the posterior mean -# association and colour its sign, because that is where the effect sizes live. -# The other two are drawn at uniform width, dashed and dotted, because for those -# pairs the classification is the result and a weight would suggest otherwise. +# In the supported panel, line width represents the posterior mean association +# and colour indicates its sign. The absence and inconclusive panels use uniform +# line widths, with dashed and dotted lines respectively. # # The supported panel goes unweighted too when a pair has no single magnitude to # draw -- a bgmCompare fit on more than two groups, where one indicator per pair @@ -348,7 +344,7 @@ draw_evidence_panels = function(weight, verdict, pairs, variables, on.exit(graphics::par(old_par), add = TRUE) graphics::par(mfrow = c(1L, 3L)) - classes = c("presence", "absence", "undecided") + classes = c("presence", "absence", "inconclusive") for(class in classes) { keep = !is.na(verdict) & verdict == class carries_weight = weighted && class == "presence" @@ -365,15 +361,15 @@ draw_evidence_panels = function(weight, verdict, pairs, variables, # Unweighted, the supported panel has no sign to colour by and takes # the plain ink; the classification is the whole of what it says. presence = if(carries_weight) matrix_edge_colors(m) else style$ink, - # A ruled-out pair is a finding and takes the darker ink; an undecided + # A ruled-out pair is a finding and takes the darker ink; an inconclusive # one is not, and recedes. absence = grDevices::adjustcolor(style$ink, 0.8), - undecided = style$muted + inconclusive = style$muted ), lty = switch(class, presence = 1L, absence = 2L, - undecided = 3L + inconclusive = 3L ), edge.width = if(carries_weight) NULL else 1.6, ... @@ -469,7 +465,7 @@ draw_weight_network = function(weight, pairs, variables, unit, #' edge evidence plot; `"centrality"` is the posterior strength centrality of #' [extract_centrality()]. #' @param evidence_threshold Numeric > 1; the inclusion Bayes factor separating -#' evidence of presence from undecided, as in [verdicts()]. Default `10`. +#' evidence of presence from inconclusive, as in [verdicts()]. Default `10`. #' @param layout Layout passed to [qgraph::qgraph()]. Default `"spring"`. #' @param ... Passed to [qgraph::qgraph()] for `type = "network"`, and to #' [plot.bgms_centrality()] otherwise. @@ -491,11 +487,9 @@ draw_weight_network = function(weight, pairs, variables, unit, #' Only the first panel is weighted. There, line width is the posterior mean #' pairwise association and colour carries its sign -- blue for a positive #' association, vermillion for a negative one, the Okabe-Ito pair, so the sign -#' survives common forms of colour-vision deficiency -- because that is where -#' the effect sizes are. The other two panels are drawn at uniform width, dashed -#' for evidence of absence and dotted for undecided: for those pairs the -#' classification is the result, and a width would suggest an effect size that -#' the data have either ruled out or not established. +#' survives common forms of colour-vision deficiency. The other two panels use +#' uniform line widths: dashed for evidence of absence and dotted for +#' inconclusive evidence. #' #' The figure carries no key. Each panel is titled with the evidence class it #' holds and the rule that defines it, which is what a key would otherwise @@ -517,9 +511,8 @@ draw_weight_network = function(weight, pairs, variables, unit, #' The single-panel display (no edge selection) is content with the default #' device. #' -#' A fit with no edge left in a panel is a result, not a failure. An all-absence -#' fit fills the second panel and leaves the first empty, which is the honest -#' picture of it. +#' A panel with no edges still displays all nodes. If every edge has evidence +#' of absence, all edges appear in the second panel. #' #' \strong{Without edge selection} there is no indicator and so no inclusion #' Bayes factor, and nothing to split the pairs by: the analysis is an @@ -690,7 +683,7 @@ main_difference_nodes = function(verdict, pip, main_selected) { #' one shared layout; `"centrality"` is the posterior strength centrality of #' [extract_centrality()]. #' @param evidence_threshold Numeric > 1; the inclusion Bayes factor separating -#' evidence of a difference from undecided, as in [verdicts()]. Default `10`. +#' evidence of a difference from inconclusive, as in [verdicts()]. Default `10`. #' @param group For `type = "centrality"`: a single group index, passed to #' [extract_centrality()] for that group's centrality. A difference in #' centrality (two indices) can be extracted and summarized but has no plot; @@ -722,9 +715,8 @@ main_difference_nodes = function(verdict, pip, main_selected) { #' for a negative one, the Okabe-Ito pair, so the sign survives common forms of #' colour-vision deficiency. Which group a positive difference favours follows #' the contrast coding, which [extract_group_params()] reports per group. The -#' other two are drawn at uniform width, dashed for a difference the data rule -#' out and dotted for undecided, because for those pairs the classification is -#' the result. +#' other two panels use uniform line widths: dashed for evidence of no difference +#' and dotted for inconclusive evidence. #' #' The figure carries no key: the panel titles name the evidence class and the #' rule that defines it, and the sign convention is documented here. @@ -755,11 +747,8 @@ main_difference_nodes = function(verdict, pip, main_selected) { #' where they are per group: `plot(fit, type = "groups")` for the picture, #' [extract_group_params()] for the numbers. #' -#' The panels need the split to exist, and more than two groups \emph{without} -#' `difference_selection` is the one case where it does not. Selection off -#' means weights are the display -- as it does for a [bgm()] fit -- and beyond -#' two groups the weights of a pair are `K - 1` numbers rather than one, whose -#' honest weighted picture is the groups themselves. `plot()` therefore draws +#' With more than two groups and `difference_selection = FALSE`, each pair has +#' `K - 1` differences and no selection indicator. `plot()` therefore draws #' the `type = "groups"` panels in that case, with the same layout, the same #' `max_panels` paging and the same passthrough to [qgraph::qgraph()]. #' [extract_group_params()] remains the way to read the differences as numbers. @@ -769,7 +758,7 @@ main_difference_nodes = function(verdict, pip, main_selected) { #' evidence is carried on the nodes: each node wears a ring filled to its #' difference indicator's posterior inclusion probability -- a full ring is #' probability 1, half a ring 0.5 -- coloured by the verdict (accented for -#' presence, grey for undecided, faint for absence). The fill fraction carries +#' presence, grey for inconclusive, faint for absence). The fill fraction carries #' the number, so the encoding does not rest on colour alone. Under the default #' `main_difference_selection = FALSE` those indicators do not exist and no ring #' is drawn. `verdicts()` remains the place to read main-effect differences diff --git a/R/prior_sensitivity.R b/R/prior_sensitivity.R index 6e413c58..c8df506e 100644 --- a/R/prior_sensitivity.R +++ b/R/prior_sensitivity.R @@ -18,10 +18,10 @@ # @param bf Numeric inclusion Bayes factor(s). # @param threshold Upper evidence threshold; lower is 1 / threshold. # -# Returns: character vector of "presence" / "absence" / "undecided". +# Returns: character vector of "presence" / "absence" / "inconclusive". # ------------------------------------------------------------------ verdict_from_bf = function(bf, threshold) { - out = rep("undecided", length(bf)) + out = rep("inconclusive", length(bf)) out[bf >= threshold] = "presence" out[bf <= 1 / threshold] = "absence" out[is.na(bf)] = NA_character_ @@ -741,11 +741,11 @@ print.bgms_prior_sensitivity = function(x, max_rows = 10L, ...) { vt = apply(x$verdict_by_scale, 1, function(v) { c( presence = sum(v == "presence", na.rm = TRUE), - undecided = sum(v == "undecided", na.rm = TRUE), + inconclusive = sum(v == "inconclusive", na.rm = TRUE), absence = sum(v == "absence", na.rm = TRUE) ) }) - vt = matrix(vt, nrow = 3L, dimnames = list(c("presence", "undecided", "absence"), mlab)) + vt = matrix(vt, nrow = 3L, dimnames = list(c("presence", "inconclusive", "absence"), mlab)) out = utils::capture.output(print(vt)) cat(paste0(" ", out, collapse = "\n"), "\n", sep = "") cat("\n") diff --git a/R/refit_engine.R b/R/refit_engine.R index aca9dc8b..a3dec0ee 100644 --- a/R/refit_engine.R +++ b/R/refit_engine.R @@ -243,7 +243,7 @@ data_preferred_scale = function(fit) { # lthr = log(t). # ------------------------------------------------------------------ verdict_from_lbf = function(lbf, lthr) { - out = rep("undecided", length(lbf)) + out = rep("inconclusive", length(lbf)) out[lbf >= lthr] = "presence" out[lbf <= -lthr] = "absence" out[is.na(lbf)] = NA_character_ diff --git a/R/verdicts.R b/R/verdicts.R index 1a8e3df9..abd07dab 100644 --- a/R/verdicts.R +++ b/R/verdicts.R @@ -2,7 +2,7 @@ # Edge verdicts and the Monte Carlo fragility flag # ============================================================================== # -# The three-way reading of an inclusion Bayes factor (presence / undecided / +# The three-way reading of an inclusion Bayes factor (presence / inconclusive / # absence at a threshold t and its reciprocal) plus the flag that says whether # the reading would survive a rerun. Both standard errors behind the flag are # on the log inclusion Bayes factor scale, which equals the logit inclusion @@ -223,7 +223,7 @@ build_verdicts = function(parameter, log_bf, pip, mcse, draws, evidence_threshol log_bf = log_bf, verdict = factor( verdict_from_lbf(log_bf, lthr), - levels = c("presence", "undecided", "absence") + levels = c("presence", "inconclusive", "absence") ), se_two_state = se_two_state, se_rb = se_rb, @@ -246,7 +246,7 @@ build_verdicts = function(parameter, log_bf, pip, mcse, draws, evidence_threshol #' #' @description #' Reads each edge (or difference) indicator's inclusion Bayes factor as a -#' three-way verdict -- evidence of presence, undecided, evidence of absence -- +#' three-way verdict -- evidence of presence, inconclusive, evidence of absence -- #' and flags the verdicts that a rerun of the sampler could change. #' #' @param bgms_object A fitted model object of class `bgms` (from [bgm()] with @@ -266,7 +266,7 @@ build_verdicts = function(parameter, log_bf, pip, mcse, draws, evidence_threshol #' from [extract_inclusion_bf()], which returns the same natural-log #' scale under `log = TRUE`. `log_bf` stays finite where `bf` saturates #' at `0` or `Inf`.} -#' \item{verdict}{Factor with levels `presence`, `undecided`, `absence`, +#' \item{verdict}{Factor with levels `presence`, `inconclusive`, `absence`, #' and `NA` for indicators that were never updated (main-effect #' differences under `main_difference_selection = FALSE`).} #' \item{se_two_state, se_rb}{Standard errors of the logit inclusion @@ -492,8 +492,8 @@ print.bgms_verdicts = function(x, digits = 3, max_rows = 10L, ...) { tally = table(rows$verdict) cat(sprintf( - " presence %d | undecided %d | absence %d (%d %s)\n", - tally[["presence"]], tally[["undecided"]], tally[["absence"]], nrow(rows), + " presence %d | inconclusive %d | absence %d (%d %s)\n", + tally[["presence"]], tally[["inconclusive"]], tally[["absence"]], nrow(rows), if(nrow(rows) == 1L) "indicator" else "indicators" )) if(!is.null(hidden) && any(hidden)) { diff --git a/man/extract_centrality.Rd b/man/extract_centrality.Rd index 5124a317..53646f3c 100644 --- a/man/extract_centrality.Rd +++ b/man/extract_centrality.Rd @@ -36,7 +36,7 @@ The centrality is evaluated on the model-averaged pairwise draws, in which an edge excluded at a given iteration contributes exactly zero. Structural uncertainty therefore propagates into the centrality without any extra step: a node whose edges are themselves uncertain gets a wide centrality -posterior, which is the honest summary. Conditioning on the included-only +posterior. Conditioning on the included-only draws instead would report each node's centrality in the models where its edges happen to be present, which is a different and generally larger quantity. diff --git a/man/extract_inclusion_bf.Rd b/man/extract_inclusion_bf.Rd index fb916573..cf4ff7b2 100644 --- a/man/extract_inclusion_bf.Rd +++ b/man/extract_inclusion_bf.Rd @@ -29,8 +29,7 @@ proposed at every iteration, so the accumulators see its conditional inclusion odds and it gets a finite (possibly very large) Bayes factor. An unselected main-effect difference in \code{\link[=bgmCompare]{bgmCompare()}} (\code{main_difference_selection = FALSE}) is never proposed at all, so no -Rao-Blackwellized quantity exists for it and \code{NA} is the honest entry -rather than a lost number. +Rao-Blackwellized quantity exists for it, so the returned value is \code{NA}. } \description{ Computes inclusion Bayes factors from a model fitted with \code{\link[=bgm]{bgm()}} (edge diff --git a/man/plot.bgmCompare.Rd b/man/plot.bgmCompare.Rd index aa97184c..c4b9843c 100644 --- a/man/plot.bgmCompare.Rd +++ b/man/plot.bgmCompare.Rd @@ -24,7 +24,7 @@ one shared layout; \code{"centrality"} is the posterior strength centrality of \code{\link[=extract_centrality]{extract_centrality()}}.} \item{evidence_threshold}{Numeric > 1; the inclusion Bayes factor separating -evidence of a difference from undecided, as in \code{\link[=verdicts]{verdicts()}}. Default \code{10}.} +evidence of a difference from inconclusive, as in \code{\link[=verdicts]{verdicts()}}. Default \code{10}.} \item{group}{For \code{type = "centrality"}: a single group index, passed to \code{\link[=extract_centrality]{extract_centrality()}} for that group's centrality. A difference in @@ -66,9 +66,8 @@ and colour carries its sign -- blue for a positive difference, vermillion for a negative one, the Okabe-Ito pair, so the sign survives common forms of colour-vision deficiency. Which group a positive difference favours follows the contrast coding, which \code{\link[=extract_group_params]{extract_group_params()}} reports per group. The -other two are drawn at uniform width, dashed for a difference the data rule -out and dotted for undecided, because for those pairs the classification is -the result. +other two panels use uniform line widths: dashed for evidence of no difference +and dotted for inconclusive evidence. The figure carries no key: the panel titles name the evidence class and the rule that defines it, and the sign convention is documented here. @@ -99,11 +98,8 @@ classification is the whole of what the panel reports. Read the magnitudes where they are per group: \code{plot(fit, type = "groups")} for the picture, \code{\link[=extract_group_params]{extract_group_params()}} for the numbers. -The panels need the split to exist, and more than two groups \emph{without} -\code{difference_selection} is the one case where it does not. Selection off -means weights are the display -- as it does for a \code{\link[=bgm]{bgm()}} fit -- and beyond -two groups the weights of a pair are \code{K - 1} numbers rather than one, whose -honest weighted picture is the groups themselves. \code{plot()} therefore draws +With more than two groups and \code{difference_selection = FALSE}, each pair has +\code{K - 1} differences and no selection indicator. \code{plot()} therefore draws the \code{type = "groups"} panels in that case, with the same layout, the same \code{max_panels} paging and the same passthrough to \code{\link[qgraph:qgraph]{qgraph::qgraph()}}. \code{\link[=extract_group_params]{extract_group_params()}} remains the way to read the differences as numbers. @@ -113,7 +109,7 @@ the \code{type = "groups"} panels in that case, with the same layout, the same evidence is carried on the nodes: each node wears a ring filled to its difference indicator's posterior inclusion probability -- a full ring is probability 1, half a ring 0.5 -- coloured by the verdict (accented for -presence, grey for undecided, faint for absence). The fill fraction carries +presence, grey for inconclusive, faint for absence). The fill fraction carries the number, so the encoding does not rest on colour alone. Under the default \code{main_difference_selection = FALSE} those indicators do not exist and no ring is drawn. \code{verdicts()} remains the place to read main-effect differences diff --git a/man/plot.bgms.Rd b/man/plot.bgms.Rd index 95560063..c58f4772 100644 --- a/man/plot.bgms.Rd +++ b/man/plot.bgms.Rd @@ -20,7 +20,7 @@ edge evidence plot; \code{"centrality"} is the posterior strength centrality of \code{\link[=extract_centrality]{extract_centrality()}}.} \item{evidence_threshold}{Numeric > 1; the inclusion Bayes factor separating -evidence of presence from undecided, as in \code{\link[=verdicts]{verdicts()}}. Default \code{10}.} +evidence of presence from inconclusive, as in \code{\link[=verdicts]{verdicts()}}. Default \code{10}.} \item{layout}{Layout passed to \code{\link[qgraph:qgraph]{qgraph::qgraph()}}. Default \code{"spring"}.} @@ -49,11 +49,9 @@ its logarithm. The classification is the one \code{\link[=verdicts]{verdicts()}} Only the first panel is weighted. There, line width is the posterior mean pairwise association and colour carries its sign -- blue for a positive association, vermillion for a negative one, the Okabe-Ito pair, so the sign -survives common forms of colour-vision deficiency -- because that is where -the effect sizes are. The other two panels are drawn at uniform width, dashed -for evidence of absence and dotted for undecided: for those pairs the -classification is the result, and a width would suggest an effect size that -the data have either ruled out or not established. +survives common forms of colour-vision deficiency. The other two panels use +uniform line widths: dashed for evidence of absence and dotted for +inconclusive evidence. The figure carries no key. Each panel is titled with the evidence class it holds and the rule that defines it, which is what a key would otherwise @@ -75,9 +73,8 @@ plot(fit) The single-panel display (no edge selection) is content with the default device. -A fit with no edge left in a panel is a result, not a failure. An all-absence -fit fills the second panel and leaves the first empty, which is the honest -picture of it. +A panel with no edges still displays all nodes. If every edge has evidence +of absence, all edges appear in the second panel. \strong{Without edge selection} there is no indicator and so no inclusion Bayes factor, and nothing to split the pairs by: the analysis is an diff --git a/man/verdicts.Rd b/man/verdicts.Rd index 441cf510..61b81e6e 100644 --- a/man/verdicts.Rd +++ b/man/verdicts.Rd @@ -27,7 +27,7 @@ order of the fit's raw indicator draws, with columns: from \code{\link[=extract_inclusion_bf]{extract_inclusion_bf()}}, which returns the same natural-log scale under \code{log = TRUE}. \code{log_bf} stays finite where \code{bf} saturates at \code{0} or \code{Inf}.} -\item{verdict}{Factor with levels \code{presence}, \code{undecided}, \code{absence}, +\item{verdict}{Factor with levels \code{presence}, \code{inconclusive}, \code{absence}, and \code{NA} for indicators that were never updated (main-effect differences under \code{main_difference_selection = FALSE}).} \item{se_two_state, se_rb}{Standard errors of the logit inclusion @@ -49,7 +49,7 @@ its counts because no indicator exists for them. } \description{ Reads each edge (or difference) indicator's inclusion Bayes factor as a -three-way verdict -- evidence of presence, undecided, evidence of absence -- +three-way verdict -- evidence of presence, inconclusive, evidence of absence -- and flags the verdicts that a rerun of the sampler could change. } \details{ diff --git a/tests/testthat/_snaps/plot-methods.md b/tests/testthat/_snaps/plot-methods.md index 6f31d2c7..a4072f57 100644 --- a/tests/testthat/_snaps/plot-methods.md +++ b/tests/testthat/_snaps/plot-methods.md @@ -14,7 +14,7 @@ dots : none window : 0.00 to 0.48 -# the panel of an undecided edge splits its wheel +# the edge panel shows the inclusion probability without a verdict label Code describe_panel(panel) diff --git a/tests/testthat/_snaps/verdicts.md b/tests/testthat/_snaps/verdicts.md index 63599099..6d68b159 100644 --- a/tests/testthat/_snaps/verdicts.md +++ b/tests/testthat/_snaps/verdicts.md @@ -6,13 +6,13 @@ Edge verdicts at an inclusion Bayes factor of 10 (and 0.1 for absence): presence: log BF > 2.30; absence: log BF < -2.30 - presence 1 | undecided 2 | absence 0 (3 indicators) + presence 1 | inconclusive 2 | absence 0 (3 indicators) Main-effect differences are not under selection (main_difference_selection = FALSE). - parameter pip log_bf verdict fragile - A-B (pairwise) 0.95 2.94 presence FALSE - A-C (pairwise) 0.10 -2.20 undecided TRUE - B-C (pairwise) 0.52 0.08 undecided FALSE + parameter pip log_bf verdict fragile + A-B (pairwise) 0.95 2.94 presence FALSE + A-C (pairwise) 0.10 -2.20 inconclusive TRUE + B-C (pairwise) 0.52 0.08 inconclusive FALSE 2 verdicts appear robust to Monte Carlo error. 1 verdict could change on a rerun: its estimated log Bayes factor lies within two standard errors of an @@ -36,15 +36,15 @@ Edge verdicts at an inclusion Bayes factor of 10 (and 0.1 for absence): presence: log BF > 2.30; absence: log BF < -2.30 - presence 1 | undecided 4 | absence 1 (6 indicators) + presence 1 | inconclusive 4 | absence 1 (6 indicators) - parameter pip log_bf verdict fragile - A (main) 0.05 -2.94 absence FALSE - A-B (pairwise) 0.95 2.94 presence FALSE - A-C (pairwise) 0.10 -2.20 undecided TRUE - B (main) 0.90 2.20 undecided FALSE - B-C (pairwise) 0.52 0.08 undecided FALSE - C (main) 0.50 0.00 undecided FALSE + parameter pip log_bf verdict fragile + A (main) 0.05 -2.94 absence FALSE + A-B (pairwise) 0.95 2.94 presence FALSE + A-C (pairwise) 0.10 -2.20 inconclusive TRUE + B (main) 0.90 2.20 inconclusive FALSE + B-C (pairwise) 0.52 0.08 inconclusive FALSE + C (main) 0.50 0.00 inconclusive FALSE 5 verdicts appear robust to Monte Carlo error. 1 verdict could change on a rerun: its estimated log Bayes factor lies within two standard errors of an diff --git a/tests/testthat/test-plot-methods.R b/tests/testthat/test-plot-methods.R index 50cb5a7e..c1d59cb3 100644 --- a/tests/testthat/test-plot-methods.R +++ b/tests/testthat/test-plot-methods.R @@ -64,7 +64,7 @@ test_that("a network with nothing left to support is still a figure", { test_that("main_difference_nodes fills each node's ring to its inclusion probability", { style = bgms_style() - verdict = c("presence", "undecided", "absence") + verdict = c("presence", "inconclusive", "absence") pip = c(0.97, 0.5, 0.02) nodes = main_difference_nodes(verdict, pip, main_selected = TRUE) @@ -159,8 +159,7 @@ test_that("a panel matrix states its node set and reads its colours in order", { palette = mover_palette() expect_equal(matrix_edge_colors(m), c(palette[1], palette[2], palette[1])) - # An empty panel is a matrix of zeros, and qgraph draws the nodes alone -- - # which is what an all-decided fit's undecided panel has to look like. + # With no selected edges, the matrix retains all nodes and contains only zeros. empty = panel_edge_matrix(weight, rep(FALSE, 10L), pairs, V) expect_true(all(empty == 0)) expect_length(matrix_edge_colors(empty), 0L) @@ -181,7 +180,7 @@ test_that("the threshold rules read in Bayes factors, not their logarithms", { rules = threshold_rules(10) expect_equal(unname(rules[["presence"]]), "BF > 10") expect_equal(unname(rules[["absence"]]), "BF < 0.1") - expect_equal(unname(rules[["undecided"]]), "0.1 < BF < 10") + expect_equal(unname(rules[["inconclusive"]]), "0.1 < BF < 10") # A threshold a user chose is printed as they chose it. expect_equal(unname(threshold_rules(100)[["presence"]]), "BF > 100") @@ -195,7 +194,7 @@ test_that("both network methods split their pairs with the same wording rule", { # The two displays are one routine; only the nouns differ, and both name the # same three classes in the same order. expect_equal(names(edge$panels), names(difference$panels)) - expect_equal(names(edge$panels), c("presence", "absence", "undecided")) + expect_equal(names(edge$panels), c("presence", "absence", "inconclusive")) expect_equal(unname(edge$panels[["presence"]]), "evidence of presence") expect_equal(unname(difference$panels[["presence"]]), "difference supported") expect_equal(edge$weights_label, "Edge weights") @@ -410,16 +409,15 @@ test_that("the panel of a decisive edge carries the wheel, not a stem", { expect_snapshot(describe_panel(panel)) }) -test_that("the panel of an undecided edge splits its wheel", { +test_that("the edge panel shows the inclusion probability without a verdict label", { set.seed(102) draws = c(rnorm(1200, 0.09, 0.03), rep(0, 800)) panel = edge_panel_selection( "intrusion-upset", draws, test_slab_prior(), pip = 0.6, log_bf = 0.41 ) - # No verdict word is printed, here least of all: the split wheel and the log - # Bayes factor near zero are the statement, and "undecided" would have added - # a threshold the reader did not choose. + # Show the inclusion probability and log Bayes factor without applying an + # evidence threshold. expect_null(panel$subtitle) expect_snapshot(describe_panel(panel)) }) diff --git a/tests/testthat/test-prior-sensitivity.R b/tests/testthat/test-prior-sensitivity.R index e63e858d..c76f3dc7 100644 --- a/tests/testthat/test-prior-sensitivity.R +++ b/tests/testthat/test-prior-sensitivity.R @@ -61,14 +61,14 @@ fake_sensitivity = function(cls, multipliers, rhat_max = rep(1, length(multiplie test_that("the classification compares each verdict change with the two fits' Monte Carlo error", { lthr = log(10) multipliers = c(0.5, 1, 2) - # Five edges at the chosen scale: presence, undecided, undecided, absence, + # Five edges at the chosen scale: presence, inconclusive, inconclusive, absence, # presence. s0 = fake_stats(c(3.0, 1.0, 2.0, -3.0, 2.6), mcse = c(0.2, 0.1, 0.2, 0.2, 0.3)) # 0.5x: edge 2 becomes presence with a change of 1.5 against an error of # 2 * sqrt(0.1^2 + 0.1^2) = 0.28 (beyond); edge 5 stays presence. s_lo = fake_stats(c(3.2, 2.5, 2.1, -2.9, 2.8), mcse = c(0.2, 0.1, 0.2, 0.2, 0.3)) # 2x: edge 3 becomes presence by a change of 0.35 against an error of - # 2 * sqrt(0.2^2 + 0.2^2) = 0.57 (within); edge 5 becomes undecided by a + # 2 * sqrt(0.2^2 + 0.2^2) = 0.57 (within); edge 5 becomes inconclusive by a # change of 0.4 against 2 * sqrt(0.3^2 + 0.3^2) = 0.85 (within). s_hi = fake_stats(c(2.9, 1.1, 2.35, -3.1, 2.2), mcse = c(0.2, 0.1, 0.2, 0.2, 0.3)) @@ -187,7 +187,7 @@ test_that("print() reports the counts, the movers and high R-hat fits", { expect_match(out, "Their log Bayes factors lie within two standard errors of an evidence threshold") expect_false(grepl("not certifiable", out, fixed = TRUE)) expect_match(out, "1 edge changed verdict beyond Monte Carlo error") - expect_match(out, "e2 presence undecided undecided 0.5x") + expect_match(out, "e2 presence inconclusive inconclusive 0.5x") expect_match(out, "Largest split R-hat above 1.01: 0.5x fit 1.03 and 2x fit 1.02") expect_match(out, "the slab is 5 times that") expect_match(out, "toward absence") @@ -507,7 +507,7 @@ test_that("prior_sensitivity_check compares bgmCompare difference verdicts", { out = paste(utils::capture.output(print(ps)), collapse = "\n") expect_match(out, "are the difference verdicts robust to the difference scale") # main_difference_selection is FALSE by default, so those indicators were - # never updated; the report says so instead of counting them as undecided. + # never updated; the report says so instead of counting them as inconclusive. expect_match(out, "never updated by the sampler and carry no verdict") expect_false(grepl("Note: the slab scale", out, fixed = TRUE)) }) diff --git a/tests/testthat/test-verdicts.R b/tests/testthat/test-verdicts.R index 0fca88a7..4ea350d3 100644 --- a/tests/testthat/test-verdicts.R +++ b/tests/testthat/test-verdicts.R @@ -80,7 +80,7 @@ test_that("the reported evidence is the natural log Bayes factor", { # -1.474 is below the log10 boundary but inside the natural-log one. expect_equal( as.character(v$verdict), - c("presence", "absence", "undecided", "undecided") + c("presence", "absence", "inconclusive", "inconclusive") ) # The printed header names the boundaries in the unit the table reports. @@ -122,7 +122,7 @@ test_that("verdicts() reports one row per edge with a three-way verdict", { expect_s3_class(v, "bgms_verdicts") expect_equal(nrow(v), 15L) expect_equal(v$parameter, rownames(fit$posterior_summary_indicator)) - expect_equal(levels(v$verdict), c("presence", "undecided", "absence")) + expect_equal(levels(v$verdict), c("presence", "inconclusive", "absence")) expect_false(anyNA(v$verdict)) expect_identical(attr(v, "evidence_threshold"), 10) expect_true(attr(v, "flag_validated")) @@ -135,7 +135,7 @@ test_that("verdicts() reports one row per edge with a three-way verdict", { expect_equal(v$bf, reported, tolerance = 1e-8) expect_true(all(v$verdict[reported > 10] == "presence")) expect_true(all(v$verdict[reported < 0.1] == "absence")) - expect_true(all(v$verdict[reported >= 0.1 & reported <= 10] == "undecided")) + expect_true(all(v$verdict[reported >= 0.1 & reported <= 10] == "inconclusive")) # The inclusion probability is the Rao-Blackwellized one the fit reports. expect_equal(v$pip, fit$posterior_summary_indicator$mean, tolerance = 1e-10) @@ -168,8 +168,8 @@ test_that("verdicts() moves the boundaries with evidence_threshold", { loose = verdicts(fit, evidence_threshold = 3) strict = verdicts(fit, evidence_threshold = 100) - # A stricter threshold can only move verdicts toward undecided. - expect_gte(sum(strict$verdict == "undecided"), sum(loose$verdict == "undecided")) + # A stricter threshold can only move verdicts toward inconclusive. + expect_gte(sum(strict$verdict == "inconclusive"), sum(loose$verdict == "inconclusive")) expect_identical(attr(strict, "evidence_threshold"), 100) # The standard errors are properties of the chain, not of the threshold. @@ -234,7 +234,7 @@ test_that("print.bgms_verdicts tallies verdicts and warns once when fragile", { v = verdicts(fit) out = gsub("\\s+", " ", paste(utils::capture.output(print(v)), collapse = " ")) - expect_match(out, "presence \\d+ \\| undecided \\d+ \\| absence \\d+") + expect_match(out, "presence \\d+ \\| inconclusive \\d+ \\| absence \\d+") expect_match(out, "15 indicators") # Edge indicators are what the flag was calibrated on, so no caveat here. expect_false(grepl("not validated", out)) @@ -282,7 +282,7 @@ test_that("the print's tally pluralizes and states the absence threshold cleanly parameter = "a-b", pip = 0.99, log_bf = 4.6, - verdict = factor("presence", levels = c("presence", "undecided", "absence")), + verdict = factor("presence", levels = c("presence", "inconclusive", "absence")), fragile = FALSE, stringsAsFactors = FALSE ), @@ -377,7 +377,7 @@ make_compare_verdicts = function(main_selected) { log_bf = log_bf, verdict = factor( verdict_from_lbf(log_bf, log(10)), - levels = c("presence", "undecided", "absence") + levels = c("presence", "inconclusive", "absence") ), se_two_state = 0.1, se_rb = 0.1, distance_two_state = 5, distance_rb = 5, diff --git a/vignettes/checking-your-model.Rmd b/vignettes/checking-your-model.Rmd index fffce1c4..dfd75f9d 100644 --- a/vignettes/checking-your-model.Rmd +++ b/vignettes/checking-your-model.Rmd @@ -52,8 +52,8 @@ fit = bgm(data, Each edge carries an inclusion Bayes factor, and reading it at a threshold gives one of three verdicts: evidence of presence, evidence of absence, or -undecided. The third is not a failure of the analysis; it is the honest answer -when the data do not separate the two hypotheses. +inconclusive. Inconclusive means the Bayes factor does not reach the evidence +threshold for either presence or absence. ```{r} edges = verdicts(fit) @@ -87,7 +87,7 @@ data rule out, and the pairs the data cannot decide -- drawn on one shared layout, so a variable sits in the same place in all three. Only the first panel is weighted, with line width the posterior mean association and colour its sign; the other two are drawn at uniform width, dashed for a ruled-out pair and -dotted for an undecided one, because there the classification is the result. A +dotted for an inconclusive one. A single drawing would have to leave the last two classes as the same blank, which is exactly what a reader cannot interpret. For one edge in detail, the spike-and-slab posterior shows how the mass is actually divided: diff --git a/vignettes/comparison.Rmd b/vignettes/comparison.Rmd index 9d96a8e9..eb4536a5 100644 --- a/vignettes/comparison.Rmd +++ b/vignettes/comparison.Rmd @@ -31,7 +31,7 @@ probability and an inclusion Bayes factor of its own -- the factor by which the data shift the odds that the groups differ on that parameter [@HuthEtAl_2023; @SekulovskiEtAl_2023]. `verdicts()` reads those Bayes factors against a threshold and returns evidence of a difference, evidence of no -difference, or undecided. +difference, or inconclusive. # ADHD dataset diff --git a/vignettes/fast-ggm.Rmd b/vignettes/fast-ggm.Rmd index 0efbc97d..b78fee5b 100644 --- a/vignettes/fast-ggm.Rmd +++ b/vignettes/fast-ggm.Rmd @@ -92,7 +92,7 @@ The default returns the stated half. The joint specification returns `r round(B$prior$joint, 3)`, and the gap widens as the model grows. Nothing here is broken: the joint specification is a coherent model, and the sampler targets its posterior correctly. But it is a *different* model, so its inclusion Bayes -factors are not interchangeable with the default's. An edge that is undecided +factors are not interchangeable with the default's. An edge that is inconclusive under one specification can show evidence of absence under the other, without either fit being wrong. diff --git a/vignettes/intro.Rmd b/vignettes/intro.Rmd index ad7fde32..a37dd91c 100644 --- a/vignettes/intro.Rmd +++ b/vignettes/intro.Rmd @@ -32,7 +32,7 @@ The graph is treated as unknown rather than fixed. The analysis returns a posterior distribution over graphs and, for every pair of variables, an inclusion Bayes factor: the factor by which the data update the odds that the edge is present. The reporting convention assigns each pair one of three -verdicts: evidence of presence, evidence of absence, or undecided. The +verdicts: evidence of presence, evidence of absence, or inconclusive. The `verdicts()` function reports these classifications. This vignette is the front door: enough to run an analysis and read what comes @@ -135,10 +135,8 @@ verdicts(fit) The default threshold is 10, so an edge is called **presence** when the data multiply its inclusion odds by more than 10, **absence** when they divide them -by more than 10, and **undecided** in between. That third category is not a -failure of the analysis. It is the honest answer when the data separate neither -hypothesis from the other, and being able to report it is the point of treating -the graph as unknown. +by more than 10, and **inconclusive** in between. Inconclusive means the evidence +does not reach the threshold for either presence or absence. The evidence is displayed as `log_bf`, the **natural** logarithm of the Bayes factor: zero is even odds, positive favours presence, negative favours absence, diff --git a/vignettes/prior-sensitivity.Rmd b/vignettes/prior-sensitivity.Rmd index 8d5ce373..b2a73f26 100644 --- a/vignettes/prior-sensitivity.Rmd +++ b/vignettes/prior-sensitivity.Rmd @@ -75,7 +75,7 @@ ps The verdict counts by scale show how the verdicts shift as the slab widens. A wider slab penalizes the extra parameter an edge costs, so evidence for -inclusion weakens and edges move from undecided toward absence; a narrower +inclusion weakens and edges move from inconclusive toward absence; a narrower slab moves them the other way. The four counts below that table classify every edge against the verdict of