How to use this package

Mauricio Vargas S.

2019-12-04

Package data

Available tables

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 Statistics

Country codes

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:

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>

Product codes and communities

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 rows

Inflation data

This 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 rows

Package functions

Country code

The 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.

Product code

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>           wine

Trade data

This function downloads data for a single year and needs (at least) some filter parameters according to the query type.

Bilateral trade at product level (Year - Reporter - Partner - Product Code)

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 ID
  • group_name: English name corresponding to group_id
  • export_value_usd: Exports measured in nominal United States Dollars (USD)
  • import_value_usd: Imports measured in nominal United States Dollars (USD)

Bilateral trade at aggregated level (Year - Reporter - Partner)

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.

Reporter trade at product level (Year - Reporter - Product Code)

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.

Reporter trade at aggregated level (Year - Reporter)

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).

Product trade at aggregated level (Year - Product Code)

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).

Inflation adjustment

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>