R/grf_helpers.R

Defines functions .grf_code_column validate_grf_data print_grf_details create_null_result create_success_result assign_subgroup_membership extract_selected_tree_cuts extract_all_tree_cuts find_leaf_split extract_tree_cuts select_best_subgroup fit_policy_trees compute_node_metrics fit_causal_forest create_grf_config

Documented in assign_subgroup_membership compute_node_metrics create_grf_config create_null_result create_success_result extract_all_tree_cuts extract_selected_tree_cuts extract_tree_cuts find_leaf_split fit_causal_forest fit_policy_trees print_grf_details select_best_subgroup validate_grf_data

#' Helper Functions for GRF Subgroup Analysis
#'
#' This file contains helper functions used by grf.subg.harm.survival()
#' to improve readability and modularity.

#' Create GRF configuration object
#'
#' Creates a configuration object to organize GRF parameters
#'
#' @param frac.tau Numeric. Fraction of tau for GRF horizon
#' @param n.min Integer. Minimum subgroup size
#' @param dmin.grf Numeric. Minimum difference in subgroup mean
#' @param RCT Logical. Is the data from a randomized controlled trial?
#' @param sg.criterion Character. Subgroup selection criterion
#' @param maxdepth Integer. Maximum tree depth
#' @param seedit Integer. Random seed
#' @return List with configuration parameters
#' @examples
#' cfg <- create_grf_config(frac.tau = 0.6, n.min = 60, dmin.grf = 6,
#'                          RCT = TRUE, sg.criterion = "mDiff",
#'                          maxdepth = 2, seedit = 42L)
#' str(cfg)
#' @export

create_grf_config <- function(frac.tau, n.min, dmin.grf, RCT,
                              sg.criterion, maxdepth, seedit) {
  list(
    frac.tau = frac.tau,
    n.min = n.min,
    dmin.grf = dmin.grf,
    RCT = RCT,
    sg.criterion = sg.criterion,
    maxdepth = maxdepth,
    seedit = seedit,
    valid_criteria = c("mDiff", "Nsg"),
    max_tree_depth = 3,
    return_selected_cuts_only = FALSE
  )
}

#' Fit causal survival forest
#'
#' Wrapper function to fit GRF causal survival forest with appropriate settings
#'
#' @param X Matrix. Covariate matrix
#' @param Y Numeric vector. Outcome variable
#' @param W Numeric vector. Treatment indicator
#' @param D Numeric vector. Event indicator
#' @param tau.rmst Numeric. Time horizon for RMST
#' @param RCT Logical. Is this RCT data?
#' @param seedit Integer. Random seed
#' @param tune_grf Logical. If TRUE, enables cross-validated hyperparameter
#'   tuning via \code{tune.parameters = "all"}. Default FALSE.
#' @return Causal survival forest object
#' @examples
#' \donttest{
#' library(survival)
#' library(grf)
#' df <- survival::gbsg
#' X <- as.matrix(df[, c("age", "meno", "size", "nodes", "pgr", "er")])
#' tau <- quantile(df$rfstime[df$status == 1], 0.6)
#' cs <- fit_causal_forest(X = X, Y = df$rfstime, W = df$hormon,
#'                         D = df$status, tau.rmst = tau,
#'                         RCT = FALSE, seedit = 42L)
#' }
#' @export

fit_causal_forest <- function(X, Y, W, D, tau.rmst, RCT, seedit,
                              tune_grf = FALSE) {
  tune_arg <- if (tune_grf) "all" else "none"
  if (RCT) {
    cs.forest <- try(
      suppressWarnings(
        grf::causal_survival_forest(X, Y, W, D, W.hat = 0.5,
                                    horizon = tau.rmst, seed = seedit,
                                    tune.parameters = tune_arg,
                                    num.threads = .fs_grf_num_threads())
      ),
      TRUE
    )
  } else {
    cs.forest <- try(
      suppressWarnings(
        grf::causal_survival_forest(X, Y, W, D,
                                    horizon = tau.rmst, seed = seedit,
                                    tune.parameters = tune_arg,
                                    num.threads = .fs_grf_num_threads())
      ),
      TRUE
    )
  }

  if (inherits(cs.forest, "try-error")) {
    stop("Failed to fit causal survival forest: ", attr(cs.forest, "condition")$message)
  }

  return(cs.forest)
}


