---
title: "Basic usage"
author: "Mauricio Vargas S."
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Basic usage}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  cache = FALSE,
  collapse = TRUE,
  message = FALSE,
  comment = "#>"
)
```

# Introduction

This vignette explains the functions within this package. The idea is to show how this package simplifies obtaining data from (api.tradestatistics.io)[https://api.tradestatistics.io].

```{r pkgs}
library(tradestatistics)
```

# Package data

## Available tables

Provided that this package obtains data from an API, it is useful to know which tables can be accessed:

```{r tables, eval = T}
ots_tables
```

The ITPD-E table means "International Trade and Production Database for Estimation" and does not contain imputed values.

The ITPD-S table means "International Trade and Production Database for Simulation" and contains imputed values using the gravity model of trade.

The most aggregated tables are `itpde_imp`/`itpds_imp` (for imports, or with `_exp` for exporter) which contains how many dollars each country imports and exports in a year.

The less aggregated tables are `itpde`/`itpds` which detail bilateral trade at industry level in a year.

For the complete detail you can check [tradestatistics.io](https://tradestatistics.io).

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

```{r countries, eval = T}
ots_countries
```

## Sector/industry codes

The functions within this package are designed to match strings (i.e. "agriculture") to sector/industry codes.

```{r commodities, eval = T}
ots_sectors

ots_industries
```

# Package functions

## Country code

The end user can use this function to find a dynamic ISO-3 code by providing a country name. This works by implementing partial search.

Basic examples:
```{r country_code}
# Single match with no replacement
ots_country_code("Chile")

# Single match with replacement
ots_country_code("America")

# Double match with no replacement
ots_country_code("Germany")
```

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(... importers = "Chile" ...)` and it will automatically replace your input for a
valid code in case there is a match. This will be covered in detail in the Trade Data section.

## Sector/industry code

The end user can find a code or a set of codes by looking for keywords for commodities or groups. The function
`ots_commodity_code()` allows to search from the official commodities and groups in the Harmonized system:
```{r commodity_code2}
ots_sector_code(" AgriCulture ")
ots_industry_code("  CeReaLS")
```

## Trade data

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

Here we cover aggregated tables to describe the usage.

### Bilateral trade (aggregated)

If we want Chile-Argentina bilateral trade at community level in 2019:

```{r aggregate1, eval = F}
ots_create_tidy_data(
  years = 2019,
  importers = "chl",
  exporters = "arg",
  table = "itpde_imp_exp"
)
```

We can pass two years or more, several reporters/partners, and filter by commodities with exact codes or code
matching based on keywords:

```{r aggregate2, eval = F}
ots_create_tidy_data(
  years = 2018:2019,
  importers = c("chl", "Peru", "col"),
  exporters = c("arg", "Brazil"),
  table = "itpde_imp_exp"
)
```

### Bilateral trade (sector)

```{r sector1, eval = F}
ots_create_tidy_data(
  years = 2018:2019,
  importers = c("chl", "Peru", "col"),
  exporters = c("arg", "Brazil"),
  table = "itpde_imp_exp_sec"
)
```

### Aggregate trade (industry)

```{r industry1, eval = F}
ots_create_tidy_data(
  years = 2018:2019,
  importers = c("chl", "Peru", "col"),
  exporters = c("arg", "Brazil"),
  table = "itpde_ind"
)
```