Merge pull request #106 from pepfar-datim/dev

Release v0.5.1

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: datimutils
 Type: Package
 Title: Utilities for interacting with the DATIM api from R
-Version: 0.5.0
-Date: 2022-07-29
+Version: 0.5.1
+Date: 2022-08-02
 Authors@R: 
     c(
     person("Scott", "Jackson", email = "[email protected]",

NEWS.md

@@ -1,3 +1,9 @@
+# datimutils 0.5.1
+
+## New features
+* Adds `verbose` parameter to all functions which returns entire response. Set to `FALSE` by default.
+* Adds `quiet` parameter to all functions which determines whether URL is printed. Set to `TRUE` by default.
+
 # datimutils 0.5.0
 
 ## New features

R/callDATIMapi.R

@@ -7,12 +7,16 @@
 #' default will not try again
 #' @param timeout how long should a reponse be waited for
 #' @param api_version defaults to current but can pass in version number
+#' @param verbose return raw content with data
+#' @param quiet Echo the URL which is called to the console.
 #' @return Result of DATIM API query returned as named list.
 #'
 api_get <- function(path,
                     d2_session,
                     retry = 1, timeout = 60,
-                    api_version = NULL) {
+                    api_version = NULL,
+                    verbose = FALSE,
+                    quiet = TRUE) {
 
   base_url <- d2_session$base_url
   handle <- d2_session$handle
@@ -76,7 +80,10 @@ api_get <- function(path,
 
   # removes whitespace
   url <- gsub(" ", "", url)
-  print(url)
+  if (!quiet) {
+    print(url)
+  }
+
   # retry api get block, only retries if reponse code not in 400s
   i <- 1
   response_code <- 5
@@ -129,10 +136,16 @@ api_get <- function(path,
   }
 
   # extract text response from api response
-  resp <- jsonlite::fromJSON(httr::content(resp, as = "text"),
+  content <- jsonlite::fromJSON(httr::content(resp, as = "text"),
     simplifyDataFrame = TRUE,
     flatten = TRUE
   )
 
-  return(resp)
+  if (verbose) {
+    return(list("data" = content, "api_responses" = resp))
+  } else {
+    return(content)
+  }
+
+
 }

R/getAnalytics.R

@@ -20,6 +20,8 @@
 #' @param d2_session the d2Session object, default is "d2_default_session",
 #' it will be made upon logining in to datim with loginToDATIM
 #' @param retry retry
+#' @param verbose return raw content with data
+#' @param quiet Echo the URL which is called to the console if TRUE.
 #' @return data frame with the rows of the response
 
 getAnalytics <-  function(...,
@@ -31,7 +33,9 @@ getAnalytics <-  function(...,
                           return_names = FALSE,
                           d2_session = dynGet("d2_default_session", inherits = TRUE),
                           retry = 1,
-                          timeout = 60) {
+                          timeout = 60,
+                          verbose = FALSE,
+                          quiet = TRUE) {
 
   # cap time out at 5 minutes
   if (timeout > 300) {
@@ -78,7 +82,14 @@ getAnalytics <-  function(...,
   resp <- api_get(path = path,
                   d2_session = d2_session,
                   retry = retry,
-                  timeout = timeout)
+                  timeout = timeout,
+                  verbose = verbose,
+                  quiet = quiet)
+
+  if (verbose) {
+    meta_data <- resp$api_responses
+    resp <- resp$data
+  }
 
   if (NROW(resp$rows) == 0) {
     return(NULL)
@@ -103,8 +114,11 @@ getAnalytics <-  function(...,
 
   #change data types to numeric where possible
   resp[, coercions == "NUMBER"] <- sapply(resp[, coercions == "NUMBER"], as.numeric)
-
-  return(resp)
+  if (verbose) {
+    return(list("data" = resp, "api_responses" = meta_data))
+  } else {
+    return(resp)
+  }
 }
 
 

R/getDataValueSets.R

@@ -10,13 +10,17 @@
 #'  with DATIM
 #' @param retry number of times to retry
 #' @param timeout number of seconds to wait during call
+#' @param verbose return raw content with data
+#' @param quiet Echo the URL which is called to the console if TRUE.
 #' @return  Data frame with the data requested
 #'
 getDataValueSets <- function(variable_keys = NULL, #keys,
                              variable_values = NULL, #values,
                              d2_session = dynGet("d2_default_session",
                                                  inherits = TRUE),
-                             retry = 1, timeout = 180) {
+                             retry = 1, timeout = 180,
+                             verbose = FALSE,
+                             quiet = TRUE) {
 
   #Test that the provided variables have their associated values used for
   # munging
@@ -77,10 +81,22 @@ getDataValueSets <- function(variable_keys = NULL, #keys,
       path = path,
       d2_session = d2_session,
       retry = retry,
-      timeout = timeout
+      timeout = timeout,
+      verbose = verbose,
+      quiet = quiet
     )
 
+    if (verbose) {
+      meta_data <- resp$api_responses
+      resp <- resp$data
+    }
+
     #Create Dataframe from api response
     resp <- as.data.frame(resp$dataValues, stringsAsFactors = FALSE)
 
+    if (verbose) {
+      return(list("data" = resp, "api_responses" = meta_data))
+    } else {
+      return(resp)
+    }
 }

R/getMetadata.R

@@ -79,6 +79,8 @@ simplifyStructure <- function(resp) {
 #' it will be made upon logining in to datim with loginToDATIM
 #' @param retry number of times to retry
 #' @param timeout integer - seconds to wait for a response, default = 180
+#' @param verbose return raw content with data
+#' @param quiet Echo the URL which is called to the console if TRUE.
 #' @return the metadata response in json format and flattened
 #'
 
@@ -89,7 +91,9 @@ getMetadata <- function(end_point,
                         d2_session = dynGet("d2_default_session",
                                             inherits = TRUE),
                         retry = 1,
-                        timeout = 180) {
+                        timeout = 180,
+                        verbose = FALSE,
+                        quiet = TRUE) {
   if (!is.character(fields)) {
     stop("The fields argument of getMetadata should be of type character")
   }
@@ -125,9 +129,16 @@ getMetadata <- function(end_point,
   resp <- api_get(
     path = path, d2_session = d2_session, retry = retry,
     timeout = timeout,
-    api_version = NULL
+    api_version = NULL,
+    verbose = verbose,
+    quiet = quiet
   )
 
+  if (verbose) {
+    meta_data <- resp$api_responses
+    resp <- resp$data
+  }
+
    # simplify data structure
   resp <- simplifyStructure(resp)
 
@@ -151,10 +162,18 @@ getMetadata <- function(end_point,
           fixed = TRUE
         )
     )) {
-    return(resp[[1]])
+    if (verbose) {
+      return(list("data" = resp[[1]], "api_responses" = meta_data))
+    } else {
+      return(resp[[1]])
+    }
   }
 
-  return(resp)
+  if (verbose) {
+    return(list("data" = resp, "api_responses" = meta_data))
+  } else {
+    return(resp)
+  }
 }
 
 #' @export