#' Compute node metrics for a policy tree
#'
#' Aggregates scores by leaf node and calculates treatment effect differences
#'
#' @param data Data frame. Original data
#' @param dr.scores Matrix. Doubly robust scores
#' @param tree Policy tree object
#' @param X Matrix. Covariate matrix
#' @param n.min Integer. Minimum subgroup size
#' @return Data frame with node metrics
#' @importFrom stats aggregate
#' @examples
#' \dontrun{
#' # compute_node_metrics() is called internally by grf.subg.harm.survival().
#' # See grf.subg.harm.survival() for the standard entry point.
#' }
#' @export

compute_node_metrics <- function(data, dr.scores, tree, X, n.min) {
  data$predict.node <- predict(tree, X, type = "node.id")

  values <- stats::aggregate(
    dr.scores,
    by = list(leaf.node = data$predict.node),
    FUN = function(x) c(
      mean = mean(x),
      size = length(x),
      se = sd(x) / sqrt(length(x))
    )
  )

  values$diff <- values$control[, "mean"] - values$treated[, "mean"]
  values$Nsg <- values$control[, "size"]

  # Filter by minimum size requirement
  values <- values[values$control[, "size"] >= n.min, ]

  return(values)
}

#' Fit policy trees up to specified depth
#'
#' Fits policy trees of depths 1 through maxdepth and computes metrics
#'
#' @param X Matrix. Covariate matrix
#' @param data Data frame. Original data
#' @param dr.scores Matrix. Doubly robust scores
#' @param maxdepth Integer. Maximum tree depth (1-3)
#' @param n.min Integer. Minimum subgroup size
#' @return List with trees and combined values
#' @importFrom policytree policy_tree
#' @examples
#' \dontrun{
#' # fit_policy_trees() is called internally by grf.subg.harm.survival().
#' # See grf.subg.harm.survival() for the standard entry point.
#' }
#' @export

fit_policy_trees <- function(X, data, dr.scores, maxdepth, n.min) {
  trees <- list()
  all_values <- list()

  for (depth in 1:maxdepth) {
    trees[[depth]] <- policytree::policy_tree(X, dr.scores, depth = depth)

    values <- compute_node_metrics(data, dr.scores, trees[[depth]], X, n.min)
    values$depth <- depth
    all_values[[depth]] <- values
  }

  # Combine all values across depths
  combined_values <- do.call(rbind, all_values)

  return(list(
    trees = trees,
    values = combined_values
  ))
}

#' Select best subgroup based on criterion
#'
#' Identifies the optimal subgroup according to the specified criterion
#'
#' @param values Data frame. Node metrics from policy trees
#' @param sg.criterion Character. "mDiff" for maximum difference, "Nsg" for largest size
#' @param dmin.grf Numeric. Minimum difference threshold
#' @param n.max Integer. Maximum allowed subgroup size (total sample size)
#' @return Data frame row with best subgroup or NULL if none found
#' @examples
#' vals <- data.frame(diff = c(8.5, 6.2, 3.1), Nsg = c(120, 95, 80))
#' select_best_subgroup(values = vals, sg.criterion = "mDiff",
#'                      dmin.grf = 6, n.max = 500)
#' @export

select_best_subgroup <- function(values, sg.criterion, dmin.grf, n.max) {
  if (nrow(values) == 0) {
    return(NULL)
  }

  if (sg.criterion == "mDiff") {
    # Select subgroup with maximum difference
    loc.max <- which.max(values$diff)
    max.diff <- values[loc.max, , drop = FALSE]

  } else if (sg.criterion == "Nsg") {
    # Select largest subgroup meeting minimum difference threshold
    eligible <- values[values$diff >= dmin.grf, , drop = FALSE]

    if (nrow(eligible) == 0) {
      return(NULL)
    }

    loc.max <- which.max(eligible$Nsg)
    max.diff <- eligible[loc.max, , drop = FALSE]

  } else {
    stop("Unknown sg.criterion: ", sg.criterion)
  }

  # Validate subgroup: must meet difference threshold and not be entire population
  if (max.diff$diff < dmin.grf || max.diff$Nsg >= n.max) {
    return(NULL)
  }

  return(max.diff)
}

