---
title: "Introduction to exvatools"
author: 
  - name: Enrique Feás
    affiliation: University of Alcalá and Elcano Royal Institute
date: September, 2024
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to exvatools}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

Half of today's international trade is composed of intermediate goods, so 
statistics of gross exports do not reflect the complexity of globalization.
Trade flows should be expressed in terms of value added, taking advantage of
modern international input-output tables, which show how different sectors in
different countries interact with each other. The problem is that handling 
big input-output tables is complicated and many indicators are not available.
This is where **exvatools** proves useful. Its purpose is double:

* To facilitate the extraction and processing of the most relevant 
  international input tables available today, or the use of custom databases,
  with user-friendly commands.
* To provide tools to analyze value added in exports, including the 
  calculation of decompositions according to different methodologies 
  in the literature.

## International input-output analysis tools

### Installing exvatools

Installing **exvatools** from the CRAN repository follows the usual
procedure:

```{r install, eval=FALSE, echo=TRUE}
install.packages("exvatools")
```

To make **exvatools** available:

```{r library}
library(exvatools)
```

### Using data

**exvatools** produces basic input-output tables from three types of data:

1. Raw data of standard international input-output databases

Raw data can be directly downloaded from the web pages of their respective
institutions. Four sources are currently supported:
  
  * OECD Inter-Country Input-Output (ICIO) tables, on which the OECD's
    Trade in Value Added database (TiVA) is based.
  * World Input Output Database (WIOD) tables.
  * FIGARO EU Input-Output Tables (EU IC-SUIOTs).
  * ADB Multi-Regional Input-Output Tables (ADB MRIO)

The advantage of these databases is threefold: they are widely used in the 
economic literature, they are quite rich in terms of countries and sectors, 
and they are directly downloadable from the web page of their supporting 
institutions, normally as zipped files containing comma-delimited 
files (`.csv`), Excel files (`.xlsx`) or R data files (`.rData`).

