added vignette on transitioning from old comtradr

vignettes/transition.Rmd

@@ -0,0 +1,201 @@
+---
+title: "Transition"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{transition}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+
+## Transitioning from the old API to the new API 🔄
+
+With the update of the Comtrade API by the United Nations, this package has
+undergone a comprehensive rewrite. Most functions that were available have been
+deprecated and there are breaking changes also in the names of arguments and 
+possible parameter values. 
+
+With the below examples, we hope to make the transition a little easier. Most 
+of the design principles of the package have remained similar. 
+
+The most important changes can be summarised in that the package: 
+- extensively checks parameters for validity before submitting 
+them
+- allows iso3 standardized country codes as inputs
+- queries the new parameters the UN added, such as a mode of transport.
+
+You will see that most other things have stayed more or less the same and the 
+transition will be a breeze! 💨
+
+### The basics 📊
+
+
+```{r, eval = FALSE}
+#### Previously
+q <- ct_search(reporters = "USA", 
+               partners = c("Germany", "France", "Japan", "Mexico"), 
+               trade_direction = "imports")
+
+#### Now
+q <- ct_get_data(reporter = "USA", 
+               partner = c("DEU", "FRA", "JPN", "MEX"), 
+               flow_direction = "import",
+               start_date = 2020,
+               end_date = 2023)
+```
+
+### The time parameter
+
+```{r, eval = FALSE}
+#### Previously
+# Get all monthly data for a single year (API max of 12 months per call).
+q <- ct_search(reporters = "USA", 
+               partners = c("Germany", "France", "Japan", "Mexico"), 
+               trade_direction = "imports", 
+               start_date = 2012, 
+               end_date = 2012, 
+               freq = "monthly")
+
+# Get monthly data for a specific span of months (API max of five months per call).
+q <- ct_search(reporters = "USA", 
+               partners = c("Germany", "France", "Japan", "Mexico"), 
+               trade_direction = "imports", 
+               start_date = "2012-03", 
+               end_date = "2012-07", 
+               freq = "monthly")
+
+
+#### Now
+# Get all monthly data for a single year (API max of 12 months per call).
+q <- ct_get_data(reporter = "USA", 
+               partner = c("DEU", "FRA", "JPN", "MEX"), 
+               flow_direction = "import",
+               start_date = 2012, 
+               end_date = 2012, 
+               frequency = "M"
+               )
+
+# Get monthly data for a specific span of months (API max of five months per call).
+q <- ct_get_data(reporter = "USA", 
+               partner = c("DEU", "FRA", "JPN", "MEX"), 
+               flow_direction = "import",
+               start_date = "2012-03", 
+               end_date = "2012-07", 
+               frequency = "M"
+               )
+```
+
+
+
+### Country Names 🌍
+
+#### Previously
+Countries passed to parameters `reporters` and `partners` must be spelled as they appear in the Comtrade country reference table. Function `ct_country_lookup` allows us to query the country reference table.
+```{r, eval = F}
+ct_country_lookup("korea", "reporter")
+ct_country_lookup("bolivia", "partner")
+q <- ct_search(reporters = "Rep. of Korea", 
+               partners = "Bolivia (Plurinational State of)", 
+               trade_direction = "all")
+```
+
+#### Now
+No need to specify the Comtrade country name, just use iso3 codes, as you can extract them from a myriad of other packages, e.g. `countrycodes`, `rnaturalearth` or `giscoR`.
+
+```{r, eval = F}
+
+asia <- countrycode::codelist |> poorman::filter(un.region.name == "Asia") |> poorman::pull(iso3c)
+
+q <- ct_get_data(reporter = asia, 
+               partner = c("DEU", "FRA", "JPN", "MEX"), 
+               flow_direction = "import",
+               start_date = 2012, 
+               end_date = 2012, 
+               frequency = "M"
+               )
+```
+
+### Searching for commodity codes 🚢📦
+
+#### Previously == Now
+
+This has not changed!
+
+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, eval = F}
+ct_commodity_lookup("tomato")
+```
+If we want to search for shipment data on all of the commodity descriptions listed, then we can simply adjust the parameters for `ct_commodity_lookup` so that it will return only the codes, which can then be passed along to `ct_search`.
+```{r, eval = FALSE}
+tomato_codes <- ct_commodity_lookup("tomato", 
+                                    return_code = TRUE, 
+                                    return_char = TRUE)
+```
+
+
+### API search metadata 📑
+
+
+```{r}
+#### Previously
+# The url of the API call.
+attributes(q)$url
+# The date-time of the API call.
+attributes(q)$time_stamp
+# The total duration of the API call, in seconds.
+attributes(q)$req_duration
+
+#### Now
+# The url of the API call.
+attributes(q)$url
+# The date-time of the API call.
+attributes(q)$time
+# The total duration of the API call, in seconds is not returned anymore!
+```
+
+
+
+### Package Data 📦
+
+`comtradr` ships with a few different package data objects, and functions for interacting with and using the package data.
+
+#### Previously
+
+The package data was mostly stored in different databases and had to be queried and updated separately. See below:
+
+```{r, eval = FALSE}
+ct_update_databases()
+
+ct_commodity_db_type()
+```
+
+#### Now
+
+All package data can be referenced from one function, which automatically includes the `update` possibility. 
+
+```{r, eval = F}
+## to get the parameter values for the mode_of_transport argument
+ct_get_ref_table("mode_of_transport")
+
+## to get the parameter values for the partner argument
+ct_get_ref_table("partner")
+
+## to update the parameter reference for the partner argument
+ct_get_ref_table("partner", update = T)
+
+## to get any commodity classification scheme, just pass in the code
+## you would use in commodity_classification
+ct_get_ref_table("HS")
+```
+
+
+
+### "Polished" Column Headers 🎨
+
+Previously there were polished column names, that were handy for plotting, 
+because they were human readable. This is no longer an included functionality.
+
+```{r, eval = F}
+# Apply polished column headers
+q <- ct_use_pretty_cols(q)
+```