#' Extract cut information from a policy tree
#'
#' Extracts all split points and variables from a policy tree
#'
#' @param tree Policy tree object
#' @return List with cuts (expressions) and names (unique variables)
#' @keywords internal

extract_tree_cuts <- function(tree) {
  grf_names <- tree$columns
  tnodes <- tree$nodes
  cuts <- character()
  names <- character()

  for (tt in seq_along(tnodes)) {
    node <- tnodes[[tt]]
    if (!node$is_leaf) {
      split_variable_index <- node$split_variable
      split_value <- round(node$split_value, 2)

      variable_name <- grf_names[split_variable_index]
      cut_expression <- paste0(variable_name, " <= ", split_value)

      cuts <- c(cuts, cut_expression)
      names <- c(names, variable_name)
    }
  }

  return(list(
    cuts = cuts,
    names = unique(names)
  ))
}

#' Find the split that leads to a specific leaf node (deprecated)
#'
#' @description
#' \strong{Deprecated.}
#'
#' Returns only the single split immediately above `leaf_node`, rendered as
#' `"var <= value"`.  This is **not** a correct subgroup definition for a leaf
#' below depth 1: it drops the rest of the root-to-leaf path and mis-renders
#' right-turns (which are `>`, not `<=`).  Use the path-based
#' `.grf_build_subgroup_definition()` instead, which
#' `grf.subg.harm.survival()` now calls internally.  Retained (exported) only
#' for backward compatibility; it is no longer used inside the package and
#' will be removed in a future release.
#'
#' @param tree Policy tree object
#' @param leaf_node Integer. Leaf node identifier
#' @return Character string with a single split expression, or NULL.
#' @seealso \code{\link{grf.subg.harm.survival}} for the standard entry point.
#' @examples
#' \dontrun{
#' # Deprecated; grf.subg.harm.survival() builds the full path internally.
#' }
#' @export

find_leaf_split <- function(tree, leaf_node) {
  .Deprecated("grf.subg.harm.survival",
              msg = paste0("'find_leaf_split()' is deprecated: it returns only ",
                           "one split above a leaf and mis-renders right-turns. ",
                           "GRF subgroup definitions are now built from the full ",
                           "root-to-leaf path inside grf.subg.harm.survival()."))
  grf_names <- tree$columns
  tnodes <- tree$nodes

  for (tt in seq_along(tnodes)) {
    node <- tnodes[[tt]]
    if (!node$is_leaf) {
      if (node$left_child == leaf_node || node$right_child == leaf_node) {
        split_variable_index <- node$split_variable
        split_value <- node$split_value
        variable_name <- grf_names[split_variable_index]

        return(paste0(variable_name, " <= ", split_value))
      }
    }
  }

  return(NULL)
}

#' Extract all cuts from fitted trees
#'
#' Consolidates cut information from all fitted policy trees. This is the
#' default behavior that returns cuts from all trees regardless of which
#' tree identified the selected subgroup.
#'
#' @param trees List. Policy trees (indexed by depth)
#' @param maxdepth Integer. Maximum tree depth
#' @return List with cuts and names for each tree and combined
#' @keywords internal

extract_all_tree_cuts <- function(trees, maxdepth) {
  result <- list()
  all_cuts <- character()
  all_names <- character()

  for (depth in 1:maxdepth) {
    if (!is.null(trees[[depth]])) {
      tree_info <- extract_tree_cuts(trees[[depth]])

      # Store tree-specific cuts
      result[[paste0("tree", depth)]] <- tree_info$cuts
      result[[paste0("names", depth)]] <- tree_info$names

      # Accumulate all cuts
      all_cuts <- c(all_cuts, tree_info$cuts)
      all_names <- c(all_names, tree_info$names)
    }
  }

  result$all <- unique(all_cuts)
  result$all_names <- unique(all_names)

  return(result)
}

