R/anesrake.R

In aaronrudkin/autumn: Fast, Modern, and Tidy-Friendly Iterative Raking

#nolint start
#' Backwards compatibility function call syntax for anesrake
#'
#' This function exists to provide a backwards compatible function syntax for
#' \code{\link[anesrake]{anesrake}} and should not be called for any other
#' reason. Rewriting the request as a \code{\link{harvest}} call is preferable.
#'
#' The arguments \code{iterate}, \code{force1}, and \code{center.baseweights}
#' are not supported. \code{iterate} and \code{center.baseweights} are forced to
#' be TRUE. \code{force1} is ignored and if any target variables do not sum to 1,
#' an error will occur.
#'
#' @param inputter Mapped to \code{\link{harvest}}'s \code{target} argument
#' @param dataframe Mapped to \code{\link{harvest}}'s \code{data} argument
#' @param caseid Ignored
#' @param weightvec Mapped to \code{\link{harvest}}'s \code{start_weights}
#'   argument
#' @param cap Mapped to \code{\link{harvest}}'s \code{max_weight} argument
#' @param verbose Mapped to \code{\link{harvest}}'s \code{verbose} argument
#' @param maxit Mapped to \code{\link{harvest}}'s \code{max_iterations}
#'   argument
#' @param type Mapped to \code{\link{harvest}}'s \code{select_function}
#'   argument
#' @param pctlim Mapped to \code{\link{harvest}}'s
#'   \code{select_params[["pct"]]} argument
#' @param nlim Mapped to \code{\link{harvest}}'s
#'   \code{select_params[["number"]]} argument
#' @param filter Ignored
#' @param choosemethod Mapped to \code{\link{harvest}}'s \code{error_function}
#'   argument
#' @param iterate Ignored, \code{\link{harvest}}'s functionality is equivalent
#'   to \code{iterate = TRUE}
#' @param convcrit Mapped to \code{\link{harvest}}'s
#'   \code{convergence[["pct"]]} argument
#' @param force1 Ignored, \code{\link{harvest}}'s functionality is equivalent
#'   to \code{force1 = TRUE}
#' @param center.baseweights Ignored, \code{\link{harvest}}'s functionality is
#'   equivalent to \code{iterate = TRUE}
#'
#' @return A list containing one item, a named vector weightvec which contains
#'   the weights generated by \code{\link{harvest}}. Other elements of
#'   \code{\link[anesrake]{anesrake}} returns are not supported.
#'
#' @examples
#' \dontrun{
#' # Load autumn: this will mask anesrake's anesrake function with autumn's
#' library(autumn)
#'
#' # Argument order and names are the same as anesrake; but caseid is no longer
#' # required and the increased flexibility for data and target arguments from
#' # `harvest()` are supported.
#' anesrake(inputter = ns_target, dataframe = respondent_data)
#'
#' # Most anesrake arguments supported
#' anesrake(ns_target, respondent_data, type = "nlim", choosemethod = "max")
#' }
#' @export
anesrake = function(inputter, dataframe, caseid = NULL, weightvec = NULL,
                    cap = 5, verbose = FALSE, maxit = 1000,
                    type = "pctlim", pctlim = 5,
                    nlim = 5, filter = NULL, choosemethod = "total",
                    iterate = NULL, convcrit = 0.01, force1 = NULL,
                    center.baseweights = NULL) {
  # autumn ignores the following parameters:
  # caseid, filter, iterate, force1, center.baseweights
  if(length(c(iterate, force1, center.baseweights))) {
    message("Note: When using `autumn::anesrake` for pass-through of existing ",
            "`anesrake::anesrake` calls, please note that the arguments ",
            "'iterate' and 'center.baseweights' are forced to be TRUE. ",
            "'force1' is ignored because all raking variables must sum to 1. ",
            "If any variables do not sum to 1, an error will occur.")

  }

  # Handle some of the basic options.
  if(is.null(weightvec)) weightvec = 1
  if(pctlim > 1) pctlim = pctlim / 100
  if(!is.null(filter) && length(filter) == nrow(dataframe)) {
    dataframe = dataframe[filter == 1, ]
    if(!is.null(weightvec)) {
      weightvec = weightvec[filter == 1]
    }
  } else if(!is.null(filter)) {
    stop("Supplied 'filter' argument does not match 'dataframe' row count.")
  }

  weightvec =
    harvest(
      data = dataframe,
      target = inputter,
      start_weights = weightvec,
      max_weight = cap,
      max_iterations = maxit,
      select_params = c(pct = pctlim, number = nlim),
      convergence = c(pct = convcrit, absolute = 0),
      select_function = type,
      error_function = choosemethod,
      verbose = verbose,
      attach_weights = FALSE
    )

  if(!is.null(caseid)) {
    if(length(caseid) != length(weightvec)) {
      warning("Supplied 'caseid' argument does not match 'data' length. ",
              "Ignoring 'caseid' and returning weights without names.")
    } else {
      names(weightvec) = caseid
    }
  }

  list(weightvec = weightvec)
}
#nolint end