Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Changes to documentation as a result of review #73

Closed
wants to merge 4 commits into from
Closed

Changes to documentation as a result of review #73

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0d776bb
Merge pull request #71 from ropensci/dev
datapumpernickel Nov 17, 2023
c44b45c
Merge pull request #72 from ropensci/dev
datapumpernickel Nov 17, 2023
ef86f66
review updates.
potterzot Dec 9, 2023
88f8428
change partner2 to partner_2.
potterzot Dec 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions R/ct_get_data.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion README.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
19 changes: 12 additions & 7 deletions vignettes/comtradr.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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 `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.

Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit tricky and I can see how it can be misunderstood! I would like to work with you on how I could make this more explicit.

What you did, was this:

comtradr::ct_get_data(reporter = "DEU", 
                      start_date = 2020, 
                      end_date = 2020)

You left the argument without any specification and it goes to the default of world (as specified in the help file, whihc says: 'Partner ISO3 code(s) or NULL. See comtradr::country_codes for possible values. Default: 'World' (all partners as an aggregate).'

However what I MEANT, when I wrote setting it to NULL, was:

``` r
comtradr::ct_get_data(reporter = "DEU", 
                      partner = NULL, 
                      start_date = 2020, 
                      end_date = 2020)

Then, it will actually query all possible values.

I am not saying that you are wrong, but the way you have put it here, also is not correct, because using NULL will actually query all parameters. Not sure how to make the distinction between NULL and just not specifying the argument.

Do you have a suggestion?



### `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

Expand Down