#' Extract cuts from selected tree only
#'
#' Extracts cut information only from the tree at the specified selected depth.
#' This provides a focused set of cuts from the tree that identified the
#' subgroup meeting the `dmin.grf` criterion, rather than cuts from all trees.
#'
#' @param trees List. Policy trees (indexed by depth)
#' @param selected_depth Integer. Depth of the selected tree (from best_subgroup$depth)
#' @param maxdepth Integer. Maximum tree depth (for populating tree-specific slots)
#' @return List with cuts and names, structured similarly to extract_all_tree_cuts
#'   but with only the selected tree's cuts in the `all` field
#'
#' @details
#' This function is used when `return_selected_cuts_only = TRUE` in
#' `grf.subg.harm.survival()`. It returns:
#' \itemize{
#'   \item `tree1`, `tree2`, `tree3`: Individual tree cuts (still populated for reference)
#'   \item `names1`, `names2`, `names3`: Individual tree variable names
#'   \item `all`: Cuts from the SELECTED tree only (not union of all trees)
#'   \item `all_names`: Variable names from the SELECTED tree only
#'   \item `selected_depth`: The depth that was selected
#' }
#'
#' @examples
#' \dontrun{
#' # When best_subgroup$depth = 2, only tree2 cuts are returned in $all
#' tree_cuts <- extract_selected_tree_cuts(trees, selected_depth = 2, maxdepth = 2)
#' tree_cuts$all
#' # Returns only cuts from depth 2 tree
#' }
#'
#' @keywords internal

extract_selected_tree_cuts <- function(trees, selected_depth, maxdepth) {
  result <- list()

  # Still extract cuts from all trees for reference
  for (depth in 1:maxdepth) {
    if (!is.null(trees[[depth]])) {
      tree_info <- extract_tree_cuts(trees[[depth]])

      # Store tree-specific cuts
      result[[paste0("tree", depth)]] <- tree_info$cuts
      result[[paste0("names", depth)]] <- tree_info$names
    }
  }

  # For the combined 'all' field, only use the selected tree
  if (!is.null(trees[[selected_depth]])) {
    selected_tree_info <- extract_tree_cuts(trees[[selected_depth]])
    result$all <- unique(selected_tree_info$cuts)
    result$all_names <- unique(selected_tree_info$names)
  } else {
    result$all <- character()
    result$all_names <- character()
  }

  # Record which depth was selected

result$selected_depth <- selected_depth

  return(result)
}

#' Assign data to subgroups based on selected node
#'
#' Creates treatment recommendation flags based on identified subgroup
#'
#' @param data Data frame. Original data
#' @param best_subgroup Data frame row. Selected subgroup information
#' @param trees List. Policy trees
#' @param X Matrix. Covariate matrix
#' @return Data frame with added predict.node and treat.recommend columns
#' @keywords internal

assign_subgroup_membership <- function(data, best_subgroup, trees, X) {
  depth <- best_subgroup$depth
  selected_tree <- trees[[depth]]

  # Assign nodes based on selected tree
  data$predict.node <- predict(selected_tree, X, type = "node.id")

  # Create treatment recommendation flag
  # 0 = belongs to identified harm subgroup
  # 1 = belongs to complement (recommend treatment)
  data$treat.recommend <- ifelse(
    data$predict.node == best_subgroup$leaf.node,
    0,
    1
  )

  return(data)
}

#' Create result object for successful subgroup identification
#'
#' Builds comprehensive result object when a subgroup is found
#'
#' @param data Data frame. Original data with subgroup assignments
#' @param best_subgroup Data frame row. Selected subgroup information
#' @param trees List. All fitted policy trees
#' @param tree_cuts List. Cut information from trees
#' @param selected_tree Policy tree. The tree that identified the subgroup
#' @param sg_harm_id Character. Expression defining the subgroup
#' @param values Data frame. All node metrics
#' @param config List. GRF configuration
#' @return List with complete GRF results
#' @keywords internal

