Nothing
# =============================================================================
# grf_subgroup_labels.R - Correct subgroup-definition construction for GRF
# =============================================================================
#
# GRF policy trees define the identified subgroup as a set of leaves. The
# textual subgroup definition must be the EXACT root-to-leaf decision path(s)
# for those leaves, with correct per-split directions:
# * left child => "var <= value"
# * right child => "var > value"
# A subgroup spanning multiple leaves is therefore a DISJUNCTION of
# conjunctions (a union of axis-aligned boxes), which a single AND-composed
# label vector cannot represent.
#
# The helpers here build that definition directly from the policy-tree
# topology (node `left_child`/`right_child` give the path; `split_variable`
# indexes `tree$columns`; `predict(tree, X, type = "node.id")` returns the
# 1-based position in `tree$nodes`, so leaf targets are node positions).
#
# Two earlier builders were structurally unable to do this and produced
# subgroup definitions that did not match GRF's own membership whenever a
# path turned right or the subgroup spanned more than one leaf:
# * find_leaf_split() (survival): returned only the single split
# immediately above one leaf.
# * .build_sg_harm_id() (GLM): emitted every internal-node split as
# "<=", ignoring path and direction.
# Both now delegate here.
# =============================================================================
# ---------------------------------------------------------------------------
# Internal: parent/direction map for a policy_tree
# ---------------------------------------------------------------------------
# Returns, for each node position, its parent position and whether it is the
# parent's left ("<=") or right (">") child. Root has parent 0L.
#' @noRd
.grf_parent_map <- function(tree) {
nodes <- tree$nodes
k <- length(nodes)
parent <- integer(k); side <- character(k)
parent[] <- 0L; side[] <- ""
for (i in seq_len(k)) {
nd <- nodes[[i]]
if (isTRUE(nd$is_leaf)) next
lc <- nd$left_child; rc <- nd$right_child
if (!is.null(lc) && lc >= 1L && lc <= k) { parent[lc] <- i; side[lc] <- "left" }
if (!is.null(rc) && rc >= 1L && rc <= k) { parent[rc] <- i; side[rc] <- "right" }
}
list(parent = parent, side = side)
}
# ---------------------------------------------------------------------------
# Internal: root-to-leaf conjunction for one leaf
# ---------------------------------------------------------------------------
# Walks from `leaf` up to the root, recording each ancestor split as a
# (variable, op, value) triple with the direction taken to reach the leaf.
# Returns a data.frame of components in root-to-leaf order.
#' @noRd
.grf_leaf_conjunction <- function(tree, leaf, pmap) {
nodes <- tree$nodes
columns <- tree$columns
comps <- list()
cur <- leaf
guard <- 0L
while (cur >= 1L && pmap$parent[cur] != 0L) {
par <- pmap$parent[cur]
sd <- pmap$side[cur]
pnode <- nodes[[par]]
var <- columns[pnode$split_variable]
op <- if (identical(sd, "left")) "<=" else ">"
comps[[length(comps) + 1L]] <- data.frame(
variable = var, op = op, value = as.numeric(pnode$split_value),
stringsAsFactors = FALSE)
cur <- par
guard <- guard + 1L
if (guard > length(nodes)) break # cycle guard; trees are acyclic
}
if (length(comps) == 0L)
return(data.frame(variable = character(0), op = character(0),
value = numeric(0), stringsAsFactors = FALSE))
out <- do.call(rbind, rev(comps)) # root-to-leaf order
.grf_simplify_conjunction(out)
}
# ---------------------------------------------------------------------------
# Internal: drop dominated same-variable, same-direction cuts
# ---------------------------------------------------------------------------
# Within one conjunction (AND), repeated cuts on the same variable in the same
# direction collapse to the binding one:
# multiple "x <= a" -> smallest a (tightest upper bound)
# multiple "x > b" -> largest b (tightest lower bound)
# Opposite-direction cuts on the same variable (an interval) are both kept.
#' @noRd
.grf_simplify_conjunction <- function(cj) {
if (nrow(cj) <= 1L) return(cj)
keep <- rep(TRUE, nrow(cj))
for (v in unique(cj$variable)) {
for (o in c("<=", ">")) {
idx <- which(cj$variable == v & cj$op == o)
if (length(idx) > 1L) {
bind <- if (o == "<=") idx[which.min(cj$value[idx])]
else idx[which.max(cj$value[idx])]
drop <- setdiff(idx, bind)
keep[drop] <- FALSE
}
}
}
cj[keep, , drop = FALSE]
}
# ---------------------------------------------------------------------------
# Internal: format one conjunction as a brace-label vector
# ---------------------------------------------------------------------------
# Each component becomes "{var op value}". digits controls value formatting.
#' @noRd
.grf_conjunction_labels <- function(cj, digits = 17L) {
if (nrow(cj) == 0L) return(character(0))
sprintf("{%s %s %s}", cj$variable, cj$op,
formatC(cj$value, format = "g", digits = digits, width = 1L))
}
# ---------------------------------------------------------------------------
# Build the GRF subgroup definition from the tree + target leaves
# ---------------------------------------------------------------------------
#' Construct a correct subgroup definition from a GRF policy tree
#'
#' Returns the exact root-to-leaf decision rule(s) for `target_leaves`,
#' with correct directions, as a structured definition consumed by
#' \code{\link{evaluate_grf_subgroup}} and rendered for display.
#'
#' @param tree A \code{policy_tree} object (has \code{$nodes}, \code{$columns}).
#' @param target_leaves Integer vector of leaf node positions (as returned by
#' \code{predict(tree, X, type = "node.id")}) that constitute the subgroup.
#' @param digits Significant digits for threshold formatting in labels.
#'
#' @return A list with:
#' \describe{
#' \item{conjunctions}{list of data.frames, one per target leaf, each with
#' columns variable/op/value (simplified).}
#' \item{labels}{when there is exactly ONE conjunction, a character vector
#' of \code{"{var op value}"} component labels (back-compatible with
#' \code{\link{get_dfpred}}); \code{NULL} for a union.}
#' \item{definition}{a single human-readable string: one
#' parenthesised conjunction, or several joined by \code{" | "} for a
#' union.}
#' \item{is_disjunction}{logical; \code{TRUE} when the subgroup spans more
#' than one leaf (cannot be a single AND-label vector).}
#' }
#' @keywords internal
#' @noRd
.grf_build_subgroup_definition <- function(tree, target_leaves, digits = 17L) {
pmap <- .grf_parent_map(tree)
leaves <- sort(unique(as.integer(target_leaves)))
conjunctions <- lapply(leaves, function(lf)
.grf_leaf_conjunction(tree, lf, pmap))
# Drop any empty conjunctions (a degenerate root-only "tree" selecting all).
nonempty <- vapply(conjunctions, nrow, integer(1)) > 0L
conjunctions <- conjunctions[nonempty]
is_disj <- length(conjunctions) > 1L
if (length(conjunctions) == 0L) {
return(list(conjunctions = list(), labels = NULL,
definition = NA_character_, is_disjunction = FALSE))
}
conj_strings <- vapply(conjunctions, function(cj) {
parts <- sprintf("%s %s %s", cj$variable, cj$op,
formatC(cj$value, format = "g", digits = digits, width = 1L))
paste(parts, collapse = " & ")
}, character(1))
if (is_disj) {
definition <- paste0("(", conj_strings, ")", collapse = " | ")
labels <- NULL
} else {
definition <- conj_strings[1]
labels <- .grf_conjunction_labels(conjunctions[[1]], digits = digits)
}
list(conjunctions = conjunctions, labels = labels,
definition = definition, is_disjunction = is_disj)
}
# ---------------------------------------------------------------------------
# Evaluate a GRF subgroup definition on new data (AND of comps, OR of leaves)
# ---------------------------------------------------------------------------
#' Evaluate a GRF subgroup definition and return membership
#'
#' Computes subgroup membership for an arbitrary data frame from the structured
#' definition built by \code{.grf_build_subgroup_definition()}. Membership is
#' the union (OR) over conjunctions, each the intersection (AND) over its
#' components -- so it reproduces \code{predict(tree, X)} on the fit data and
#' applies cleanly to \code{df.predict} / \code{df.test}.
#'
#' @param def A definition list from \code{.grf_build_subgroup_definition()}.
#' @param df A data frame containing the split variables.
#'
#' @return Integer vector \code{treat.recommend}: 0 for subgroup members (harm),
#' 1 for the complement.
#' @keywords internal
#' @noRd
.grf_evaluate_subgroup <- function(def, df) {
n <- nrow(df)
conjunctions <- def$conjunctions
if (length(conjunctions) == 0L) {
# No subgroup -> everyone in complement.
return(rep(1L, n))
}
in_any <- rep(FALSE, n)
for (cj in conjunctions) {
in_cj <- rep(TRUE, n)
for (r in seq_len(nrow(cj))) {
v <- cj$variable[r]; op <- cj$op[r]; val <- cj$value[r]
if (!v %in% names(df))
stop("Subgroup variable '", v, "' not found in data.", call. = FALSE)
# Code the column exactly as the forest's covariate matrix does
# (.grf_code_column(), shared with .build_grf_X()): a factor with levels
# "0"/"1" is compared as 0/1, not as a factor, which R cannot order.
x <- .grf_code_column(df[[v]])
member <- switch(op,
"<=" = x <= val,
">" = x > val,
"<" = x < val,
">=" = x >= val,
stop("Unsupported operator '", op, "'.", call. = FALSE))
in_cj <- in_cj & member
}
in_any <- in_any | in_cj
}
ifelse(in_any, 0L, 1L)
}
# =============================================================================
# GRF doubly-robust-score Pareto frontier (selection = "frontier")
# =============================================================================
# An alternative to the policy tree that consumes the SAME doubly-robust score
# matrix. It enumerates single-covariate thresholds (depth 1) and, when
# grf_depth >= 2, covariate-pair conjunctions (depth 2), scores each candidate
# subgroup S by its DR harm-effect (mean(control[S]) - mean(treated[S])) and
# size, takes the Pareto frontier, and selects one subgroup under a rule
# (effMaxSG / eff / maxSG). The selected subgroup is always a single
# conjunction, so it maps directly onto the standard sg_def structure.
#
# Sign convention matches the tree path: dr columns are per-action value
# estimates (higher = better outcome); diff = control - treated > 0 means
# treatment harms S. dmin is the harm-eligibility threshold (== dmin.grf).
# =============================================================================
#' Enumerate single-covariate DR-score candidates
#' @noRd
.grf_dr_candidates <- function(X, dr, grid_probs = seq(0.1, 0.9, 0.1),
n_min = 60L) {
ctrl <- dr[, 1L]; trt <- dr[, 2L]; n <- nrow(X); cn <- colnames(X)
out <- list(); k <- 0L
for (j in seq_len(ncol(X))) {
xj <- X[, j]
cuts <- unique(stats::quantile(xj, probs = grid_probs, names = FALSE,
type = 7))
for (cc in cuts) for (dir in c("left", "right")) {
S <- if (dir == "left") xj <= cc else xj > cc
nS <- sum(S)
if (nS < n_min || nS > n - 1L) next
k <- k + 1L
out[[k]] <- data.frame(
v1 = cn[j], d1 = dir, c1 = as.numeric(cc),
v2 = NA_character_, d2 = NA_character_, c2 = NA_real_,
effect = mean(ctrl[S]) - mean(trt[S]), size = nS,
stringsAsFactors = FALSE)
}
}
if (!k) return(NULL)
do.call(rbind, out)
}
#' Enumerate depth-2 covariate-pair DR-score candidates
#' @noRd
.grf_dr_candidates_d2 <- function(X, dr, grid_probs = seq(0.2, 0.8, 0.2),
n_min = 60L) {
ctrl <- dr[, 1L]; trt <- dr[, 2L]; n <- nrow(X); p <- ncol(X); cn <- colnames(X)
conds <- vector("list", p)
for (j in seq_len(p)) {
xj <- X[, j]
cuts <- unique(stats::quantile(xj, probs = grid_probs, names = FALSE,
type = 7))
cl <- list()
for (cc in cuts) for (dir in c("left", "right"))
cl[[length(cl) + 1L]] <- list(cov = cn[j], dir = dir, cut = cc,
v = if (dir == "left") xj <= cc else xj > cc)
conds[[j]] <- cl
}
out <- list(); k <- 0L
if (p >= 2L) for (j in seq_len(p - 1L)) for (jj in (j + 1L):p) {
for (a in conds[[j]]) for (b in conds[[jj]]) {
S <- a$v & b$v; nS <- sum(S)
if (nS < n_min || nS > n - 1L) next
k <- k + 1L
out[[k]] <- data.frame(
v1 = a$cov, d1 = a$dir, c1 = as.numeric(a$cut),
v2 = b$cov, d2 = b$dir, c2 = as.numeric(b$cut),
effect = mean(ctrl[S]) - mean(trt[S]), size = nS,
stringsAsFactors = FALSE)
}
}
if (!k) return(NULL)
do.call(rbind, out)
}
#' Mark the Pareto frontier on (effect maximize, size maximize)
#'
#' Contract unchanged: returns \code{cand} sorted by \code{(-effect, -size)}
#' with an added logical \code{on_frontier} column.
#'
#' Dominance now comes from \code{.pareto_dominated_xy()}, the same core the
#' consistency engine and \code{.compute_inclusion_band()} use on the same
#' axes, rather than a local sweep. The two agree except on exact duplicates in
#' \code{(effect, size)}: the sweep's \code{size > best_size} test kept only the
#' first of a tied pair, whereas \code{.pareto_dominated_xy()} requires a strict
#' improvement on one axis, so identical points are all non-dominated. The
#' latter is the correct reading of Pareto dominance, and \code{on_frontier} is
#' a reported field rather than a selection input (its only caller is
#' \code{grf_main.R}), so the change is confined to what is displayed.
#' @noRd
.grf_mark_frontier <- function(cand) {
ord <- order(-cand$effect, -cand$size)
cand <- cand[ord, , drop = FALSE]
cand$on_frontier <- !.pareto_dominated_xy(cand$effect, cand$size)
cand
}
#' Select one frontier subgroup under a rule (harm side: effect >= dmin)
#'
#' @param rule one of \code{"effMaxSG"} (default), \code{"eff"}, \code{"maxSG"},
#' \code{"minSG"}, \code{"effMinSG"}; semantics match \code{dina_subgroup()}'s
#' \code{sg_focus}. \code{"eff"} = max harm-effect; \code{"maxSG"}/\code{"minSG"}
#' = largest/smallest eligible (effect >= dmin); \code{"effMaxSG"}/
#' \code{"effMinSG"} = largest/smallest within a relative neighborhood of the
#' max harm-effect.
#' @param nbhd relative neighborhood for the \code{eff*SG} rules: keep candidates
#' with effect >= (1 - nbhd) * max-eligible-effect, then take the
#' largest/smallest.
#' @param selection_rule one of \code{"neighborhood"} (default), \code{"pareto"},
#' \code{"both"}, defining the inclusion band for the \code{eff*SG} rules.
#' Previously this argument did not exist and the band was hardcoded to the
#' multiplicative neighborhood, so a caller asking for \code{"pareto"} or
#' \code{"both"} was silently given \code{"neighborhood"} -- while MR's
#' re-selection honoured the request, leaving the identifier and MR banding
#' differently. The band now comes from \code{.compute_inclusion_band()}, the
#' same helper DINA and the consistency engine use.
#' @return one-row data.frame (the selected candidate), or NULL.
#' @noRd
.grf_frontier_select <- function(cand, dmin, rule = "effMaxSG", nbhd = 0.10,
selection_rule = "neighborhood") {
if (is.null(cand) || !nrow(cand)) return(NULL)
elig <- cand[cand$effect >= dmin, , drop = FALSE]
if (!nrow(elig)) return(NULL)
if (rule == "maxSG") {
elig[which.max(elig$size), , drop = FALSE]
} else if (rule == "minSG") {
elig[which.min(elig$size), , drop = FALSE]
} else if (rule == "eff") {
elig[which.max(elig$effect), , drop = FALSE]
} else { # effMaxSG / effMinSG: restrict to the inclusion band first
# Identical to the former hardcoded band under the default
# selection_rule = "neighborhood": .compute_inclusion_band() applies
# (1 - effect_neighborhood) * max(effect), which is the same comparison as
# the previous effect >= emax * (1 - nbhd).
in_band <- .compute_inclusion_band(
hr_vec = elig$effect,
n_vec = elig$size,
selection_rule = selection_rule,
effect_neighborhood = nbhd)
band <- elig[in_band == 1L, , drop = FALSE]
# No empty-band fallback here, deliberately. The band CAN empty: when the
# maximum effect is negative, (1 - nbhd) * emax exceeds emax, so even the
# maximum fails its own test. That is a property of the formula, identical
# before and after this change, and the old code likewise returned a
# zero-row selection. MR's .inband() does carry a "never empty" fallback;
# reconciling the two is a decision pending on its own, and adding a
# fallback here would pre-empt it and change behaviour beyond threading.
if (rule == "effMinSG") {
band[which.min(band$size), , drop = FALSE]
} else { # effMaxSG (default)
band[which.max(band$size), , drop = FALSE]
}
}
}
#' Build the standard sg_def structure from a selected frontier candidate
#'
#' A frontier subgroup is a single conjunction (one or two cuts), so this
#' returns the same shape as \code{.grf_build_subgroup_definition()} for a
#' one-leaf subgroup: a labels vector, a definition string, conjunctions list,
#' and is_disjunction = FALSE.
#' @noRd
.grf_sg_def_from_candidate <- function(cand_row, digits = 17L) {
comps <- list(data.frame(
variable = cand_row$v1,
op = if (cand_row$d1 == "left") "<=" else ">",
value = as.numeric(cand_row$c1), stringsAsFactors = FALSE))
if (!is.na(cand_row$v2)) {
comps[[2L]] <- data.frame(
variable = cand_row$v2,
op = if (cand_row$d2 == "left") "<=" else ">",
value = as.numeric(cand_row$c2), stringsAsFactors = FALSE)
}
cj <- do.call(rbind, comps)
cj <- .grf_simplify_conjunction(cj)
parts <- sprintf("%s %s %s", cj$variable, cj$op,
formatC(cj$value, format = "g", digits = digits, width = 1L))
list(conjunctions = list(cj),
labels = .grf_conjunction_labels(cj, digits = digits),
definition = paste(parts, collapse = " & "),
is_disjunction = FALSE)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.