---
title: "Transition from old comtradr"
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 summarized 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")

# 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"
               )

# 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, echo = FALSE}
v_data_7 <- system.file("extdata", "vignette_data_7.rda", package = "comtradr")
if (!file.exists(v_data_7)) {
  stop("internal vignette data set '~/extdata/vignette_data_7.rda' not found", 
       call. = FALSE)
}
load(v_data_7)
```

```{r, eval = F}
#### 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
``` 

``` {r}
#### 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)
```