For instance, if we want to use **exvatools** with the latest edition of 
the OECD ICIO tables (2023, with data up to 2020), we must first download to
our computer the source file "2016-2020.zip" (95 MB) from the
[ICIO web page](https://www.google.com/search?q=OECD+ICIO+tables).
Then we will use the command `make_wio()`, specifying the edition, 
the year and the folder where the source zip file is saved (just the directory).
For instance, if we had downloaded it in `C:\Users\Username\Documents\R` and
we wanted the year 2020, we would just need to type:

```{r make_wio, eval=FALSE, echo=TRUE}
wio <- make_wio("icio2023", year = 2020, 
                src_dir = "C:/Users/Username/Documents/R")
```

and **exvatools** will take care of the rest: it will extract the `.csv` files
from the zip file and produce the basic input-output matrices.

2. Test datasets included in the package

If we just want to check the features of **exvatools**, there is no need to
download any data. The package includes two sets of fictitious data, one 
replicating an ICIO-type database (`wiotype = "iciotest"`, with Mexico and 
China disaggregated) and another one replicating a WIOD-type database 
(`wiotype = "wiodtest"`).

```{r make_wio_test, message=FALSE}
wio <- make_wio("iciotest")
```

3. Custom data

Alternatively, **exvatools** can use custom data to create basic input-output 
matrices. In this case, we just need as input a numeric matrix (or data frame)
with the intermediate inputs `Z` and the final demand `Yfd`, and a vector with
the names of the countries (names of sectors and final demand components are
optional). The command `make_custom_wio()` will be used in this case.   

```{r make_custom_wio, eval=FALSE}
wio <- make_custom_wio(df, g_names = c("C01", "C02", "C03"))
```

For didactic purposes, we will use here ICIO-type fictitious data made with
`make_wio("iciotest")`.

The contents of the created `wio` object can be checked with `summary()`:

```{r summary_wio}
summary(wio)
```

### Operating with input-output matrices

**exvatools** provides multiple commands that make operating with international
input-output tables extremely easy: thus, we can multiply a diagonal matrix by
an ordinary one with `dmult()`, an ordinary by a diagonal with `multd()`, or 
make a block-by-block Hadamard product of matrices with `hmult()`.

We can also easily obtain a block diagonal matrix with `bkd()`, a block 
off-diagonal matrix with `bkoffd()`, or a diagonal matrix with the sums of all
columns with `diagcs()`, 

Additionally, as we are always operating with named rows and columns with
names of countries and sectors, we have improved commands to consolidate
matrices and provide names, like `rsums()` to sum rows, `csums()` to sum 
columns, `sumnrow()` to sum every nth row of a matrix, `sumncol()` to sum every
nth column, `sumgrows()` to sum groups of rows of a particular size,
`sumgcols()` to do the same with columns, etc.

For instance, let us check that the production `X` is equivalent to the product
of the global Leontief inverse matrix `B` and the final demand `Y`:

```{r BY}
BY <- wio$B %*% wio$Y
```

We can sum the rows and check that it coincides with the production vector:

```{r sum_WBY}
BY <- rsums(BY, "BY")
print(cbind(head(BY, 10), head(wio$X, 10)))
```

In OECD ICIO tables two big industrial countries, China and Mexico, 
are disaggregated into two. Calculations must be done with disaggregated
data, but countries must be later consolidated (e.g., `CN1` and `CN2` must
be converted into `CHN`). This can be done with the command `meld()`.

For instance, to calculate the value added absorbed abroad (`VAX`) we need to 
multiply the value added coefficients matrix `V`-hat (represented here
with `W`) by the global inverse matrix `B` by the final demand matrix `Y`, 
and then exclude the value added absorbed domestically. This can be easily done
with a few commands.

```{r WBY}
# To calculate all value added induced by demand:
VBY <- dmult(wio$W, wio$B) %*% wio$Y
VBY
```

We can see that rows for Mexico and China are disaggregated. We can meld them
with `meld()`:

```{r meld}
VBY <- meld(VBY)
VBY
```

We just want the value added absorbed abroad (sometimes referred to as 
value added exported). For that we need the block off-diagonal matrix of
`VBY`, that we can produce with `bkoffd()`:

```{r bkoffd}
bkoffd(VBY)
```

## Value added in exports

The model we have used allows us to express value added induced by final 
demand, but we can also study how gross exports induce value added, not
only from final exports but also from exports of intermediates. In this case,
we need to consider the effect of the multiple times that intermediate 
products cross international borders, to avoid double counting.

This is why several methods have appeared to calculate full decomposition of
value added in exports, distinguishing what part of value added is *pure*
value added and which one is double counting, and also, within the *pure*
double counting, what part is really exported and what part eventually
returns back to the exporting country ('false' exports).

**exvatools** can then produce key value added indicators (like bilateral value 
added exports or `VAX`) that are not currently available in public databases.

### Alternative decompositions of value added in exports

There are several methodologies in the economic literature, and **exvatools**
includes the most complete ones: Koopman et al. (2014), Wang et al. (2013),
Borin and Mancini (2023) and Miroudot and Ye (2021).

For instance, to  create create a full decomposition of value added 
in exports of Spain using the method of Borin and Mancini (2023), 
using a source-based approach, we would type::

```{r make_exvadec ESP}
exvabm <- make_exvadec(wio, exporter = "ESP", method = "bm_src")
```

The advantage is that, once we have obtained a decomposition, we can play 
with the results in terms of sectors and countries of destination just
using the command `get_exvadec_bkdown()`. For instance, to select the
value added in Spanish exports of services (including construction) 
to the United States, we just have to type: 

```{r bkdown_esp_srvwc_usa}
get_exvadec_bkdown(exvabm, exporter = "ESP", 
                   sector = "SRVWC", importer = "USA")
```

An alternative (although with some methodologically limitations) decomposition
would be that of Wang et al. (2013). In this case, instead of the normal
decomposition, we will use the `"terms"` output. (that shows the 16 terms that
compose the value added in exports):

```{r make_exvadec_wwz}
exvawwz <- make_exvadec(wio, exporter = "all", method = "wwz",
                        output = "terms", quiet = TRUE)
```

Note that here we have selected `export = all`, that produces decompositions 
for all countries (not only a specific one), and we have also used the option 
`quiet = TRUE`, that produces a silent output.

We can check any exporting country, any sector, and any destination country. For
instance, we can produce the decomposition of the value added in US exports to
China for the manufacturing sector:

```{r bkdown_usa_manuf_chn}
get_exvadec_bkdown(exvawwz, exporter = "USA", 
                sector = "MANUF", importer = "CHN")
```

### Direction of value added in exports: origin and destination

We have seen that the foreign content in Spanish exports amounts to USD 2501.78
million. Where does it come from? If we do not need a detailed breakdown of
the value added, but we are interested in knowing the specific geographical and
sector origin of the value added content in exports, we can use the command
`make_exvadir()`: 

```{r make_exvadir, results='hide'}
exvadir <- make_exvadir(wio, exporter = "ESP", va_type = "FC", 
                        flow_type = "EXGR")
```

Please note that the `exvadir` object that we have obtained is different from
the `exvadec` object, in the sense that *'exporters'* in an `exvadir` object
are the different countries and sectors of origin of the value added included
in the exports of the country specified with `make_exvadir()`(in this case, 
Spain). We can better understand this by typing `summary(exvadir)`:

```{r summary exvadir}
summary(exvadir)
```

### Get specific data with custom groups

We can use `get_data()` to summarize the foreign content of Spanish exports,
with a breakdown between EU and Non-EU origin (specifying a few countries)
and also distinguishing between goods (with utilities) and
services. We can also break down the destination of those exports between
EU and non-EU: 

```{r get_data_power}
get_data(exvadir, exporter = c("WLD", "EU27", "FRA",
                               "NONEU27", "USA"),
         sector = c("TOTAL", "GOODSWU", "SRVWC"),
         importer = c("WLD", "EU27", "NONEU27"))
```

On the other hand, the flexibility of `get_data()` allows for the creation of
custom-made groups of countries and/or sectors.

For instance, let's create a group of countries called `LATAM`, with Spain
and Mexico. We would just have to define the variable
in the current environment.

```{r define_aukus}
LATAM <- c("ESP", "MEX")
```

And now we can use it as a normal variable, just introducing it as `"LATAM"` 
(with double quotes). We will use the `wwz` decomposition and
extract the domestic value added in intermediates (`DVA_INT`) from `LATAM` to
`USA`. Note that, if we use custom groups, we need to select the 
option `custom = TRUE` in `get_data()`.

```{r get_data_vax_latam}
get_data(exvawwz, "DVA_INT", exporter = "LATAM", 
         sector = c("TOTAL", "MANUF", "SRVWC"), 
         importer = "USA", custom = TRUE)
```

Let us now see an  example of the exception marker `"x"`, that allows to define
exceptions for countries and for sectors. We can, for instance, calculate
the NAFTA exports, both intra-regional and extra-regional, employing just two
sectors: non-services and services.

```{r get_data_vax_latam_intrarreg}
get_data(exvawwz, "EXGR", exporter = "NAFTA", 
         sector = c("TOTAL", "TOTALxSRVWC", "SRVWC"), 
         importer = c("WLD", "NAFTA", "WLDxNAFTA"), custom = TRUE)
```

### Other useful commands

The flexibility of the commands `make_exvadir()` and `get_data()` allows for
the creation of several ready-made commands in **exvatools**. One is
`get_va_exgr()`, to get a detailed sector and geographical origin and 
destination of value added, i.e., how the inputs of specific sectors in 
specific countries contribute to the value added in exports of a particular 
sector of a particular country. For instance, if we want to check the value 
added in US services incorporated in Spanish exports of manufactures, we
just have to type:

```{r get_va_exgr}
get_va_exgr(wio,geo_orig = "USA", sec_orig = "SRVWC",
            geo_export = "ESP", sec_export = "MANUF")
```

Sometimes we are not only interested in the origin, but also in the country
of final absorption. For that we have `get_va_exgry()`. For instance, if we 
want to know what part of the US value added incorporated in China's exports
of manufactures ends up absorbed back in the US, we can type:

```{r get_va_exgry}
get_va_exgry(wio, geo_orig = "USA", geo_export = "CHN",
             sec_export = "MANUF", geo_fd = "USA")
```

At the beginning we manually calculated the value added induced by final 
demand. There is also a specific command for that in **exvatools** called
`get_va_fd()`. This allows, for instance, the calculation of the Chinese total
value added (or GDP) induced by US final demand for manufactures:

```{r get_va_fd}
get_va_fd(wio, geo_orig = "CHN", sec_orig = "TOTAL",
          geo_fd = "USA", sec_fd = "MANUF")
```

### TiVA useful indicators

Finally, if we want to get a list of common trade indicators (exports, imports,
value added, production) similar to those of the TiVA database, we could just
use `make_exvadec()` with the method `"oecd"` and `output = "tiva"`.

```{r make_exvadec_oecd_tiva, results='hide'}
exvativa <- make_exvadec(wio, exporter = "all", method = "oecd",
                         output = "tiva", quiet = TRUE)
```

And then get the decomposition for Spain:

```{r tiva_esp}
get_exvadec_bkdown(exvativa, exporter = "ESP")
```

## Available sectors and countries in each input-output edition

To check the information about sectors, it suffices to print `info_sec()`:

```{r info_sec}
info_sec("iciotest")
```

To check the information about available countries, the command is `info_geo()`:

```{r info_geo}
info_geo("iciotest")
```

These commands do not require to have a `wio` in the environment, so we can just
check what sectors are available in the OECD's ICIO tables, 2023 edition.
```{r info_sec_2023}
info_sec("icio2023")
```

Additionally, the commands `get_geo_codes()` and `get_sec_codes` provide details
about the components of the different groups. These commands are also directly
applicable for any available input-output table. For instance, for `"wiod2016"`
we would have the following components of EU27:

```{r get_geo_codes_wiod2016}
get_geo_codes("EU27", wiotype = "wiod2016")
```

And for `"icio2023"` we have the following components of the business services
sector:

```{r get_sec_codes_icio2023}
get_sec_codes("BIZSV", wiotype = "icio2023")
```