R/options.R

In andybega/icews: Get the ICEWS Event Data

#' Setup ICEWS options
#'
#' Checks for an sets several options like paths to data locations; and provides
#' instructions for the .Rprofile entries needed to persist the settings.
#'
#' @param data_dir Where should the raw TSV data be kept?
#' @param use_db Store events in a SQLite database?
#' @param keep_files keep_files If using a database, retain raw data TSV files?
#' @param r_profile If TRUE, this will write config parameters to a .Renviron file.
#'
#' @details Generally, the most flexible option is to keep both a database and
#'   the raw event files. As of late 2018, the database takes up about 8GB of
#'   space and the raw event files 5GB. The database contains several pre-built
#'   indices, which account for the extra space. Reading the raw data from files
#'   into memory takes about 2 minutes but from then on is more convenient and
#'   quicker for exploratory, interactive work. Queries on the database take
#'   longer, but don't require the initial loading into memory overhead. And
#'   with the right indices, it is possible to further cut down the time for
#'   specific queries.
#'
#'   Either way, I heavily recommend adding the option values to .Rprofile,
#'   to take away the trouble of having to deal with paths manually.
#'
#' @return `unset_icews_opts` silently returns a list of prior option values to
#'   make it possible reset the values if needed. See [get_icews_opts()] and
#'   [set_icews_opts()].
#'
#'   `get_icews_opts` returns on object of class "icews_opts". Essentially a list
#'   containing the option values but with format and print methods.
#'
#' @seealso [set_icews_opts()]
#'
#' @export
#' @md
setup_icews <- function(data_dir, use_db = TRUE, keep_files = FALSE, r_profile = TRUE) {
  if (!dir.exists(data_dir)) {
    stop("Data directory does not exist.")
  }
  if (!use_db %in% c(TRUE, FALSE)) {
    stop("use_db should be TRUE or FALSE")
  }
  if (use_db %in% FALSE & keep_files %in% FALSE) {
    stop("Either 'use_db' or 'keep_files' has to be TRUE, both cannot be FALSE")
  }

  set_icews_opts(data_dir, use_db, keep_files)

  # Create folders as neccessary
  if (use_db & !dir.exists(find_db())) {
    dir.create(dirname(find_db()))
  }
  if ((!use_db | keep_files) & !dir.exists(find_raw())) {
    dir.create(find_raw())
  }

  if(isTRUE(r_profile)) {
    if (!requireNamespace("usethis", quietly = TRUE)) {
      stop("Package \"usethis\" needed for this function to work. Please install it (recommended) or set 'r_environ = FALSE'.",
           call. = FALSE)
    }
    cat("Add these lines to the .Rprofile file:\n\n")
    cat("# ICEWS data location and options\n")
    cat(sprintf("options(icews.data_dir   = \"%s\")\n", data_dir))
    cat(sprintf("options(icews.use_db     = %s)\n", use_db))
    cat(sprintf("options(icews.keep_files = %s)\n", keep_files))
    cat("\n")
    usethis::edit_r_profile()
  }
  cat("Path options are set\n")
  invisible(get_icews_opts())
}

#' Set ICEWS option values
#'
#' @param x Either an object of class "icews_opts" generated by [get_icews_opts()]
#'   or [unset_icews_opts()], or a string for the data directory path.
#' @param ... arguments for other methods
#'
#' @seealso [setup_icews()]
#' @md
#' @keywords internal
set_icews_opts <- function(x, ...) {
  UseMethod("set_icews_opts", x)
}

#' @export
#' @method set_icews_opts default
set_icews_opts.default <- function(x, use_db, keep_files, ...) {
  options(icews.data_dir   = x)
  options(icews.use_db     = use_db)
  options(icews.keep_files = keep_files)
  invisible(NULL)
}

#' @export
#' @method set_icews_opts icews_opts
set_icews_opts.icews_opts <- function(x, ...) {
  set_icews_opts(x[["data_dir"]], x[["use_db"]], x[["keep_files"]])
}

#' @rdname setup_icews
#'
#' @export
#'
#' @examples
#' \dontrun{
#'   # This works:
#'   opts <- unset_icews_opts()
#'   # do some stuff without the path options
#'   set_icews_opts(opts)
#' }
unset_icews_opts <- function() {
  opts <- get_icews_opts()
  options(icews.data_dir   = NULL)
  options(icews.use_db     = NULL)
  options(icews.keep_files = NULL)
  invisible(opts)
}


#' @rdname setup_icews
#'
#' @export
get_icews_opts <- function() {
  out <- list(
    data_dir = getOption("icews.data_dir"),
    use_db   = getOption("icews.use_db"),
    keep_files = getOption("icews.keep_files")
  )
  class(out) <- "icews_opts"
  out
}

#' Format setup use case
#'
#' @param opts List of options generated by [get_icews_opts()]
#'
#' @keywords internal
opts_string <- function(opts) {
  if (is.null(opts$use_db)) {
    return("Options not set, consider running 'setup_icews()'")
  }
  if (isFALSE(opts$use_db)) {
    return("Backend: file-based only\n")
  }
  str <- "Backend: database"
  if (isTRUE(opts$keep_files)) {
    str <- paste0(str, " and files")
  } else {
    str <- paste0(str, " only")
  }
  str
}

#' @export
#' @method format icews_opts
format.icews_opts <- function(x, ...) {
  opts <- x
  str  <- list()
  for (i in seq_along(opts)) {
    str[i] <- paste0(names(opts)[i], ": ", opts[i])
  }
  #str <- paste0(str, collapse = "\n")
  smry <- opts_string(opts)
  unlist(c(smry, str))
}

#' @export
#' @method print icews_opts
print.icews_opts <- function(x, ...) {
   str <- format(x)
   cat(paste0(str, collapse = "\n"))
}