create_success_result <- function(data, best_subgroup, trees, tree_cuts,
                                  selected_tree, sg_harm_id, values, config) {

  # Find all subgroups with positive difference
  harm_any <- values[values$diff > 0, ]

  result <- list(
    # Core results
    data = data,
    grf.gsub = best_subgroup,
    sg.harm.id = sg_harm_id,

    # Tree cuts
    tree.cuts = tree_cuts$all,
    tree.names = tree_cuts$all_names,

    # Tree-specific cuts
    tree1.cuts = tree_cuts$tree1,
    tree1.names = tree_cuts$names1,

    # Additional subgroups
    harm.any = harm_any,

    # Tree objects
    tree = selected_tree,
    tree1 = trees[[1]],

    # Configuration
    tau.rmst = config$tau.rmst,
    dmin.grf = config$dmin.grf,
    frac.tau = config$frac.tau,
    maxdepth = config$maxdepth,
    n.min = config$n.min,

    # Track selected depth and cut extraction mode
    selected_depth = best_subgroup$depth,
    return_selected_cuts_only = config$return_selected_cuts_only
  )

  # Add tree2 cuts if maxdepth >= 2
  if (config$maxdepth >= 2) {
    result$tree2.cuts <- tree_cuts$tree2
    result$tree2.names <- tree_cuts$names2
    result$tree2 <- trees[[2]]
  }

  # Add tree3 cuts if maxdepth >= 3
  if (config$maxdepth >= 3) {
    result$tree3.cuts <- tree_cuts$tree3
    result$tree3.names <- tree_cuts$names3
    result$tree3 <- trees[[3]]
  }

  return(result)
}

#' Create result object when no subgroup is found
#'
#' Builds result object for cases where no valid subgroup is identified
#'
#' @param data Data frame. Original data
#' @param values Data frame. Node metrics (may be empty)
#' @param trees List. Fitted policy trees
#' @param config List. GRF configuration
#' @return List with limited GRF results
#' @keywords internal

create_null_result <- function(data, values, trees, config) {

  # Find any subgroups with positive difference (for diagnostic purposes)
  harm_any <- NULL
  if (!is.null(values) && nrow(values) > 0) {
    cand.sgs <- which(values$diff > 0)
    if (length(cand.sgs) > 0) {
      harm_any <- values[cand.sgs, ]
    }
  }

  # Use the first tree as default (or the deepest available)
  selected_tree <- trees[[1]]
  if (config$maxdepth > 1 && !is.null(trees[[config$maxdepth]])) {
    selected_tree <- trees[[config$maxdepth]]
  }

  result <- list(
    data = data,
    grf.gsub = NULL,
    sg.harm.id = NULL,
    tree.cuts = character(),
    tree.names = character(),
    harm.any = harm_any,
    tree = selected_tree,
    tau.rmst = config$tau.rmst,
    dmin.grf = config$dmin.grf,
    frac.tau = config$frac.tau,
    maxdepth = config$maxdepth,
    n.min = config$n.min,
    selected_depth = NULL,
    return_selected_cuts_only = config$return_selected_cuts_only
  )

  # Add tree objects if they exist
  for (i in 1:config$maxdepth) {
    if (!is.null(trees[[i]])) {
      result[[paste0("tree", i)]] <- trees[[i]]
    }
  }

  return(result)
}

#' Print detailed output for debugging
#'
#' Displays detailed information about the GRF analysis
#'
#' @param config List. GRF configuration
#' @param values Data frame. Node metrics
#' @param best_subgroup Data frame row. Selected subgroup (or NULL)
#' @param sg_harm_id Character. Subgroup definition (or NULL)
#' @param tree_cuts List. Cut information
#' @return Called for its side effect of printing to the console. The value
#'   is returned invisibly and is incidental: `tree_cuts$all` when a subgroup,
#'   its definition and `tree_cuts` are all supplied, otherwise `NULL`.
#' @examples
#' \dontrun{
#' # print_grf_details() is called internally by grf.subg.harm.survival().
#' # See grf.subg.harm.survival() for the standard entry point.
#' }
#' @export

