---
title: "Trade Intensity, Openness and Diversification with tradeIndices"
author: "Chiranjit Mazumder and Renjini V. R."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Trade Intensity, Openness and Diversification}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

`tradeIndices` calculates frequently used international trade indicators from
numeric vectors. It deliberately separates measurement from data acquisition,
allowing researchers to use UN Comtrade, World Bank, national, or independently
verified data.

```{r}
library(tradeIndices)
```

The numerical data below are illustrative agricultural-trade values and should
not be interpreted as official statistics.

## Trade openness

Trade openness is exports plus imports divided by GDP:

\[
TO_t = 100\frac{X_t+M_t}{GDP_t}.
\]

```{r}
macro <- data.frame(
  year = 2020:2024,
  exports = c(276, 302, 326, 351, 379),
  imports = c(365, 421, 457, 493, 528),
  gdp = c(2667, 3150, 3390, 3570, 3810)
)

macro$openness <- with(
  macro,
  trade_openness(exports, imports, gdp)
)
macro
```

```{r openness-plot, fig.width=6.5, fig.height=4}
plot(
  macro$year, macro$openness,
  type = "o", pch = 16, lwd = 2, col = "#1B5E20",
  xlab = "Year", ylab = "Trade openness (% of GDP)",
  main = "Illustrative trade-openness series"
)
grid()
```

The monetary units cancel, but exports, imports, and GDP must be expressed in
the same unit and price basis.

## Bilateral trade intensity

For reporter country \(i\) and partner \(j\), conventional export intensity is

\[
TII_{ij}=\frac{X_{ij}/X_i}{M_j/M_w}.
\]

```{r}
intensity <- data.frame(
  year = 2020:2024,
  bilateral_exports = c(14, 16, 19, 21, 25),
  reporter_exports = c(180, 195, 210, 225, 245),
  world_exports_to_partner = c(310, 335, 360, 390, 420),
  world_exports = c(4300, 4650, 4920, 5180, 5490)
)

intensity$tii <- with(
  intensity,
  trade_intensity(
    bilateral_exports,
    reporter_exports,
    world_exports_to_partner,
    world_exports
  )
)
intensity
```

Values above one indicate that the reporter directs a larger export share to
the partner than the partner represents in world imports. This is a relative
measure and is not the value or growth rate of bilateral trade.

## Concentration and evenness-based diversification

```{r}
products <- c(rice = 45, wheat = 25, tea = 20, spices = 10)

c(
  HHI = trade_concentration(products),
  HHI_10000 = trade_concentration(products, scale = 10000),
  One_minus_HHI = trade_diversification(products),
  Normalized_HHI_diversity = trade_diversification(
    products, method = "normalized_hhi"
  ),
  Shannon = trade_diversification(products, method = "shannon"),
  Effective_products = trade_diversification(
    products, method = "effective_number"
  )
)
```

Higher HHI means concentration. Higher one-minus-HHI, normalized HHI diversity,
and normalized Shannon entropy mean a more even distribution. The effective
number converts entropy into the number of equally important categories that
would generate the same entropy.

When indices are compared over time or across countries, the product
classification and included category universe should remain consistent.

The package includes a small illustrative agricultural-trade file for
reproducible practice:

```{r diversity-over-time, fig.width=6.5, fig.height=4}
example_file <- system.file(
  "extdata", "agricultural_trade_example.csv",
  package = "tradeIndices"
)
ag_trade <- read.csv(example_file)

diversity_by_year <- vapply(
  split(ag_trade$country_exports, ag_trade$year),
  trade_diversification,
  numeric(1),
  method = "normalized_hhi"
)

plot(
  as.integer(names(diversity_by_year)), diversity_by_year,
  type = "o", pch = 16, lwd = 2, col = "#8D6E63",
  xlab = "Year", ylab = "Normalized HHI diversification",
  main = "Illustrative agricultural export diversification"
)
grid()
```

## Structural diversification relative to a benchmark

The structural diversification index compares a country's product shares with
a benchmark such as world exports:

\[
DIV_i=\frac{1}{2}\sum_k\left|s_{ik}-s_{wk}\right|.
\]

```{r}
country_exports <- c(rice = 45, wheat = 25, tea = 20, spices = 10)
world_exports <- c(spices = 30, tea = 15, wheat = 35, rice = 20)

c(
  Structural_distance = trade_diversification_index(
    country_exports, world_exports
  ),
  Export_similarity = export_similarity(
    country_exports, world_exports
  )
)
```

Named vectors are automatically aligned by category. A high structural index
means that the country's export pattern differs from the benchmark. It does
not necessarily mean that the country's export basket is more evenly
diversified; use `trade_diversification()` for that question.

## Additional indicators

```{r}
rca_balassa(
  country_product_exports = c(rice = 40, wheat = 20, tea = 10),
  country_total_exports = 100,
  world_product_exports = c(rice = 300, wheat = 500, tea = 200),
  world_total_exports = 5000
)

grubel_lloyd(
  exports = c(rice = 40, wheat = 25, tea = 30),
  imports = c(rice = 10, wheat = 20, tea = 28),
  aggregate = TRUE
)
```

Balassa RCA above one indicates that a product's export share is higher in the
country than in the world benchmark. A high Grubel-Lloyd value indicates a
larger share of two-way, within-product trade.

## Reproducible workflow

For a country-year panel:

1. Use the same monetary units within every formula.
2. Keep commodity classifications consistent across years.
3. Retain zero-trade categories when comparing normalized diversification.
4. Document whether conventional or reporter-excluded intensity is used.
5. Treat mirrored bilateral flows and reported flows as different data series;
   do not combine them without reconciliation.