From ef86f662c5891ab04e980fa595d7388a3c042e56 Mon Sep 17 00:00:00 2001 From: Nicholas Potter <477294+potterzot@users.noreply.github.com> Date: Sat, 9 Dec 2023 11:35:44 -0700 Subject: [PATCH 1/2] review updates. --- R/ct_get_data.R | 6 +++--- README.Rmd | 2 +- vignettes/comtradr.Rmd | 19 ++++++++++++------- 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/R/ct_get_data.R b/R/ct_get_data.R index 2a07df0..d96049a 100644 --- a/R/ct_get_data.R +++ b/R/ct_get_data.R @@ -20,15 +20,15 @@ #' @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. Default: 'TOTAL' (sum of all commodities). #' @param flow_direction The direction of trade flows or `NULL`. Possible values: 'import', 'export', 're-import', 're-export', 'all'. Default: 'all'. -#' @param reporter Reporter ISO3 code(s) or `NULL`. See `comtradr::country_codes` 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). +#' @param reporter Reporter ISO3 code(s), `all`, or `NULL`. See `comtradr::country_codes` for possible values. Default: 'all'. +#' @param partner Partner ISO3 code(s), `all`, or `NULL`. See `comtradr::country_codes` for possible values. 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. Format: `yyyy` for yearly, `yyyy-mm` for monthly. Max: 12 years after start date for annual data, one year for monthly data. #' @param primary_token Your primary UN Comtrade API token. Default: stored token from `comtradr::set_primary_comtrade_key`. #' @param process If TRUE, returns a data.frame with results. If FALSE, returns the raw httr2 request. Default: TRUE. #' @param tidy_cols If TRUE, returns tidy column names. 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 '0' (TOTAL). See `ct_get_ref_table(dataset_id = 'mot')` for possible values. +#' @param mode_of_transport Mode of Transport ID code, default '0' (TOTAL). See `ct_get_ref_table(dataset_id = 'mot')` for possible values. #' @param partner_2 Partner ISO3 code(s) or `NULL`. Default: 'World'. #' @param customs_code Customs code, default 'C00' (TOTAL). See `ct_get_ref_table(dataset_id = 'customs')` for possible values. #' @param update If TRUE, downloads possibly updated reference tables from the UN. Default: FALSE. diff --git a/README.Rmd b/README.Rmd index daa655b..04fbefe 100644 --- a/README.Rmd +++ b/README.Rmd @@ -54,7 +54,7 @@ install.packages("comtradr") ### Authentication 🔐 -As stated above, you need an API token, see the [FAQ](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+User+Guide#NewComtradeUserGuide-UNComtradeAPIManagement) for details on how to obtain the access tokens. +As stated above, you need an API token, see the [FAQ](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+User+Guide#NewComtradeUserGuide-UNComtradeAPIManagement) for details on how to obtain the access tokens. If you are just getting started, typing the "comtradr-v1" into the subscribe field under the Free APIs list is a good place to start. If you are in an interactive session, you can call the following function to save your API token to the environment file for the current session. diff --git a/vignettes/comtradr.Rmd b/vignettes/comtradr.Rmd index 65b945c..336feca 100644 --- a/vignettes/comtradr.Rmd +++ b/vignettes/comtradr.Rmd @@ -42,7 +42,7 @@ library(comtradr) ## Authentication -As stated above, you need an API token, see the [FAQ](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+User+Guide#NewComtradeUserGuide-UNComtradeAPIManagement) for details on how to obtain the access tokens. +As stated above, you need an API token, see the [FAQ](https://unstats.un.org/wiki/display/comtrade/New+Comtrade+User+Guide#NewComtradeUserGuide-UNComtradeAPIManagement) for details on how to obtain the access tokens. If you are just getting started, typing the "comtradr-v1" into the subscribe field under the Free APIs list is a good place to start. If you are in an interactive session, you can call the following function to save your API token to the environment file for the current session. @@ -114,7 +114,7 @@ q <- ct_search(reporters = "USA", freq = "monthly") ``` -Countries passed to parameters `reporters` and `partners` must be spelled as they appear in the official ISO 3 character code convention. +Countries passed to parameters `reporters` and `partners` must be spelled as they appear in the official ISO 3 character code convention. A list of valid codes can be found in `comtradr::country_codes$iso_3`. Search trade related to specific commodities (say, tomatoes). We can query the Comtrade commodity reference table to see all of the different commodity descriptions available for tomatoes. ```{r} @@ -189,7 +189,7 @@ The API also limits the amount of times it can be queried per minute, but we cou In addition to these rate limits, the API imposes some limits on parameter combinations. -* The arguments `reporters`, `partners` do not have an `All` value specified natively anymore, we have implemented it in R for convenience reasons on our side. +* The arguments `reporter`, `partner`, and `partner2` do not have an `All` value specified natively anymore, but we have implemented it as `all` in R for convenience reasons on our side. * For date range the `start_date` and `end_date` must not span more than twelve months or twelve years. There is no more parameter to specify `All` years. * For arg `commodity_codes`, the maximum number of input values is dependent on the maximum length of the request. Hence, if specifying `reporters` or `partners`, this value might be shorter. @@ -323,13 +323,18 @@ Setting `commodity_code` to `NULL` will query all possible commodity values. Thi If `flow_direction` is set to `NULL`, all possible values for trade flow directions are queried. This includes imports, exports, re-imports, and re-exports. -### `reporter` and `partner` +### `reporter` -Using `NULL` for `reporter` or `partner` will query all possible values for reporter and partner countries. This allows you to retrieve trade data for all countries without specifying individual ISO3 codes. +Using `NULL` for `reporter` will query all possible values for reporter countries. This allows you to retrieve trade data for all countries without specifying individual ISO3 codes. -### `mode_of_transport`, `partner_2`, and `customs_code` +### `partner` and `partner_2` -Setting these parameters to `NULL` will query all possible values related to the mode of transport, secondary partner, and customs procedures. This provides a comprehensive view of the data across different transportation modes and customs categories. +Using `NULL` for `partner` will query the aggregate `World` partner. Using `all` will query for all partners. This allows you to retrieve trade data for the world in aggregate or for all countries without specifying individual ISO3 codes. + + +### `mode_of_transport`, and `customs_code` + +Setting these parameters to `NULL` will query the aggregate of all possible values related to the mode of transport and customs procedures. ### Example Usage From 88f84284691335ae7268e0c6c08259add4d8dea0 Mon Sep 17 00:00:00 2001 From: Nicholas Potter <477294+potterzot@users.noreply.github.com> Date: Sat, 9 Dec 2023 11:40:45 -0700 Subject: [PATCH 2/2] change partner2 to partner_2. --- vignettes/comtradr.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vignettes/comtradr.Rmd b/vignettes/comtradr.Rmd index 336feca..3a8a4fe 100644 --- a/vignettes/comtradr.Rmd +++ b/vignettes/comtradr.Rmd @@ -189,7 +189,7 @@ The API also limits the amount of times it can be queried per minute, but we cou In addition to these rate limits, the API imposes some limits on parameter combinations. -* The arguments `reporter`, `partner`, and `partner2` do not have an `All` value specified natively anymore, but we have implemented it as `all` in R for convenience reasons on our side. +* The arguments `reporter`, `partner`, and `partner_2` do not have an `All` value specified natively anymore, but we have implemented it as `all` in R for convenience reasons on our side. * For date range the `start_date` and `end_date` must not span more than twelve months or twelve years. There is no more parameter to specify `All` years. * For arg `commodity_codes`, the maximum number of input values is dependent on the maximum length of the request. Hence, if specifying `reporters` or `partners`, this value might be shorter.