print_grf_details <- function(config, values, best_subgroup, sg_harm_id, tree_cuts = NULL) {
  cat("tau, maxdepth =", c(config$tau.rmst, config$maxdepth), "\n")

  if (!is.null(values) && nrow(values) > 0) {
    temp <- values[, c("leaf.node", "control", "depth")]
    print(round(temp, 2))
  }

  if (!is.null(best_subgroup)) {
    temp <- best_subgroup[, c("leaf.node", "control", "depth")]
    cat("\nSelected subgroup:\n")
    print(round(temp, 2))

    if (!is.null(sg_harm_id)) {
      cat("\nGRF subgroup found\n")
      cat("Terminating node at max.diff (sg.harm.id):\n")
      print(sg_harm_id)

      if (!is.null(tree_cuts)) {
        if (isTRUE(config$return_selected_cuts_only)) {
          cat("\nCuts from selected tree (depth =", best_subgroup$depth, "):\n")
        } else {
          cat("\nAll splits (from all trees):\n")
        }
        print(tree_cuts$all)
      }
    }
  } else {
    cat("GRF subgroup NOT found\n")
  }
}

#' Validate input data for GRF analysis
#'
#' Checks that input data meets requirements for GRF analysis
#'
#' @param W Numeric vector. Treatment indicator
#' @param D Numeric vector. Event indicator
#' @param n.min Integer. Minimum subgroup size
#' @return Logical. TRUE if data is valid, FALSE with warning otherwise
#' @examples
#' W <- rep(0:1, each = 50)
#' D <- rbinom(100, 1, 0.6)
#' validate_grf_data(W, D, n.min = 60)
#' @export

validate_grf_data <- function(W, D, n.min) {
  # Check treatment variation
  if (length(unique(W)) < 2) {
    warning("Treatment variable has only one unique value. Cannot identify subgroups.")
    return(FALSE)
  }

  # Check event variation
  if (length(unique(D)) < 2) {
    warning("Event variable has only one unique value. Cannot identify subgroups.")
    return(FALSE)
  }

  # Check minimum sample size per arm
  n_treat <- sum(W == 1)
  n_control <- sum(W == 0)

  if (n_treat < n.min || n_control < n.min) {
    warning(sprintf(
      "Insufficient sample size: treatment=%d, control=%d, required=%d per arm.",
      n_treat, n_control, n.min
    ))
    return(FALSE)
  }

  return(TRUE)
}


#' Code one covariate column as the GRF forest matrix codes it
#'
#' The single definition of how a candidate covariate enters GRF on the GLM
#' path.  Numeric columns pass through unchanged.  A factor or character
#' column whose levels are all numeric strings (for example `"0"`/`"1"`)
#' becomes those values via `as.numeric(as.character())`.  Any other factor or
#' character column becomes integer codes via `as.integer(as.factor())`.
#'
#' `.build_grf_X()` applies it to build the forest's covariate matrix and
#' `.grf_evaluate_subgroup()` applies it before comparing a column with a
#' candidate cut, so a cut is always evaluated on the scale the forest split
#' on.  Before this helper existed the evaluator compared the raw column, and a
#' factor covariate returned `NA` membership for every cut on it.
#'
#' @param x A covariate column.
#' @return `x` unchanged when it is neither a factor nor a character vector;
#'   otherwise a numeric vector (all-numeric levels) or an integer vector
#'   (other levels).
#' @noRd
.grf_code_column <- function(x) {
  if (!is.factor(x) && !is.character(x)) {
    return(x)
  }
  lvls <- if (is.factor(x)) levels(x) else unique(x)
  if (!anyNA(suppressWarnings(as.numeric(lvls)))) {
    # All-numeric levels: preserve the original values.
    as.numeric(as.character(x))
  } else {
    # Non-numeric levels: integer codes.
    as.integer(as.factor(x))
  }
}

Try the forestsearch package in your browser

Any scripts or data that you put into this service are public.

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