Adaptive Alpha from an Actual Tree Structure

Factory function counterpart to alpha_adaptive for irregular trees. Creates an alpha adjustment function for use with find_blocks, using actual per-node sample sizes to compute the alpha schedule instead of assuming a regular k-ary tree.

Usage

alpha_adaptive_tree(
  node_dat,
  delta_hat,
  max_depth = NULL,
  budget_weights = NULL
)

Arguments

node_dat

A data.frame or data.table with columns nodenum, parent, depth, and nodesize. Typically extracted from a find_blocks result. The root node must have parent = 0 and depth = 1.

delta_hat

Estimated standardized effect size (e.g., Cohen's d). Conservative (larger) values produce more stringent adjustment, which preserves the FWER guarantee.

max_depth

Maximum depth to compute. Defaults to the maximum depth present in node_dat.

budget_weights

Controls how the error budget is allocated across depths (Theorems B.3 and B.5 in the supplement). Options:

NULL

(default) No budget weights — use the telescoping formula \(\alpha_\ell = \alpha / G_\ell\). This is the tightest bound for regular k-ary trees (Theorem B.2).

"equal"

Equal weights: \(w_\ell = 1/(L-1)\) for all depths \(\ell \ge 2\).

"proportional"

Error-load-proportional: \(w_\ell = G_\ell / \sum G\), giving a uniform adjusted alpha of \(\alpha / \sum G\) at every depth.

numeric vector

Custom weights for depths 2 through L. Must have length \(L - 1\) and sum to at most 1.

Value

A function with signature function(pval, batch, nodesize, thealpha, thew0, depth) conforming to the alphafn interface used by find_blocks.

Details

The returned function behaves identically to the closure from alpha_adaptive: it uses the depth parameter to look up pre-computed alphas, ignoring pval, batch, and other arguments. The difference is that the alpha schedule comes from compute_adaptive_alphas_tree rather than the parametric formula, so it handles irregular branching correctly.

Results are cached internally: the alpha schedule is computed once per unique value of thealpha and reused on subsequent calls.

Examples

# Build a tree template from the DPP design
nd <- data.frame(
  nodenum  = 1:7,
  parent   = c(0, 1, 1, 2, 2, 3, 3),
  depth    = c(1, 2, 2, 3, 3, 3, 3),
  nodesize = c(500, 250, 250, 125, 125, 100, 150)
)
my_alpha <- alpha_adaptive_tree(node_dat = nd, delta_hat = 0.5)

# Use with find_blocks
# find_blocks(idat, bdat, ..., alphafn = my_alpha)