dina_frontier: Extract DINA per-covariate Pareto frontiers as forestsearch...

View source: R/dina_subgroup.R

dina_frontierR Documentation

Extract DINA per-covariate Pareto frontiers as forestsearch cuts

Description

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.

Usage

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
)

Arguments

fit

a fitted DINA object (class "dina" or "dina_bagged").

df

data frame containing the covariate columns.

covariates

character vector of numeric covariate columns to search over.

scope

one of "wide" (default) or "harm". "wide" casts a broad net: every candidate with size ⁠>= n_min⁠ is eligible, and the per-covariate frontiers span the whole effect-size boundary (mirroring GRF's wide-net role, leaving forestsearch's consistency stage as the gatekeeper). "harm" restricts the eligible set to candidates with mean tau-hat ⁠>= m_diff⁠ before taking the frontiers.

m_diff

scalar harm floor on the link (natural-parameter) scale. Required when scope = "harm"; ignored when scope = "wide". Default NULL.

n_min

positive integer minimum subgroup size. Default 60L.

direction

one of "both" (default), "left", "right".

max_per_covariate

positive integer, or Inf for no limit: the most cuts any single covariate may contribute to the returned table (its top cuts by effect). A report-trimming cap, not a search control. Default Inf – show everything. A finite value that actually trims warns, naming the kept and available counts.

max_subgroups

positive integer, or Inf for no limit: the cap on the total pooled cuts in the returned table. When the pool is larger it is trimmed round-robin by within-covariate effect rank. Default Inf; a finite value that actually trims warns, naming the kept and available counts.

Both caps default to Inf for the same reason forestsearch()'s max_subgroups_search does: a finite pooled cap drops covariates whole and truncates the rank-2 pass, so the table stops being a faithful picture of the frontier. The two are still not the same knob – max_subgroups_search truncates the pool of candidate subgroups that forestsearch actually evaluates at the consistency stage, while max_subgroups trims the rows of the table this function returns. One changes what is computed; the other changes what is reported.

digits

significant figures for rounding the emitted threshold in cut_expr. Default 3L.

Details

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)).

Value

A data frame (one row per cut, after the caps and threshold-rounding deduplication) with columns:

covariate, direction, threshold

the subgroup definition (raw threshold).

n_subgroup

subgroup size.

mean_tau_hat

subgroup-mean tau-hat on the link scale.

effect

the same on the natural scale (exponentiated for ratio families binomial/poisson/cox), used for the frontiers and the effect ranking.

cut_expr

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.

See Also

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.

Examples

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 = ...)


forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.