R/fetch_all.R

In fognyc/factorr: Tools for Retrieving Factor Time-Series Hosted on Remote Servers

#' Request factor time-series hosted on remote servers in bulk mode.
#'
#' The function \code{fetch_all} returns the requested \strong{group} of
#' time-series represented by the \emph{meta} handle string argument, which
#' represents a group of \emph{atomic} handles. Each atomic handle must be
#' matched against an internal catalog. The catalog includes valid handles,
#' their associated source url, and other fields required to send a valid query.
#'
#' The \emph{meta} handle string argument maps to a group of valid \emph{atomic}
#' handles representing the requested time-series. Each \emph{atomic} handle is
#' parsed, validated and processed by the function \code{fetch} - see its
#' documentation for more details. In particluar, \emph{atomic} handles are
#' matched and validated against the internal catalog, which encodes and
#' maintains the parameters required to perform each query (request) associated
#' with a particular data set hosted on remote server.
#'
#' The function currently supports three \emph{meta_hdl} parameter values:
#' \itemize{
#' \item \strong{ALL} - fetch all \emph{atomic} handles in the catalog
#' \item \strong{FF} - fetch all French-Fama \emph{atomic} handles in the
#' catalog
#' \item \strong{FRED} - fetch all St. Louis FRED \emph{atomic} handles in the
#' catalog
#' }
#'
#' Note that the group mapping corresponding to each \emph{meta_hdl} parameter
#' value is performed inside the function call \emph{via} a \code{switch}
#' procedure. Call \code{catalog_do(operation = "show")} to see the list of
#' \emph{atomic} handles and their respective source.
#'
#' @param meta_hdl A string \emph{meta} handle, representing the requested
#'   \strong{group} of time-series. The function will stop and generate an error
#'   message if an invalid \emph{meta} handle parameter is passed, or
#'   alternatively if the argument maps to one or multiple invalid \emph{atomic}
#'   handles. See details.
#' @param dest_directory A string representing an existing directory, where all
#'   streams (archive files (e.g. .zip), audit files (.pdf), and uncompressed
#'   files (.txt, .csv)) will be stored. The function will stop and generate an
#'   error message if the directory does not exist. Note that three
#'   sub-directories will be created (if they do not exist): Archives, Audit and
#'   Uncompressed. Parameter ignored if \code{show_mapping_only = T}. See
#'   details.
#' @param quiet Logical (default is FALSE). Sends a tracing message to console
#'   while processing each \emph{atomic} handle in the group represented by the
#'   \emph{meta} handle parameter
#' @param show_mapping_only Logical (default is FALSE). When set to TRUE, the
#'   function will return only the \emph{atomic} handles associated with a
#'   \emph{meta} handle parameter.
#' @return A \emph{list} of \code{tibble} objects containing time stamps (e.g.
#'   date, year-month) and the requested time-series. Each \code{tibble}
#'   corresponds to an \emph{atomic} handle and has three attributes: string
#'   handle (i.e. catalog handle), series frequency and series units.
#'
#' @importFrom magrittr "%>%"
#' @export
#'
fetch_all <- function(meta_hdl = c('ALL', 'FF', 'FRED'),
                      dest_directory = '', quiet = F,
                      show_mapping_only = F) {

  if( !exists('catalog') ){
    stop(stringr::str_glue("Object 'catalog' does not exist."), call. = T)
  }

  meta_hdl <- match.arg(meta_hdl)

  HDL <- switch(meta_hdl,
                FF = c("FF_3F_US_M",
                       "FF_3F_DEV_M",
                       "FF_OP_US_M",
                       "FF_OP_exDiv_US_M"),
                FRED = c("FRED_T10Y_US_D",
                         "FRED_T1Y_US_D",
                         "FRED_Baa_US_D",
                         "FRED_Aaa_US_D",
                         "FRED_T10Y_US_M",
                         "FRED_T1Y_US_M",
                         "FRED_Baa_US_M",
                         "FRED_Aaa_US_M",
                         "FRED_CPI_US"),
                ALL = catalog_do(operation = 'get')$hdl)

  if(show_mapping_only == T){
    return(HDL)
  }

  if(quiet == T) {
    HDL_list <- purrr::map(.x = HDL, .f = function(.){
      fetch(hdl_str = ., dest_dir = dest_directory)
    })
  } else {
    HDL_list <- purrr::map(.x = HDL, .f = function(.){
      cat('Processing...', ., '\n')
      fetch(hdl_str = ., dest_dir = dest_directory)
    })
    cat('Completed', '\n')
  }

  return(HDL_list)
}