This vignette explains the functions within this package. The idea is to show how this package simplifies obtaining data from (api.tradestatistics.io)[https://api.tradestatistics.io].
To improve the presentation of the tables I shall use
tibble besides tradestatistics.
library(tradestatistics)
library(tibble)Provided that this package obtains data from an API, it is useful to know which tables can be accessed:
as_tibble(ots_tables)
#> # A tibble: 23 × 3
#> table description source
#> <chr> <chr> <chr>
#> 1 countries Countries metadata UN Comtrade (wi…
#> 2 reporters Reporters for a given year UN Comtrade (wi…
#> 3 partners Partners for a given year UN Comtrade (wi…
#> 4 commodities Commodities metadata Open Trade Stat…
#> 5 yrpc Reporter-Partner trade at commodity le… Open Trade Stat…
#> 6 yrpc-parquet Reporter-Partner trade at commodity le… Open Trade Stat…
#> 7 yrpc-imputed Reporter-Partner trade at commodity le… Open Trade Stat…
#> 8 yrpc-imputed-parquet Reporter-Partner trade at commodity le… Open Trade Stat…
#> 9 yrp Reporter-Partner trade at aggregated l… Open Trade Stat…
#> 10 yrp-imputed Reporter-Partner trade at aggregated l… Open Trade Stat…
#> # … with 13 more rowsYou might notice the tables have a pattern. The letters indicate the presence of columns that account for the level of detail in the data:
y: year column.r: reporter columnp: partner columnc: commodity columnThe most aggregated table is yr which basically says how
many dollars each country exports and imports for a given year.
The less aggregated table is yrpc which says how many
dollars of each of the 1,242 commodities from the Harmonized System each
country exports to other countries and imports from other countries.
For the complete detail you can check tradestatistics.io.
The Package Functions section explains that you don’t need to memorize all ISO codes. The functions within this package are designed to match strings (i.e. “United States” or “America”) to valid ISO codes (i.e. “USA”).
Just as a reference, the table with all valid ISO codes can be accessed by running this:
as_tibble(ots_countries)
#> # A tibble: 255 × 6
#> country_iso country_name_english country_fullname_eng… continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 afg Afghanistan Afghanistan 1 Asia
#> 2 are United Arab Emirates United Arab Emirates 1 Asia
#> 3 arm Armenia Armenia 1 Asia
#> 4 aze Azerbaijan Azerbaijan 1 Asia
#> 5 bgd Bangladesh Bangladesh 1 Asia
#> 6 bhr Bahrain Bahrain 1 Asia
#> 7 brn Brunei Darussalam Brunei Darussalam 1 Asia
#> 8 btn Bhutan Bhutan 1 Asia
#> 9 chn China China 1 Asia
#> 10 cyp Cyprus Cyprus 1 Asia
#> # … with 245 more rows, and 1 more variable: eu28_member <int>The Package Functions section explains that you don’t need to memorize all HS codes. The functions within this package are designed to match strings (i.e. “apple”) to valid HS codes (i.e. “0808”).
as_tibble(ots_commodities)
#> # A tibble: 5,304 × 6
#> commodity_code commodity_fullname_e… group_code group_fullname_… section_code
#> <chr> <chr> <chr> <chr> <chr>
#> 1 010121 Horses; live, pure-b… 01 Animals; live 01
#> 2 010129 Horses; live, other … 01 Animals; live 01
#> 3 010130 Asses; live 01 Animals; live 01
#> 4 010190 Mules and hinnies; l… 01 Animals; live 01
#> 5 010221 Cattle; live, pure-b… 01 Animals; live 01
#> 6 010229 Cattle; live, other … 01 Animals; live 01
#> 7 010231 Buffalo; live, pure-… 01 Animals; live 01
#> 8 010239 Buffalo; live, other… 01 Animals; live 01
#> 9 010290 Bovine animals; live… 01 Animals; live 01
#> 10 010310 Swine; live, pure-br… 01 Animals; live 01
#> # … with 5,294 more rows, and 1 more variable: section_fullname_english <chr>This table is provided to be used with
ots_inflation_adjustment().
as_tibble(ots_inflation)
#> # A tibble: 20 × 3
#> from to conversion_factor
#> <int> <int> <dbl>
#> 1 2000 2001 1.03
#> 2 2001 2002 1.02
#> 3 2002 2003 1.02
#> 4 2003 2004 1.03
#> 5 2004 2005 1.03
#> 6 2005 2006 1.03
#> 7 2006 2007 1.03
#> 8 2007 2008 1.04
#> 9 2008 2009 1.00
#> 10 2009 2010 1.02
#> 11 2010 2011 1.03
#> 12 2011 2012 1.02
#> 13 2012 2013 1.01
#> 14 2013 2014 1.02
#> 15 2014 2015 1.01
#> 16 2015 2016 1.01
#> 17 2016 2017 1.02
#> 18 2017 2018 1.02
#> 19 2018 2019 1.02
#> 20 2019 2020 1.01The end user can use this function to find an ISO code by providing a country name. This works by implementing partial search.
Basic examples:
# Single match with no replacement
as_tibble(ots_country_code("Chile"))
#> # A tibble: 1 × 6
#> country_iso country_name_english country_fullname_engl… continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 chl Chile Chile 5 Americas
#> # … with 1 more variable: eu28_member <int>
# Single match with replacement
as_tibble(ots_country_code("America"))
#> # A tibble: 1 × 6
#> country_iso country_name_english country_fullname_engl… continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 usa USA USA, Puerto Rico and … 5 Americas
#> # … with 1 more variable: eu28_member <int>
# Double match with no replacement
as_tibble(ots_country_code("Germany"))
#> # A tibble: 2 × 6
#> country_iso country_name_english country_fullname_… continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 ddr Fmr Dem. Rep. of Germany Fmr Dem. Rep. of … 2 Europe
#> 2 deu Germany Germany (former F… 2 Europe
#> # … with 1 more variable: eu28_member <int>The function ots_country_code() is used by
ots_create_tidy_data() in a way that you can pass
parameters like
ots_create_tidy_data(... reporters = "Chile" ...) and it
will automatically replace your input for a valid ISO in case there is a
match. This will be covered in detail in the Trade Data section.
The end user can find a code or a set of codes by looking for
keywords for commodities or groups. The function
ots_commodity_code() allows to search from the official
commodities and groups in the Harmonized system:
as_tibble(ots_commodity_code(commodity = " ShEEp ", group = " mEaT "))
#> # A tibble: 10 × 6
#> commodity_code commodity_fullname_e… group_code group_fullname_… section_code
#> <chr> <chr> <chr> <chr> <chr>
#> 1 020410 Meat; of sheep, lamb… 02 Meat and edible… 01
#> 2 020421 Meat; of sheep, carc… 02 Meat and edible… 01
#> 3 020422 Meat; of sheep (incl… 02 Meat and edible… 01
#> 4 020423 Meat; of sheep (incl… 02 Meat and edible… 01
#> 5 020430 Meat; of sheep, lamb… 02 Meat and edible… 01
#> 6 020441 Meat; of sheep, carc… 02 Meat and edible… 01
#> 7 020442 Meat; of sheep (incl… 02 Meat and edible… 01
#> 8 020443 Meat; of sheep (incl… 02 Meat and edible… 01
#> 9 020680 Offal, edible; of sh… 02 Meat and edible… 01
#> 10 020690 Offal, edible; of sh… 02 Meat and edible… 01
#> # … with 1 more variable: section_fullname_english <chr>This function downloads data for a single year and needs (at least) some filter parameters according to the query type.
Here we cover aggregated tables to describe the usage. Note: here you
may skip the use_localhost = FALSE argument.
If we want Chile-Argentina bilateral trade at community level in 2019:
yrpc <- ots_create_tidy_data(
years = 2019,
reporters = "chl",
partners = "arg",
table = "yrpc",
use_localhost = FALSE
)
as_tibble(yrpc)#> # A tibble: 2,642 × 13
#> year reporter_iso reporter_fullname_english partner_iso partner_fullname_en…
#> <int> <chr> <chr> <chr> <chr>
#> 1 2019 chl Chile arg Argentina
#> 2 2019 chl Chile arg Argentina
#> 3 2019 chl Chile arg Argentina
#> 4 2019 chl Chile arg Argentina
#> 5 2019 chl Chile arg Argentina
#> 6 2019 chl Chile arg Argentina
#> 7 2019 chl Chile arg Argentina
#> 8 2019 chl Chile arg Argentina
#> 9 2019 chl Chile arg Argentina
#> 10 2019 chl Chile arg Argentina
#> # … with 2,632 more rows, and 8 more variables: commodity_code <chr>,
#> # commodity_fullname_english <chr>, group_code <chr>,
#> # group_fullname_english <chr>, section_code <chr>,
#> # section_fullname_english <chr>, trade_value_usd_exp <int>,
#> # trade_value_usd_imp <int>We can pass two years or more, several reporters/partners, and filter by commodities with exact codes or code matching based on keywords:
# Note that here I'm passing Peru and not per which is the ISO code for Peru
# The same applies to Brazil
yrpc2 <- ots_create_tidy_data(
years = 2018:2019,
reporters = c("chl", "Peru", "bol"),
partners = c("arg", "Brazil"),
commodities = c("01", "food"),
table = "yrpc",
use_localhost = FALSE
)The yrpc table returns some fields that deserve an
explanation which can be seen at tradestatistics.io. This example
is interesting because “01” return a set of commodities (all commodities
starting with 01, which is the commodity group “Animals; live”), but
“food” return all commodities with a matching description (“1601”,
“1806”, “1904”, etc.). In addition, not all the requested commodities
are exported from each reporter to each partner, therefore a warning is
returned.
If we want Chile-Argentina bilateral trade at aggregated level in 2018 and 2019:
yrp <- ots_create_tidy_data(
years = 2018:2019,
reporters = c("chl", "per"),
partners = "arg",
table = "yrp",
use_localhost = FALSE
)This table accepts different years, reporters and partners just like
yrpc.
If we want Chilean trade at commodity level in 2019 with respect to commodity “010121” which means “Horses; live, pure-bred breeding animals”:
yrc <- ots_create_tidy_data(
years = 2019,
reporters = "chl",
commodities = "010121",
table = "yrc",
use_localhost = FALSE
)This table accepts different years, reporters and commodity codes
just like yrpc.
All the variables from this table are documented at tradestatistics.io.
If we want the aggregated trade of Chile, Argentina and Peru in 2018 and 2019:
yr <- ots_create_tidy_data(
years = 2018:2019,
reporters = c("chl", "arg", "per"),
table = "yr",
use_localhost = FALSE
)This table accepts different years and reporters just like
yrpc.
All the variables from this table are documented at tradestatistics.io.
If we want all commodities traded in 2019:
yc <- ots_create_tidy_data(
years = 2019,
table = "yc",
use_localhost = FALSE
)If we want the traded values of the commodity “010121” which means “Horses; live, pure-bred breeding animals” in 2019:
yc2 <- ots_create_tidy_data(
years = 2019,
commodities = "010121",
table = "yc",
use_localhost = FALSE
)This table accepts different years just like yrpc.
Taking the yr table from above, we can use
ots_inflation_adjustment() to convert dollars from 2018 and
2019 to dollars of 2000:
inflation <- ots_inflation_adjustment(yr, reference_year = 2000)
as_tibble(inflation)#> # A tibble: 6 × 7
#> year reporter_iso reporter_fullname_english trade_value_usd… trade_value_usd…
#> <int> <chr> <chr> <dbl> <dbl>
#> 1 2018 arg Argentina 42971728466. 45623274684.
#> 2 2018 chl Chile 51953607893. 50823688008.
#> 3 2018 per Peru 32890396012. 29581381333.
#> 4 2019 arg Argentina 44452220357. 33804622262.
#> 5 2019 chl Chile 47483388228. 46831370557.
#> 6 2019 per Peru 31131625690. 28511318484.
#> # … with 2 more variables: conversion_year <dbl>, conversion_factor <dbl>