R/hc.R

In causalDisco: Tools for Causal Discovery on Observational Data

#' @title HC Algorithm for Causal Discovery
#'
#' @description
#' Run the HC (hill-climbing) algorithm for causal discovery using one of several engines.
#'
#' @param engine Character; which engine to use. Must be one of:
#'   \describe{
#'     \item{\code{"bnlearn"}}{\pkg{bnlearn} R package.}
#'   }
#' @param score Character; name of the scoring function to use.
#' @param ... Additional arguments passed to the chosen engine (e.g. score or algorithm parameters).
#'
#' @details
#' For specific details on the supported scores and parameters for each engine, see:
#' \itemize{
#'  \item [BnlearnSearch] for \pkg{bnlearn}.
#' }
#'
#' Note that this function **always returns a fully directed DAG**.
#' In cases where the data do not provide enough information to identify the direction
#' of some edges (i.e., edges that are part of a Markov equivalence class),
#' the algorithm will choose a direction arbitrarily.
#' Therefore, some edges in the returned DAG may not reflect the true causal direction.
#'
#' @example inst/roxygen-examples/hc-example.R
#'
#' @inheritSection disco_note Recommendation
#' @inheritSection disco_algs_return_doc_dag Returns
#'
# #' @family causal discovery algorithms
# #' @concept cd_algorithms
#' @keywords internal
#' @noRd
hc <- function(
  engine = c("bnlearn"),
  score,
  ...
) {
  engine <- match.arg(engine)

  make_method(
    method_name = "hc",
    engine = engine,
    engine_fns = list(
      bnlearn = function(...) {
        make_runner(engine = "bnlearn", alg = "hc", ...)
      }
    ),
    score = score,
    graph_class = "PDAG",
    ...
  )
}