View source: R/dina_subgroup.R
| dina_subgroup | R Documentation |
Given a fitted DINA object ("dina" or "dina_bagged") and a data
frame containing the covariates the model was fit on, search over
(covariate, threshold, direction) candidates for subgroups whose mean
per-patient HTE estimate meets the harm threshold m_diff, then select
one according to sg_focus (default "maxSG": the largest qualifying
subgroup). This is the simplest bridge between DINA's continuous
estimator \hat\tau(x) = \hat\beta_0 + x'\hat\beta and
forestsearch's interpretable signature framework.
dina_subgroup(
fit,
df,
covariates,
m_diff,
n_min = 60L,
n_min.frac = 0.1,
direction = c("both", "left", "right"),
max_depth = 2L,
grid_probs = seq(0.1, 0.9, by = 0.1),
sg_focus = "maxSG",
selection_rule = "neighborhood",
effect_neighborhood = 0.1,
alpha = 0.05,
tau_sign = 1
)
fit |
a fitted DINA object of class |
df |
data frame containing the covariate columns referenced by
|
covariates |
character vector of column names in |
m_diff |
scalar harm threshold on the natural-parameter scale
of It is a candidacy floor, not a ranking key. It decides which
candidates enter the qualifying family; Scale. The link (tau) scale of Under Under |
n_min |
positive integer, or |
n_min.frac |
numeric in (0, 1); fraction of |
direction |
one of |
max_depth |
integer, |
grid_probs |
numeric vector of probabilities in |
sg_focus |
character; subgroup selection criterion applied to the
qualifying candidates. One of Five spellings, one rule. On this path
|
selection_rule |
character; rule defining the candidate inclusion
band for |
effect_neighborhood |
numeric in |
alpha |
confidence level for the Wald interval on the
subgroup-mean tau-hat. Default |
tau_sign |
|
For each covariate x_j in covariates, the search visits the
sorted unique values of df[[x_j]] as candidate thresholds q and
for each threshold considers the left-tail subgroup of patients with
x_{j,i} \le q (and optionally also the right-tail subgroup
with x_{j,i} \ge q). A candidate
subgroup must satisfy:
subgroup size |S| >= n_min, AND
mean per-patient tau-hat over S >= m_diff.
Among the qualifying candidates, sg_focus selects the returned
subgroup, mirroring forestsearch()'s selection vocabulary:
"maxSG" (default) – largest qualifying subgroup (legacy
behaviour; size ties broken by the most extreme mean tau-hat).
"minSG" – smallest qualifying subgroup.
"eff" – most extreme effect, ignoring size.
"effMaxSG" – largest subgroup in the candidate inclusion band
(see selection_rule).
"effMinSG" – smallest subgroup in the inclusion band.
The "eff*" band foci reuse the inclusion-band logic shared with
sort_subgroups(); for ratio families (binomial, poisson, cox) the
band is applied on the natural (exponentiated) effect scale.
selection_rule defines the band, exactly as in forestsearch():
"neighborhood" (1-D effect band within effect_neighborhood of the
maximum qualifying effect), "pareto" (the 2-D non-dominated frontier
in (effect, N) space), or "both" (their intersection). DINA's
univariate (covariate, threshold, direction) candidates populate the
(effect, N) plane just as forestsearch's signatures do, so the
frontier is defined analogously.
An object of class "dina_subgroup", a list with components:
logical; TRUE if any candidate satisfied
m_diff and n_min, otherwise FALSE. When FALSE, the
subgroup-specific components below are NULL.
the chosen cut(s). Length
1 for a single-covariate subgroup; length 2 (one entry per
covariate) when max_depth = 2L selects a conjunction.
character vector of the chosen {var op q} factor
label(s), in the form consumed by get_dfpred() (AND-composed).
Length matches covariate.
a single combined display string, e.g.
"{nodes >= 10 & age >= 60}".
integer; number of covariates in the selected
subgroup (1 or 2).
integer size of the chosen subgroup.
scalar subgroup-mean tau-hat (in the
tau_sign orientation).
Wald standard error, computed as
sqrt(a_S^T vcov(fit) a_S) (CONDITIONAL on the chosen
subgroup – not selection-adjusted).
named length-2 vector (lower, upper) giving the
Wald 1 - alpha CI.
logical vector of length nrow(df) marking which
rows are in the chosen subgroup.
the inputs / fit family, echoed for reproducibility.
nrow(df).
total number of (j, dir, q)
triples evaluated.
number of those triples that met
both the size and m_diff constraints.
the matched call.
With max_depth = 2 the candidate set is extended to AND-conjunctions
of two thresholds on distinct covariates, e.g.
nodes >= q1 & age >= q2. Because tau-hat is linear in X, the mean
over the intersection mask is scored exactly like a depth-1 cut, so
the m_diff, n_min, and sg_focus machinery is unchanged. To stay
tractable, depth-2 pairs are generated over a per-covariate quantile
grid (grid_probs) rather than every unique value, while depth-1
singletons retain full resolution. Singletons and pairs are ranked
jointly under sg_focus, so a depth-2 conjunction is returned only
when it outranks every depth-1 candidate; otherwise the depth-1
selection is recovered exactly. When the selected subgroup is a
conjunction, covariate, direction, and threshold are
length-2 vectors and labels holds the two {var op q} factors in
the form consumed by get_dfpred().
The variance of the subgroup-mean tau-hat is computed as
\widehat{\mathrm{Var}}(\bar{\hat\tau}_S) =
a_S^\top \widehat{\mathrm{Var}}(\hat\beta) a_S,
with a_S = (1, \bar{x}_S^\top) and
\widehat{\mathrm{Var}}(\hat\beta) = \mathrm{vcov}(\mathtt{fit}).
The variance source therefore tracks the fit class: sandwich for
"dina" and infinitesimal jackknife for "dina_bagged".
The returned Wald confidence interval is conditional on the
selected (covariate, threshold) being treated as pre-specified.
It does not adjust for the selection across the candidate set and
will undercover when the search space is large. Use this CI for
descriptive reporting; for hypothesis testing against m_diff,
a selection-adjusted interval via bootstrap of the full search
procedure is required. The undercoverage is more pronounced with
max_depth = 2L, whose candidate space is substantially larger.
dina_fit() / dina() for the underlying estimator;
dina_fit_bagged() / dina_bagged() for the bagged variant whose
IJ variance propagates through the subgroup-mean SE here;
sort_subgroups() and forestsearch() for the selection
vocabulary mirrored by sg_focus.
set.seed(1)
n <- 400
df_demo <- data.frame(
w = stats::rbinom(n, 1, 0.5),
x1 = stats::runif(n, -1, 1),
x2 = stats::runif(n, -1, 1),
x3 = stats::runif(n, -1, 1)
)
tau_x <- 0.3 + 1.2 * df_demo$x1 - 0.4 * df_demo$x2
df_demo$y <- 0.5 * df_demo$x1 + df_demo$w * tau_x + stats::rnorm(n)
fit <- dina(df_demo, outcome = "y", treatment = "w",
covariates = c("x1", "x2", "x3"),
family = "gaussian", seed = 1L)
sg <- dina_subgroup(fit, df_demo,
covariates = c("x1", "x2", "x3"),
m_diff = 0.5, n_min = 60L)
sg
# Tighter subgroup via the effect-neighborhood band:
dina_subgroup(fit, df_demo, covariates = c("x1", "x2", "x3"),
m_diff = 0.5, n_min = 60L, sg_focus = "effMaxSG")
# Frontier-aware selection (2-D non-dominated set in (effect, N)):
dina_subgroup(fit, df_demo, covariates = c("x1", "x2", "x3"),
m_diff = 0.5, n_min = 60L, sg_focus = "effMaxSG",
selection_rule = "both")
# Depth-2: allow AND-conjunctions of two covariates.
dina_subgroup(fit, df_demo, covariates = c("x1", "x2", "x3"),
m_diff = 0.5, n_min = 60L, max_depth = 2L)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.