View source: R/dina_subgroup.R
| dina_frontier | R Documentation |
Runs the same univariate (covariate, direction, threshold) search as
dina_subgroup(), but instead of selecting one subgroup it returns a
pool of per-covariate Pareto-non-dominated cuts. Each cut is
rendered as a forestsearch cut expression ("x1 <= 0.5"), so the pool
can be fed to forestsearch() as screening-stage candidates in the
same way GRF tree cuts are. This is the DINA analog of GRF candidate
discovery.
dina_frontier(
fit,
df,
covariates,
scope = c("wide", "harm"),
m_diff = NULL,
n_min = 60L,
direction = c("both", "left", "right"),
max_per_covariate = Inf,
max_subgroups = Inf,
digits = 3L
)
fit |
a fitted DINA object (class |
df |
data frame containing the covariate columns. |
covariates |
character vector of numeric covariate columns to search over. |
scope |
one of |
m_diff |
scalar harm floor on the link (natural-parameter) scale.
Required when |
n_min |
positive integer minimum subgroup size. Default |
direction |
one of |
max_per_covariate |
positive integer, or |
max_subgroups |
positive integer, or Both caps default to |
digits |
significant figures for rounding the emitted threshold
in |
Why per-covariate and not a single global frontier. The global Pareto frontier in (effect, N) space collapses onto whichever single covariate dominates the trade-off boundary, returning many micro-stepped cuts on that one covariate. That is faithful to the definition but the opposite of what forestsearch needs: its value is in composing cuts drawn from several covariates. So this function computes a separate frontier for each covariate, then pools them, mirroring how a GRF tree splits on multiple variables.
Two caps, each optional. Both caps act on this function's return
value and nothing else: they trim the frontier table of single cuts
that is returned here. They are not a cap on a selection family – the
rows they trim are univariate cuts, never conjunctions – and
dina_subgroup() does not take them, so nothing they do reaches the
subgroup selector. Either may be Inf to disable it:
max_per_covariate bounds how many cuts any single covariate
contributes (its top cuts by effect), limiting within-covariate
redundancy.
max_subgroups bounds the total pool size across covariates.
Under forestsearch(subgroup_method = "dina") neither cap has any effect:
that path selects with dina_subgroup() and never consults a frontier
table. They bite only where this function's output is used directly –
including forestsearch(use_dina = TRUE, dina_args = list(selected_only = FALSE)), where cut_expr becomes the screening-stage candidate pool.
When the pool exceeds max_subgroups, the global trim is round-robin
on within-covariate effect rank – every covariate's best cut first
(ordered by effect), then every covariate's second-best, and so on –
so a finite budget preserves cross-covariate spread instead of
refilling with one covariate's micro-steps. Setting
max_per_covariate = Inf recovers a pure global budget; setting
max_subgroups = Inf recovers per-covariate-only limits. Both default to
Inf, and a finite cap that actually removes rows warns rather than
trimming the display silently.
Cut form. The expression is always the canonical "<covariate> <= <threshold>". forestsearch's factor machinery exposes both the
cut and its complement, so one expression covers both of DINA's
left/right directions – the direction column is retained for
reference only. Thresholds are rounded to digits significant
figures so they deduplicate cleanly against existing GRF / median cuts
and read well; raw values remain in threshold.
These cuts are candidates, not forced selections: forestsearch
composes (up to maxk) and consistency-gatekeeps them, exactly as it
does GRF cuts. To use them without disturbing any user-supplied
forced cuts, append rather than overwrite, e.g.
forestsearch(..., conf_force = c(my_forced_cuts, fr$cut_expr)).
A data frame (one row per cut, after the caps and threshold-rounding deduplication) with columns:
the subgroup definition (raw threshold).
subgroup size.
subgroup-mean tau-hat on the link scale.
the same on the natural scale (exponentiated for ratio families binomial/poisson/cox), used for the frontiers and the effect ranking.
the canonical forestsearch cut expression.
The result carries attributes n_frontier (total per-covariate
frontier size, deduped, before the caps), n_qualifying, and
scope. Returns a 0-row data frame (same columns) when no candidate
qualifies.
dina_subgroup() for the single-subgroup selector;
forestsearch() for the screening stage that consumes the cuts;
compute_pareto_frontier() for the post-hoc frontier reporting on a
forestsearch result.
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)
fr <- dina_frontier(fit, df_demo, covariates = c("x1", "x2", "x3"),
n_min = 60L)
fr
fr$cut_expr # ready to append to forestsearch(conf_force = ...)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.