How to use this package

Mauricio Vargas S.

2019-09-18

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:

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

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:

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:

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:

We can pass more than one year and or reporter/partner:

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)

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

If we want Chilean trade at product level in 1962:

If we want Chilean trade at product level in 1962 with respect to product “0101” (Horses, asses, mules and hinnies; live):

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:

Another option is to pass more than one year and/or reporter:

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:

If we want traded values of product “0101” (Horses, asses, mules and hinnies; live) in 1962:

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: