implement 'everything' as an alterantive to 'NULL" in documentation, …

…functions, and tests
ropensci · Dec 21, 2023 · c190e89 · c190e89
1 parent c3af057
commit c190e89
Show file tree

Hide file tree

Showing 7 changed files with 145 additions and 75 deletions.
diff --git a/R/ct_check_params.R b/R/ct_check_params.R
@@ -275,7 +275,7 @@ check_cmdCode <-
            update = FALSE,
            verbose = FALSE) {
   # check that commodity_code code is not null
-  if (!is.null(commodity_code)) {
+    if(!any(commodity_code %in% 'everything')){
     commodity_code <- as.character(commodity_code)
 
     # remove any white space from cmd codes provided
@@ -297,6 +297,8 @@ check_cmdCode <-
     } else {
       commodity_code <- paste0(commodity_code, collapse = ',')
     }
+    } else {
+    commodity_code <- NULL
   }
 
   return(commodity_code)
@@ -321,7 +323,7 @@ check_cmdCode <-
 check_reporterCode <- function(reporter, update = FALSE, verbose = FALSE) {
   iso_3 <- id <- group <- NULL
   # check that reporter code is valid
-  if (!is.null(reporter)) {
+  if (!any(reporter %in% 'everything')) {
     reporter <- as.character(reporter)
 
     ## check if valid reporter code length and type
@@ -332,10 +334,10 @@ check_reporterCode <- function(reporter, update = FALSE, verbose = FALSE) {
                        update = update,
                        verbose = verbose)
 
-    ## get multiple values or single values that are not 'all'
-    if (length(reporter) > 1 | !any(reporter == 'all')) {
-      if (any(reporter == 'all')) {
-        rlang::abort('"all" can only be provided as a single argument.')
+    ## get multiple values or single values that are not 'all_countries'
+    if (length(reporter) > 1 | !any(reporter == 'all_countries')) {
+      if (any(reporter == 'all_countries')) {
+        rlang::abort('"all_countries" can only be provided as a single argument.')
       }
       # if one of the reporter codes is not in the list of valid reporter codes
       # send stop signal and list problems
@@ -348,18 +350,20 @@ check_reporterCode <- function(reporter, update = FALSE, verbose = FALSE) {
     }
 
     # create proper ids for reporter Code
-    if (length(reporter) > 1 | !any(reporter == 'all')) {
+    if (length(reporter) > 1 | !any(reporter == 'all_countries')) {
       reporter <- reporter_codes |>
         poorman::filter(iso_3 %in% reporter) |>
         poorman::pull(id) |>
         paste(collapse = ",")
-    } else if (reporter == 'all') {
+    } else if (reporter == 'all_countries') {
       reporter <- reporter_codes |>
         poorman::filter(group == FALSE) |>
         poorman::pull(id) |>
         paste(collapse = ',')
     }
 
+  } else {
+    reporter <- NULL
   }
 
   return(reporter)
@@ -386,17 +390,17 @@ check_partnerCode <- function(partner, update = FALSE, verbose = FALSE) {
   iso_3 <- id <- group <- NULL
 
   # check that partner code is valid
-  if (!is.null(partner)) {
+  if (!any(partner %in% 'everything')) {
     partner <- as.character(partner)
 
     partner_codes <- ct_get_ref_table(dataset_id = 'partner',
                                       update = update, verbose = verbose)
 
 
-    if (length(partner) > 1 | !any(partner == 'all')) {
+    if (length(partner) > 1 | !any(partner == 'all_countries')) {
       partner <- stringr::str_squish(partner)
-      if (any(partner == 'all')) {
-        rlang::abort('"all" can only be provided as a single argument.')
+      if (any(partner == 'all_countries')) {
+        rlang::abort('"all_countries" can only be provided as a single argument.')
       }
       # if one of the partnerCodes is not in the list of valid partnerCodes send stop signal and list problems
       if (!all(partner %in% partner_codes$iso_3)) {
@@ -408,17 +412,19 @@ check_partnerCode <- function(partner, update = FALSE, verbose = FALSE) {
     }
 
     # create proper ids for partner
-    if (length(partner) > 1 | !any(partner == 'all')) {
+    if (length(partner) > 1 | !any(partner == 'all_countries')) {
       partner <- partner_codes |>
         poorman::filter(iso_3 %in% partner) |>
         poorman::pull(id) |>
         paste(collapse = ",")
-    } else if (partner == 'all') {
+    } else if (partner == 'all_countries') {
       partner <- partner_codes |>
         poorman::filter(group == FALSE) |>
         poorman::pull(id) |>
         paste(collapse = ",")
     }
+  } else {
+    partner <- NULL
   }
 
   return(partner)
@@ -445,18 +451,18 @@ check_partner2Code <- function(partner, update = FALSE, verbose = FALSE) {
   iso_3 <- id <- group <- NULL
 
   # check that partner code is valid
-  if (!is.null(partner)) {
+  if (!any(partner %in% 'everything')) {
     partner <- as.character(partner)
 
 
     partner_codes <- ct_get_ref_table(dataset_id = 'partner',
                                       update = update, verbose = verbose)
 
 
-    if (length(partner) > 1 | !any(partner == 'all')) {
+    if (length(partner) > 1 | !any(partner == 'all_countries')) {
       partner <- stringr::str_squish(partner)
-      if (any(partner == 'all')) {
-        rlang::abort('"all" can only be provided as a single argument.')
+      if (any(partner == 'all_countries')) {
+        rlang::abort('"all_countries" can only be provided as a single argument.')
       }
       # if one of the partnerCodes is not in the list of valid partnerCodes send stop signal and list problems
       if (!all(partner %in% partner_codes$iso_3)) {
@@ -468,17 +474,19 @@ check_partner2Code <- function(partner, update = FALSE, verbose = FALSE) {
     }
 
     # create proper ids for partner
-    if (length(partner) > 1 | !any(partner == 'all')) {
+    if (length(partner) > 1 | !any(partner == 'all_countries')) {
       partner <- partner_codes |>
         poorman::filter(iso_3 %in% partner) |>
         poorman::pull(id) |>
         paste(collapse = ",")
-    } else if (partner == 'all') {
+    } else if (partner == 'all_countries') {
       partner <- partner_codes |>
         poorman::filter(group == FALSE) |>
         poorman::pull(id) |>
         paste(collapse = ",")
     }
+  } else {
+    partner <- NULL
   }
 
   return(partner)
@@ -499,7 +507,7 @@ check_motCode <-
            verbose = FALSE) {
     # check that commodity_code code is not null
     id <- text <- NA
-    if (!is.null(mode_of_transport)) {
+    if (!any(mode_of_transport %in% 'everything')) {
       valid_codes <-
         ct_get_ref_table(dataset_id = 'mode_of_transport',
                          update = update,
@@ -536,8 +544,11 @@ check_motCode <-
 
         }
       }
+      mode_of_transport <- mode_of_transport$id
+
+    } else {
+      mode_of_transport <- NULL
     }
-    mode_of_transport <- mode_of_transport$id
 
     return(mode_of_transport)
   }
@@ -552,7 +563,7 @@ check_motCode <-
 #' @noRd
 check_customsCode <- function(customs_code, update = FALSE, verbose = FALSE) {
   # check that commodity_code code is not null
-  if (!is.null(customs_code)) {
+  if (!any(customs_code %in% 'everything')) {
     customs_code <- as.character(customs_code)
 
     # remove any white space from cmd codes provided
@@ -573,6 +584,8 @@ check_customsCode <- function(customs_code, update = FALSE, verbose = FALSE) {
     } else {
       customs_code <- paste0(customs_code, collapse = ',')
     }
+  } else {
+    customs_code <- NULL
   }
 
   return(customs_code)

diff --git a/R/ct_get_data.R b/R/ct_get_data.R
@@ -30,18 +30,22 @@
 #' @param commodity_classification The trade classification scheme.
 #' Possible values for goods: `c('HS','S1','S2','S3','S4','SS','B4','B5')`;
 #' for services: `c('EB02','EB10','EB10S','EB')`. Default: 'HS'.
-#' @param commodity_code The commodity code(s) or `NULL`.
-#' See `comtradr::ct_get_ref_table('HS')` for possible values.
+#' @param commodity_code The commodity code(s) or `everything` for all possible
+#' codes. See `comtradr::ct_get_ref_table('HS')` for possible values.
 #' Default: 'TOTAL' (sum of all commodities).
 #' @param flow_direction The direction of trade flows or `everything`.
 #' Possible values can be found in `ct_get_ref_table('flow_direction')`. These
 #' are implemented case-insensitive, 'import' and 'Import' are equivalent.
 #' Default: c('import','export','re-export','re-import').
-#' @param reporter Reporter ISO3 code(s) or `NULL`.
+#' @param reporter Reporter ISO3 code(s), `everything` or `all_countries`.
 #' See `comtradr::country_codes` or `comtradr::ct_get_ref_table('reporter')`
-#' for possible values. Default: 'all'.
-#' @param partner Partner ISO3 code(s) or `NULL`. See `comtradr::country_codes`
-#' for possible values. Default: 'World' (all partners as an aggregate).
+#' for possible values. `all_countries` returns all countries without aggregates
+#' `everything` returns all possible parameters. Default: 'all_countries'.
+#' @param partner Partner ISO3 code(s), `everything` or `all_countries`.
+#' See `comtradr::country_codes` for possible values.
+#' `all_countries` returns all countries without aggregates
+#' `everything` returns all possible parameters, incl. aggregates like World.
+#' Default: 'World' (all partners as an aggregate).
 #' @param start_date The start date of the query.
 #' Format: `yyyy` for yearly, `yyyy-mm` for monthly.
 #' @param end_date The end date of the query.
@@ -55,14 +59,22 @@
 #' If FALSE, returns raw column names. Default: TRUE.
 #' @param verbose If TRUE, sends status updates to the console.
 #' If FALSE, runs functions quietly. Default: FALSE.
-#' @param mode_of_transport Mode of Transport, default 'TOTAL modes of transport' (TOTAL).
+#' @param mode_of_transport Text code of mode of transport or `everything` for
+#' all possible parameters.
 #' See `ct_get_ref_table(dataset_id = 'mode_of_transport')` for possible values.
-#' @param partner_2 Partner ISO3 code(s) or `NULL`. Default: 'World'.
-#' @param customs_code Customs code, default 'C00' (TOTAL).
+#' Default: 'TOTAL modes of transport' (TOTAL).
+#' @param partner_2 Partner 2 ISO3 code(s), `everything` or `all_countries`.
+#' See `comtradr::country_codes` for possible values.
+#' `all_countries` returns all countries without aggregates
+#' `everything` returns all possible parameters, incl. aggregates like World.
+#' Default: 'World' (all partners as an aggregate).
+#' @param customs_code Customs Code ID or `everything` for all possible
+#' parameters.
 #' See `ct_get_ref_table(dataset_id = 'customs_code')` for possible values.
+#' Default: 'C00' (TOTAL).
 #' @param update If TRUE, downloads possibly updated reference tables
 #' from the UN. Default: FALSE.
-#' @param requests_per_second rate of requests per second executed,
+#' @param requests_per_second Rate of requests per second executed,
 #' usually specified as a fraction, e.g. 10/60 for 10 requests per minute,
 #' see `req_throttle()` for details.
 #' @param extra_params Additional parameters to the API, passed as query
@@ -83,7 +95,7 @@
 #'             verbose = TRUE)
 #'
 #' # Query all commodity codes for China's imports from Germany in 2019
-#' ct_get_data(commodity_code = NULL,
+#' ct_get_data(commodity_code = 'everything',
 #'             reporter = 'CHN',
 #'             partner = 'DEU',
 #'             start_date = '2019',
@@ -92,7 +104,7 @@
 #'
 #' # Query all commodity codes for China's imports from Germany
 #' # from January to June of 2019
-#' ct_get_data(commodity_code = NULL,
+#' ct_get_data(commodity_code = "everything",
 #'             reporter = 'CHN',
 #'             partner = 'DEU',
 #'             start_date = '2019',
@@ -109,7 +121,7 @@ ct_get_data <- function(type = 'goods',
                         commodity_code = 'TOTAL',
                         flow_direction = c('Import','Export',
                                            'Re-export','Re-import'),
-                        reporter = 'all',
+                        reporter = 'all_countries',
                         partner = 'World',
                         start_date = NULL,
                         end_date = NULL,

diff --git a/man/ct_check_params.Rd b/man/ct_check_params.Rd