How to use this package

Mauricio Vargas S.

2019-08-27

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               UN Comtrade               
#>  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: 6,373 x 4
#>    product_code product_fullname_english             group_code group_name 
#>    <chr>        <chr>                                <chr>      <chr>      
#>  1 0101         Horses, asses, mules and hinnies; l… 01         Animals; l…
#>  2 010110       Horses, asses, mules and hinnies; l… 01         Animals; l…
#>  3 010190       Horses, asses, mules and hinnies; l… 01         Animals; l…
#>  4 0102         Bovine animals; live                 01         Animals; l…
#>  5 010210       Bovine animals; live, pure-bred bre… 01         Animals; l…
#>  6 010290       Bovine animals; live, other than pu… 01         Animals; l…
#>  7 0103         Swine; live                          01         Animals; l…
#>  8 010310       Swine; live, pure-bred breeding ani… 01         Animals; l…
#>  9 010391       Swine; live, (other than pure-bred … 01         Animals; l…
#> 10 010392       Swine; live, (other than pure-bred … 01         Animals; l…
#> # … with 6,363 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: 6,275 x 4
#>    product_code community_code community_name  community_color
#>    <chr>        <chr>          <chr>           <chr>          
#>  1 0101         01             Animal Products #74c0e2        
#>  2 010110       01             Animal Products #74c0e2        
#>  3 010190       01             Animal Products #74c0e2        
#>  4 0102         01             Animal Products #74c0e2        
#>  5 010210       01             Animal Products #74c0e2        
#>  6 010290       01             Animal Products #74c0e2        
#>  7 0103         01             Animal Products #74c0e2        
#>  8 010310       01             Animal Products #74c0e2        
#>  9 010391       01             Animal Products #74c0e2        
#> 10 010392       01             Animal Products #74c0e2        
#> # … with 6,265 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 1965:

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,1965), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = "0101")
#> # A tibble: 11 x 17
#>     year reporter_iso partner_iso reporter_fullna… partner_fullnam…
#>    <int> <chr>        <chr>       <chr>            <chr>           
#>  1  1962 chl          arg         Chile            Argentina       
#>  2  1965 chl          arg         Chile            Argentina       
#>  3  1962 bol          arg         Bolivia          Argentina       
#>  4  1965 bol          arg         Bolivia          Argentina       
#>  5  1962 per          arg         Peru             Argentina       
#>  6  1965 per          arg         Peru             Argentina       
#>  7  1962 chl          bra         Chile            Brazil          
#>  8  1965 chl          bra         Chile            Brazil          
#>  9  1965 bol          bra         Bolivia          Brazil          
#> 10  1962 per          bra         Peru             Brazil          
#> 11  1965 per          bra         Peru             Brazil          
#> # … with 12 more variables: product_code <chr>, product_code_length <int>,
#> #   product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> #   export_value_usd <int>, import_value_usd <int>,
#> #   export_value_usd_change_1_year <int>,
#> #   export_value_usd_percentage_change_1_year <dbl>,
#> #   import_value_usd_change_1_year <int>,
#> #   import_value_usd_percentage_change_1_year <dbl>, observation <chr>

# Pass a string that will return all matching descriptions and multiple HS codes
ots_create_tidy_data(years = c(1962,1965), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = c("0101", "apple"))
#> # A tibble: 27 x 17
#>     year reporter_iso partner_iso reporter_fullna… partner_fullnam…
#>    <int> <chr>        <chr>       <chr>            <chr>           
#>  1  1962 chl          arg         Chile            Argentina       
#>  2  1965 chl          arg         Chile            Argentina       
#>  3  1962 bol          arg         Bolivia          Argentina       
#>  4  1965 bol          arg         Bolivia          Argentina       
#>  5  1962 per          arg         Peru             Argentina       
#>  6  1965 per          arg         Peru             Argentina       
#>  7  1962 chl          bra         Chile            Brazil          
#>  8  1965 chl          bra         Chile            Brazil          
#>  9  1965 bol          bra         Bolivia          Brazil          
#> 10  1962 per          bra         Peru             Brazil          
#> # … with 17 more rows, and 12 more variables: product_code <chr>,
#> #   product_code_length <int>, product_fullname_english <chr>,
#> #   group_code <chr>, group_name <chr>, export_value_usd <int>,
#> #   import_value_usd <int>, export_value_usd_change_1_year <int>,
#> #   export_value_usd_percentage_change_1_year <dbl>,
#> #   import_value_usd_change_1_year <int>,
#> #   import_value_usd_percentage_change_1_year <dbl>, 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.”)
  • product_code_length: How many digits does product_code contain, this can be useful to filter by depth when using HS codes (HS 6 digits is a more detailed version of HS 4 digits, and therefore you don’t have to sum both or you’ll be counting exports/imports twice)
  • 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)
  • export_value_usd_percentage_change_1_year: Nominal increase/decrease in exports measured as percentage with respect to last year
  • export_value_usd_percentage_change_5_years: Nominal increase/decrease in exports measured as percentage with respect to five years ago
  • export_value_usd_change_1_year: Nominal increase/decrease in exports measured in USD with respect to last year
  • export_value_usd_change_5_years: Nominal increase/decrease in exports measured in USD with respect to five years ago

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

If we want Chile-Argentina bilateral trade at aggregated level in 1965:

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

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 1965:

If we want Chilean trade at product level in 1965 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 1965:

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_4_digits_product_code: 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_4_digits_product_code: The rank of a country given its ECI (e.g. the highest ECI obtains the #1)
  • eci_rank_4_digits_product_code_delta_1_year: How many places a country increased or decreased with respect to last year

Product trade at aggregated level (Year - Product Code)

If we want all products traded in 1965:

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

This table accepts different product codes just like yrpc.

Here some fields deserve an explanation:

  • pci_4_digits_product_code: Product Complexity Index (PCI) which is detailed on Open Trade Statistics Documentation. This index is built by using just four digits product codes.
  • pci_6_digits_product_code: Similar to the previous field but built by using just six digits product codes.
  • pci_rank_4_digits_product_code: The rank of a product given its PCI (e.g. the highest PCI obtains the #1)
  • pci_rank_4_digits_product_code_delta_1_year: How many places a country increased or decreased with respect to last year

Inflation adjustment

Taking Year - Reporter table as an example, we can use ots_inflation_adjustment() to convert dollars from 1965 to dollars of 1970: