Provided that this package obtains data from an API, it is useful to know which tables can be accessed:
library(tradestatistics)
#>
#> Welcome to tradestatistics package. If you are going to use this
#> package, it means that you are ok with the usage conditions explained
#> on https://docs.tradestatistics.io/datasets.html#code-of-conduct
#>
#> Commercial purposes are strictly out of the boundaries of what you
#> can do with this data according to UN Comtrade dissemination clauses.
#>
#> Our contents are distributed under Creative Commons
#> Attribution-NonCommercial 4.0 International License.
#>
ots_tables
#> # A tibble: 16 x 3
#> table description source
#> <chr> <chr> <chr>
#> 1 countries Countries metadata UN Comtrade
#> 2 products Product metadata UN Comtrade
#> 3 reporters Reporting countries UN Comtrade
#> 4 communiti~ Product communities Center for International ~
#> 5 product_s~ Product short names The Observatory of Econom~
#> 6 country_r~ Ranking of countries Open Trade Statistics
#> 7 product_r~ Ranking of products Open Trade Statistics
#> 8 yrpc Bilateral trade at product level ~ Open Trade Statistics
#> 9 yrp Reporter trade at aggregated leve~ Open Trade Statistics
#> 10 yrp_short Reporter trade at aggregated leve~ Open Trade Statistics
#> 11 yrc Reporter trade at aggregated leve~ Open Trade Statistics
#> 12 yrc_expor~ Reporter trade at aggregated leve~ Open Trade Statistics
#> 13 yrc_impor~ Reporter trade at aggregated leve~ Open Trade Statistics
#> 14 yr Reporter trade at aggregated leve~ Open Trade Statistics
#> 15 yr_short Reporter trade at aggregated leve~ Open Trade Statistics
#> 16 yc Product trade at aggregated level~ Open Trade StatisticsThe 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:
ots_countries
#> # A tibble: 249 x 6
#> country_iso country_name_en~ country_fullnam~ continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 afg Afghanistan Afghanistan 1 Asia
#> 2 alb Albania Albania 2 Europe
#> 3 dza Algeria Algeria 3 Africa
#> 4 asm American Samoa American Samoa 4 Oceania
#> 5 and Andorra Andorra 2 Europe
#> 6 ago Angola Angola 3 Africa
#> 7 aia Anguilla Anguilla 5 Americas
#> 8 atg Antigua and Bar~ Antigua and Bar~ 5 Americas
#> 9 arg Argentina Argentina 5 Americas
#> 10 arm Armenia Armenia 1 Asia
#> # ... with 239 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”).
ots_products
#> # A tibble: 1,320 x 4
#> product_code product_fullname_english group_code group_name
#> <chr> <chr> <chr> <chr>
#> 1 0101 Horses, asses, mules and hinnies~ 01 Animals; live
#> 2 0102 Bovine animals; live 01 Animals; live
#> 3 0103 Swine; live 01 Animals; live
#> 4 0104 Sheep and goats; live 01 Animals; live
#> 5 0105 Poultry; live, fowls of the spec~ 01 Animals; live
#> 6 0106 Animals, n.e.c. in chapter 01; l~ 01 Animals; live
#> 7 0201 Meat of bovine animals; fresh or~ 02 Meat and edib~
#> 8 0202 Meat of bovine animals; frozen 02 Meat and edib~
#> 9 0203 Meat of swine; fresh, chilled or~ 02 Meat and edib~
#> 10 0204 Meat of sheep or goats; fresh, c~ 02 Meat and edib~
#> # ... with 1,310 more rows
ots_product_shortnames
#> # A tibble: 1,222 x 2
#> product_code product_shortname_english
#> <chr> <chr>
#> 1 0101 Horses
#> 2 0102 Bovine
#> 3 0103 Pigs
#> 4 0104 Sheep and Goats
#> 5 0105 Poultry
#> 6 0106 Other Animals
#> 7 0201 Bovine Meat
#> 8 0202 Frozen Bovine Meat
#> 9 0203 Pig Meat
#> 10 0204 Sheep and Goat Meat
#> # ... with 1,212 more rows
ots_communities
#> # A tibble: 1,222 x 4
#> product_code community_code community_name community_color
#> <chr> <chr> <chr> <chr>
#> 1 0101 01 Animal Products #74c0e2
#> 2 0102 01 Animal Products #74c0e2
#> 3 0103 01 Animal Products #74c0e2
#> 4 0104 01 Animal Products #74c0e2
#> 5 0105 01 Animal Products #74c0e2
#> 6 0106 01 Animal Products #74c0e2
#> 7 0201 01 Animal Products #74c0e2
#> 8 0202 01 Animal Products #74c0e2
#> 9 0203 01 Animal Products #74c0e2
#> 10 0204 01 Animal Products #74c0e2
#> # ... with 1,212 more rowsThis table is provided to be used with ots_inflation_adjustment().
ots_inflation
#> # A tibble: 56 x 3
#> from to conversion_factor
#> <int> <int> <dbl>
#> 1 1962 1963 1.03
#> 2 1963 1964 1.03
#> 3 1964 1965 1.04
#> 4 1965 1966 1.05
#> 5 1966 1967 1.04
#> 6 1967 1968 1.04
#> 7 1968 1969 1.04
#> 8 1969 1970 1.05
#> 9 1970 1971 1.05
#> 10 1971 1972 1.06
#> # ... with 46 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
ots_country_code("Chile")
#> # A tibble: 1 x 6
#> country_iso country_name_en~ country_fullnam~ 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
ots_country_code("America")
#> # A tibble: 1 x 6
#> country_iso country_name_en~ country_fullnam~ continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 usa USA USA, Puerto Ric~ 5 Americas
#> # ... with 1 more variable: eu28_member <int>
# Double match with no replacement
ots_country_code("Germany")
#> # A tibble: 2 x 6
#> country_iso country_name_en~ country_fullnam~ continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 ddr Fmr Dem. Rep. o~ Fmr Dem. Rep. o~ 2 Europe
#> 2 deu Germany Germany (former~ 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 use this function to find a product code by providing a product name. This works by implementing partial string matching:
ots_product_code("wine")
#> # A tibble: 12 x 5
#> product_code product_fullname_en~ group_code group_name type_product
#> <chr> <chr> <chr> <chr> <chr>
#> 1 0103 Swine; live 01 Animals; live wine
#> 2 0203 Meat of swine; fres~ 02 Meat and edib~ wine
#> 3 0206 Edible offal of bov~ 02 Meat and edib~ wine
#> 4 2204 Wine of fresh grape~ 22 Beverages, sp~ wine
#> 5 2205 Vermouth and other ~ 22 Beverages, sp~ wine
#> 6 2307 Wine lees; argol 23 Food industri~ wine
#> 7 5607 Twine, cordage, rop~ 56 Wadding, felt~ wine
#> 8 5608 Twine, cordage or r~ 56 Wadding, felt~ wine
#> 9 5609 Articles of yarn, s~ 56 Wadding, felt~ wine
#> 10 6310 Rags; used or new, ~ 63 Textiles, mad~ wine
#> 11 8435 Presses, crushers a~ 84 Nuclear react~ wine
#> 12 56 Alias for all codes~ <NA> <NA> wineThis function downloads data for a single year and needs (at least) some filter parameters according to the query type.
If we want Chile-Argentina bilateral trade at product level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", partners = "arg")
#> # A tibble: 266 x 11
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1962 chl arg Chile Argentina
#> 3 1962 chl arg Chile Argentina
#> 4 1962 chl arg Chile Argentina
#> 5 1962 chl arg Chile Argentina
#> 6 1962 chl arg Chile Argentina
#> 7 1962 chl arg Chile Argentina
#> 8 1962 chl arg Chile Argentina
#> 9 1962 chl arg Chile Argentina
#> 10 1962 chl arg Chile Argentina
#> # ... with 256 more rows, and 6 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # import_value_usd <int>, export_value_usd <int>
# the same can be obtained specifying yrpc which is the default table
# ots_create_tidy_data(years = 1962, reporters = "chl", partners = "arg", table = "yrpc")We can pass more than one year and or reporter/partner:
# Note that here I'm passing Peru and not per which is the ISO code for Peru
# The same applies to Brazil
ots_create_tidy_data(years = c(1962,1963), reporters = c("chl", "Peru", "bol"), partners = c("arg", "Brazil"))
#> # A tibble: 2,275 x 11
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1962 chl arg Chile Argentina
#> 3 1962 chl arg Chile Argentina
#> 4 1962 chl arg Chile Argentina
#> 5 1962 chl arg Chile Argentina
#> 6 1962 chl arg Chile Argentina
#> 7 1962 chl arg Chile Argentina
#> 8 1962 chl arg Chile Argentina
#> 9 1962 chl arg Chile Argentina
#> 10 1962 chl arg Chile Argentina
#> # ... with 2,265 more rows, and 6 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # import_value_usd <int>, export_value_usd <int>If we want filtering by product, there are different options:
# Pass a specific HS code
ots_create_tidy_data(years = c(1962,1963), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = "0101")
#> # A tibble: 12 x 12
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1963 chl arg Chile Argentina
#> 3 1962 bol arg Bolivia Argentina
#> 4 1963 bol arg Bolivia Argentina
#> 5 1962 per arg Peru Argentina
#> 6 1963 per arg Peru Argentina
#> 7 1962 chl bra Chile Brazil
#> 8 1963 chl bra Chile Brazil
#> 9 1962 bol bra Bolivia Brazil
#> 10 1963 bol bra Bolivia Brazil
#> 11 1962 per bra Peru Brazil
#> 12 1963 per bra Peru Brazil
#> # ... with 7 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>, observation <chr>
# Pass a string that will return all matching descriptions and multiple HS codes
ots_create_tidy_data(years = c(1962,1963), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = c("0101", "apple"))
#> # A tibble: 36 x 12
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1963 chl arg Chile Argentina
#> 3 1962 bol arg Bolivia Argentina
#> 4 1963 bol arg Bolivia Argentina
#> 5 1962 per arg Peru Argentina
#> 6 1963 per arg Peru Argentina
#> 7 1962 chl bra Chile Brazil
#> 8 1963 chl bra Chile Brazil
#> 9 1962 bol bra Bolivia Brazil
#> 10 1963 bol bra Bolivia Brazil
#> # ... with 26 more rows, and 7 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>, observation <chr>yrpc table returns some fields that deserve an explanation:
product_code: HS07 product codes (e.g. according to the table within this package, 0101 stands for “Horses, etc.”)group_code: International categorization of group products defined after product IDgroup_name: English name corresponding to group_idexport_value_usd: Exports measured in nominal United States Dollars (USD)import_value_usd: Imports measured in nominal United States Dollars (USD)If we want Chile-Argentina bilateral trade at aggregated level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", partners = "arg", table = "yrp")
#> # A tibble: 1 x 7
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> # ... with 2 more variables: export_value_usd <int>,
#> # import_value_usd <int>Another option is to pass more than one year, reporter and/or partner:
ots_create_tidy_data(years = 1962:1963, reporters = c("chl", "per"), partners = "arg", table = "yrp")
#> # A tibble: 4 x 7
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1963 chl arg Chile Argentina
#> 3 1962 per arg Peru Argentina
#> 4 1963 per arg Peru Argentina
#> # ... with 2 more variables: export_value_usd <int>,
#> # import_value_usd <int>This table accepts different years, reporters and partners just like yrpc.
If we want Chilean trade at product level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", table = "yrc")
#> # A tibble: 912 x 11
#> year reporter_iso reporter_fullna~ product_code product_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl Chile 9999 Commodities not~
#> 2 1962 chl Chile 9706 Antiques; of an~
#> 3 1962 chl Chile 9705 Collections and~
#> 4 1962 chl Chile 9704 Stamps, postage~
#> 5 1962 chl Chile 9703 Sculptures and ~
#> 6 1962 chl Chile 9701 Paintings, draw~
#> 7 1962 chl Chile 9618 Tailors' dummie~
#> 8 1962 chl Chile 9617 Vacuum flasks a~
#> 9 1962 chl Chile 9616 Scent sprays an~
#> 10 1962 chl Chile 9614 Smoking pipes (~
#> # ... with 902 more rows, and 6 more variables: group_code <chr>,
#> # group_name <chr>, export_value_usd <int>, import_value_usd <int>,
#> # export_rca <dbl>, import_rca <dbl>If we want Chilean trade at product level in 1962 with respect to product “0101” (Horses, asses, mules and hinnies; live):
ots_create_tidy_data(years = 1962, reporters = "chl", products = "0101", table = "yrc")
#> # A tibble: 1 x 11
#> year reporter_iso reporter_fullna~ product_code product_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl Chile 0101 Horses, asses, ~
#> # ... with 6 more variables: group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>, export_rca <dbl>,
#> # import_rca <dbl>This table accepts different years, reporters and product codes just like yrpc.
Here the export_rca and import_rca fields contain the Revealed Comparative Advantage (RCA) of an exported product with respect to all the products with the same number of digits. The definition of RCA is detailed on Open Trade Statistics Documentation.
If we want Chilean trade at aggregated level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", table = "yr")
#> # A tibble: 1 x 15
#> year reporter_iso reporter_fullna~ export_value_usd import_value_usd
#> <int> <chr> <chr> <int> <int>
#> 1 1962 chl Chile 686689403 695823377
#> # ... with 10 more variables: eci_fitness_method <dbl>,
#> # eci_rank_fitness_method <int>, eci_reflections_method <dbl>,
#> # eci_rank_reflections_method <int>, eci_eigenvalues_method <dbl>,
#> # eci_rank_eigenvalues_method <int>, top_export_product_code <chr>,
#> # top_export_trade_value_usd <int>, top_import_product_code <chr>,
#> # top_import_trade_value_usd <int>Another option is to pass more than one year and/or reporter:
ots_create_tidy_data(years = 1962:1963, reporters = c("chl", "arg", "per"), table = "yr")
#> # A tibble: 6 x 15
#> year reporter_iso reporter_fullna~ export_value_usd import_value_usd
#> <int> <chr> <chr> <int> <int>
#> 1 1962 chl Chile 686689403 695823377
#> 2 1963 chl Chile 684739946 771099193
#> 3 1962 arg Argentina 1497724584 1789906161
#> 4 1963 arg Argentina 1689338136 1283218008
#> 5 1962 per Peru 676343986 601437849
#> 6 1963 per Peru 785459639 651334910
#> # ... with 10 more variables: eci_fitness_method <dbl>,
#> # eci_rank_fitness_method <int>, eci_reflections_method <dbl>,
#> # eci_rank_reflections_method <int>, eci_eigenvalues_method <dbl>,
#> # eci_rank_eigenvalues_method <int>, top_export_product_code <chr>,
#> # top_export_trade_value_usd <int>, top_import_product_code <chr>,
#> # top_import_trade_value_usd <int>This table accepts different years and reporters just like yrpc.
Here some fields deserve an explanation:
eci_*_method: Economic Complexity Index (ECI) which is detailed on Open Trade Statistics Documentation. This index is built by using just four digits product codes.eci_rank_*_method: The rank of a country given its ECI (e.g. the highest ECI obtains the #1).If we want all products traded in 1962:
ots_create_tidy_data(years = 1962, table = "yc")
#> # A tibble: 991 x 17
#> year product_code product_fullnam~ group_code group_name
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 9999 Commodities not~ 99 Commoditi~
#> 2 1962 9706 Antiques; of an~ 97 Works of ~
#> 3 1962 9705 Collections and~ 97 Works of ~
#> 4 1962 9704 Stamps, postage~ 97 Works of ~
#> 5 1962 9703 Sculptures and ~ 97 Works of ~
#> 6 1962 9702 Engravings, pri~ 97 Works of ~
#> 7 1962 9701 Paintings, draw~ 97 Works of ~
#> 8 1962 9618 Tailors' dummie~ 96 Miscellan~
#> 9 1962 9617 Vacuum flasks a~ 96 Miscellan~
#> 10 1962 9616 Scent sprays an~ 96 Miscellan~
#> # ... with 981 more rows, and 12 more variables: export_value_usd <dbl>,
#> # import_value_usd <dbl>, pci_fitness_method <dbl>,
#> # pci_rank_fitness_method <int>, pci_reflections_method <dbl>,
#> # pci_rank_reflections_method <int>, pci_eigenvalues_method <dbl>,
#> # pci_rank_eigenvalues_method <int>, top_exporter_iso <chr>,
#> # top_exporter_trade_value_usd <int>, top_importer_iso <chr>,
#> # top_importer_trade_value_usd <int>If we want traded values of product “0101” (Horses, asses, mules and hinnies; live) in 1962:
ots_create_tidy_data(years = 1962, products = "0101", table = "yc")
#> # A tibble: 1 x 17
#> year product_code product_fullnam~ group_code group_name
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 0101 Horses, asses, ~ 01 Animals; ~
#> # ... with 12 more variables: export_value_usd <int>,
#> # import_value_usd <int>, pci_fitness_method <dbl>,
#> # pci_rank_fitness_method <int>, pci_reflections_method <dbl>,
#> # pci_rank_reflections_method <int>, pci_eigenvalues_method <dbl>,
#> # pci_rank_eigenvalues_method <int>, top_exporter_iso <chr>,
#> # top_exporter_trade_value_usd <int>, top_importer_iso <chr>,
#> # top_importer_trade_value_usd <int>This table accepts different product codes just like yrpc.
Here some fields deserve an explanation:
pci_*_method: Product Complexity Index (PCI) which is detailed on Open Trade Statistics Documentation.pci_rank_*_method: The rank of a product given its PCI (e.g. the highest PCI obtains the #1).Taking Year - Reporter table as an example, we can use ots_inflation_adjustment() to convert dollars from 1962 to dollars of 1970:
library(magrittr)
ots_create_tidy_data(years = 1962, reporters = "chl", table = "yr") %>%
ots_inflation_adjustment(reference_year = 1970)
#> # A tibble: 1 x 17
#> year reporter_iso reporter_fullna~ export_value_usd import_value_usd
#> <int> <chr> <chr> <dbl> <dbl>
#> 1 1962 chl Chile 940315695. 952823270.
#> # ... with 12 more variables: eci_fitness_method <dbl>,
#> # eci_rank_fitness_method <int>, eci_reflections_method <dbl>,
#> # eci_rank_reflections_method <int>, eci_eigenvalues_method <dbl>,
#> # eci_rank_eigenvalues_method <int>, top_export_product_code <chr>,
#> # top_export_trade_value_usd <int>, top_import_product_code <chr>,
#> # top_import_trade_value_usd <int>, conversion_year <dbl>,
#> # conversion_factor <dbl>