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
5 changes: 5 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion R/centrality.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 1 addition & 2 deletions R/extractor_functions.R
Original file line number Diff line number Diff line change
Expand Up @@ -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{
Expand Down
61 changes: 25 additions & 36 deletions R/plot_bgms.R
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)
))
}
Expand All @@ -43,7 +43,7 @@ network_unit = function(kind = c("edge", "difference")) {
panels = c(
presence = "difference supported",
absence = "difference ruled out",
undecided = "undecided"
inconclusive = "inconclusive"
)
)
}
Expand All @@ -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)
)
}

Expand All @@ -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).
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"
Expand All @@ -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,
...
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down
8 changes: 4 additions & 4 deletions R/prior_sensitivity.R
Original file line number Diff line number Diff line change
Expand Up @@ -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_
Expand Down Expand Up @@ -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")
Expand Down
2 changes: 1 addition & 1 deletion R/refit_engine.R
Original file line number Diff line number Diff line change
Expand Up @@ -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_
Expand Down
12 changes: 6 additions & 6 deletions R/verdicts.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)) {
Expand Down
2 changes: 1 addition & 1 deletion man/extract_centrality.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/extract_inclusion_bf.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 6 additions & 10 deletions man/plot.bgmCompare.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading