R/mill.R

In iAM-AMR/sawmill: Process Queries from the CEDAR Database

#' @title
#'   The sawmill Pipeline
#'
#' @description
#'   The \code{mill()} runs the sawmill pipeline with useful defaults.
#'
#' @param timber_path
#'   String: a path to a timber file.
#'
#' @param low_cell_threshold
#'   Numeric: the two-by-two (contingency) table cell count at which (or lower)
#'            the Haldane correction (alt: Woolf-Haldane correction,
#'            Haldane-Anscombe correction) should apply.
#'
#' @param low_cell_correction
#'   Numeric: the value of the Haldane correction to apply; must be > 0.
#'
#' @param log_base
#'   Numeric: the logarithmic base to use when calculating the log(Odds Ratio),
#'            and the standard error of the log(Odds Ratio).
#'
#' @export

# To Document






# Come up with descriptors (status) with a pass or fail for each step, add as
# comments for positive and negative
# Positive:
# Negative:
# "URL creation ok: passed validation"
# Create a new branch and push/pull as earlier

mill <- function(timber_path, low_cell_threshold = 0,
                 low_cell_correction = 0.5,
                 log_base = exp(1)) {
  sub_mill(
    timber0 <- read_timber(timber_path = timber_path),
    "Read Timber: import from .CSV or .XLS/x"
  )
  # Neg:  Abort error msg from read_timber.R

  sub_mill(
    timber1 <- debark(timber = timber0),
    "Debark: rename columns."
  )
  # Neg:  Abort error msg from debark.R

  sub_mill(
    timber2 <- check_grain(timber = timber1),
    "Check Grain: detect fields that specify each outcome."
  )

  sub_mill(
    timber4 <- build_table(
      timber = timber2,
      low_cell_correction = low_cell_correction,
      low_cell_threshold = low_cell_threshold
    ),
    "Build Table: complete contingency tables for count and prevalence-based
    outcomes."
  )
  # TO-DO: Add return msgs for status of low cell count and/or null comparison
  # when True?

  sub_mill(
    timber6 <- add_CI(timber = timber4),
    "Add CI: set the confidence level (if not provided)."
  )
  # TO-DO: Add conditional if CI already provided, then skip

  sub_mill(
    timber7 <- build_chairs(
      timber = timber6,
      log_base = log_base
    ),
    "Build Chair: calculate the odds ratio (OR) and the SE(log(OR)) for each
    outcome."
  )
  # TO-DO: Implement a conditional sub-mill to calculate risk ratio or odds
  # ratio depending on the grain type supplied.

  sub_mill(
    timber8 <- build_horse(timber = timber7),
    "Build Horse: calculate the significance of the OR for count and
    prevalence-based outcomes."
  )
  # TO-DO: Implement support for risk ratios

  sub_mill(
    timber9 <- do_MA(
      timber = timber8,
      log_base = log_base,
      cedar_version = cedar_version
    ),
    "Do MA: run any meta-analyses specified by the user."
  )
  # TO-DO: Create a standalone function and implement complete reporting of
  # meta-analysis results (pooled estimates, measures of heterogeneity,
  # Forest plot visualization?)

  sub_mill(
    timber10 <- add_URL(timber = timber9),
    "Add URL: create a URL from identifiers (e.g., DOI)."
  )
  # Neg:   If URL is NA, message("NA: Unable to generate URL.")

  sub_mill(
    timber11 <- add_HTMLink(timber = timber10),
    "Add a HTML Link: create an <a> object from each URL."
  )
  # Neg:   If HTML link is NA, message("NA: Unable to generate HTML link.")

  sub_mill(
    timber12 <- add_ident(timber = timber11, cedar_version = 2),
    "Add an ANA Identifier: add a suggested ID for objects in Analytica."
  )

  sub_mill(
    planks <- reorder_fields(timber = timber12, cedar_version = 2),
    "Reorder Fields: reorder processed timber output columns."
  )

  return(planks)
}