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: 16 × 3
#> table description source
#> <chr> <chr> <chr>
#> 1 commodities Commodities metadata (HS codes, 6 digits long) UN Co…
#> 2 commodities_short Commodities metadata (HS codes, 4 digits long) UN Co…
#> 3 countries Countries metadata UN Co…
#> 4 distances Distance between countries, alongside continuity, c… CEPII…
#> 5 partners Partners for a given year UN Co…
#> 6 reporters Reporters for a given year UN Co…
#> 7 sections Sections metadata (HS codes) UN Co…
#> 8 sections_colors Colors for sections (i.e. useful to visualize data) Open …
#> 9 rtas Regional Trade Agreements per pair of countries and… Desig…
#> 10 tariffs Most Favoured Nation tarrifs (Year, Reporter and Co… World…
#> 11 years Minimum and maximum years with available data Open …
#> 12 yc Commodity trade at aggregated level (Year and Commo… Open …
#> 13 yr Reporter trade at aggregated level (Year and Report… Open …
#> 14 yrc Reporter trade at commodity level (Year, Reporter a… Open …
#> 15 yrp Reporter-Partner trade at aggregated level (Year, R… Open …
#> 16 yrpc Reporter-Partner trade at commodity level (Year, Re… Open …You 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: 264 × 5
#> country_iso country_name_english country_fullname_english continent…¹ conti…²
#> <chr> <chr> <chr> <int> <chr>
#> 1 dza Algeria Algeria 3 Africa
#> 2 ago Angola Angola 3 Africa
#> 3 ben Benin Benin 3 Africa
#> 4 bwa Botswana Botswana 3 Africa
#> 5 bfa Burkina Faso Burkina Faso 3 Africa
#> 6 bdi Burundi Burundi 3 Africa
#> 7 cmr Cameroon Cameroon 3 Africa
#> 8 cpv Cape Verde Cape Verde 3 Africa
#> 9 caf Central African Rep. Central African Rep. 3 Africa
#> 10 tcd Chad Chad 3 Africa
#> # … with 254 more rows, and abbreviated variable names ¹continent_id,
#> # ²continent_name_englishThe 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 × 4
#> commodity_code commodity_fullname_english secti…¹ secti…²
#> <chr> <chr> <chr> <chr>
#> 1 010121 Horses; live, pure-bred breeding animals 01 Live a…
#> 2 010129 Horses; live, other than pure-bred breeding a… 01 Live a…
#> 3 010130 Asses; live 01 Live a…
#> 4 010190 Mules and hinnies; live 01 Live a…
#> 5 010221 Cattle; live, pure-bred breeding animals 01 Live a…
#> 6 010229 Cattle; live, other than pure-bred breeding a… 01 Live a…
#> 7 010231 Buffalo; live, pure-bred breeding animals 01 Live a…
#> 8 010239 Buffalo; live, other than pure-bred breeding … 01 Live a…
#> 9 010290 Bovine animals; live, other than cattle and b… 01 Live a…
#> 10 010310 Swine; live, pure-bred breeding animals 01 Live a…
#> # … with 5,294 more rows, and abbreviated variable names ¹section_code,
#> # ²section_fullname_englishThis table is provided to be used with
ots_gdp_deflator_adjustment().
as_tibble(ots_gdp_deflator)
#> # A tibble: 4,084 × 4
#> country_iso from to gdp_deflator
#> <chr> <int> <int> <dbl>
#> 1 abw 2000 2001 1.06
#> 2 abw 2001 2002 1.05
#> 3 abw 2002 2003 1.02
#> 4 abw 2003 2004 1.02
#> 5 abw 2004 2005 1.03
#> 6 abw 2005 2006 1.03
#> 7 abw 2006 2007 1.06
#> 8 abw 2007 2008 1.05
#> 9 abw 2008 2009 1.02
#> 10 abw 2009 2010 0.993
#> # … with 4,074 more rowsThe 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 × 5
#> country_iso country_name_english country_fullname_english continent_id conti…¹
#> <chr> <chr> <chr> <int> <chr>
#> 1 chl Chile Chile 5 Americ…
#> # … with abbreviated variable name ¹continent_name_english
# Single match with replacement
as_tibble(ots_country_code("America"))
#> # A tibble: 1 × 5
#> country_iso country_name_english country_fullname_english conti…¹ conti…²
#> <chr> <chr> <chr> <int> <chr>
#> 1 usa USA USA, Puerto Rico and US Virg… 5 Americ…
#> # … with abbreviated variable names ¹continent_id, ²continent_name_english
# Double match with no replacement
as_tibble(ots_country_code("Germany"))
#> # A tibble: 1 × 5
#> country_iso country_name_english country_fullname_english conti…¹ conti…²
#> <chr> <chr> <chr> <int> <chr>
#> 1 deu Germany Germany (former Federal Repu… 2 Europe
#> # … with abbreviated variable names ¹continent_id, ²continent_name_englishThe 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 ", section = " mEaT "))
#> # A tibble: 0 × 4
#> # … with 4 variables: commodity_code <chr>, commodity_fullname_english <chr>,
#> # section_code <chr>, 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.
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"
)
as_tibble(yrpc)#> # A tibble: 2,245 × 11
#> year repor…¹ repor…² partn…³ partn…⁴ commo…⁵ commo…⁶ secti…⁷ secti…⁸ trade…⁹
#> <int> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <dbl>
#> 1 2019 chl Chile arg Argent… 010121 Horses… 01 Live a… 1.35e5
#> 2 2019 chl Chile arg Argent… 010129 Horses… 01 Live a… 1.79e6
#> 3 2019 chl Chile arg Argent… 020130 Meat; … 01 Live a… 1.79e8
#> 4 2019 chl Chile arg Argent… 020230 Meat; … 01 Live a… 7.21e5
#> 5 2019 chl Chile arg Argent… 020610 Offal,… 01 Live a… 2.85e5
#> 6 2019 chl Chile arg Argent… 020712 Meat a… 01 Live a… 1.54e7
#> 7 2019 chl Chile arg Argent… 020714 Meat a… 01 Live a… 1.34e7
#> 8 2019 chl Chile arg Argent… 030111 Fish; … 01 Live a… 7.7 e1
#> 9 2019 chl Chile arg Argent… 030341 Fish; … 01 Live a… 8.7 e1
#> 10 2019 chl Chile arg Argent… 030366 Fish; … 01 Live a… 2.65e2
#> # … with 2,235 more rows, 1 more variable: trade_value_usd_exp <dbl>, and
#> # abbreviated variable names ¹reporter_iso, ²reporter_name, ³partner_iso,
#> # ⁴partner_name, ⁵commodity_code, ⁶commodity_name, ⁷section_code,
#> # ⁸section_name, ⁹trade_value_usd_impWe 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"
)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"
)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"
)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"
)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"
)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"
)This table accepts different years just like yrpc.
Taking the yr table from above, we can use
ots_gdp_deflator_adjustment() to convert dollars from 2018
and 2019 to dollars of 2000:
inflation <- ots_gdp_deflator_adjustment(yr, reference_year = 2000)
as_tibble(inflation)#> # A tibble: 6 × 7
#> year reporter_iso reporter_name trade_value_usd_imp trade_v…¹ conve…² gdp_d…³
#> <int> <chr> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 2018 arg Argentina 46010293496 4.03e10 2000 0.703
#> 2 2018 chl Chile 52171431231 4.75e10 2000 0.703
#> 3 2018 per Peru 30337297220 2.64e10 2000 0.703
#> 4 2019 arg Argentina 33924034436 3.00e10 2000 0.691
#> 5 2019 chl Chile 48087306476 4.46e10 2000 0.691
#> 6 2019 per Peru 29288856549 2.56e10 2000 0.691
#> # … with abbreviated variable names ¹trade_value_usd_exp, ²conversion_year,
#> # ³gdp_deflator