How to use this package

Mauricio Vargas S.

2019-04-21

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_attributes_tables
#> # A tibble: 15 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        Bilateral trade at aggregated lev… Open Trade Statistics     
#> 10 yrc        Bilateral trade at aggregated lev… Open Trade Statistics     
#> 11 yrc_expor… Bilateral trade at aggregated lev… Open Trade Statistics     
#> 12 yrc_impor… Reporter trade at product level (… Open Trade Statistics     
#> 13 yr         Reporter trade at aggregated leve… Open Trade Statistics     
#> 14 yr_short   Reporter trade at aggregated leve… Open Trade Statistics     
#> 15 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

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

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