---
title: "Get started with the igoR package"
author: Diego Hernangómez
description: >
  Introduction to the capabilities of the package.
bibliography: refs_igo.bib
link-citations: yes
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with the igoR package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r knitropts, include=FALSE}
start_time <- Sys.time()

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE,
  fig.width = 6,
  fig.height = 4,
  out.width = "100%",
  out.height = "60%"
)
```

This vignette is meant to provide **useRs** with an visual, explorable
introduction to the capabilities of the **igoR** package.

The analysis would be based on those provided on [@pevehouse2020]. For more
information on the IGO data sets and additional downloads, see
[Intergovernmental Organizations
(v3)](https://correlatesofwar.org/data-sets/IGOs/).

*Note that the dyadic dataset is not provided in the package, due its size
(\~500 MB on Stata `.dta` format). However,* `igo_dyadic()` *function provides
similar results.*

## Definitions

From @pevehouse2019:

> ### What is an IGO?
>
> The definition of an Intergovernmental Organization (IGO) on the original
> dataset is based on the following criteria:
>
> 1.  An IGO must consist of at least three members of the [COW-defined state
>     system](https://correlatesofwar.org/data-sets/cow-country-codes/).
> 2.  An IGO must hold regular plenary sessions at least once every ten years
> 3.  An IGO must possess a permanent secretariat and corresponding
>     headquarters.
>
> ### When does an IGO actually begin?
>
> The data sets begins to code an IGO by identifying the first year in which the
> organization functions. In some cases, individual members are listed by year
> of accession or signature.
>
> ### When does an IGO die?
>
> Version 3.0 of the IGO data set uses the following criteria:
>
> -   An organization is considered terminated when the following words were
>     used to describe the context of the organization:
>     -   Replaced;
>     -   Succeeded;
>     -   Superseded;
>     -   Integrated;
>     -   Merged;
>     -   Dies.

## Analysis

This section provides some quick analysis based on the figures of
@pevehouse2020.

### Initial Setup

```{r setup}
library(igoR)

# Additional libraries
library(ggplot2)
library(dplyr)
```

In first place, we create a custom `ggplot2::theme()` named `theme_igor`, that
we would apply to all our figures:

```{r custom_theme}
theme_igor <- theme(
  axis.title = element_blank(),
  axis.line.x.bottom = element_line("black"),
  axis.line.y.left = element_line("black"),
  axis.text = element_text(color = "black", family = "sans"),
  axis.text.y.left = element_text(angle = 90, hjust = 0.5),
  legend.position = "bottom",
  legend.title = element_blank(),
  legend.key = element_blank(),
  legend.key.width = unit(2, "cm"),
  legend.text = element_text(family = "sans", size = 11.5),
  legend.box.background = element_rect(color = "black", linewidth = 1),
  legend.spacing = unit(1.2 / 100, "npc"),
  plot.background = element_rect("grey90"),
  plot.margin = unit(rep(0.5, 4), "cm"),
  panel.background = element_rect("white"),
  panel.grid = element_blank(),
  panel.border = element_rect(fill = NA, colour = "grey90"),
  panel.grid.major.y = element_line("grey90")
)
```

### IGOs overview

The following code extracts the number of IGOs and states included on this
package. The years available are 1816 to 2014.

```{r Fig1, message=FALSE, warning=FALSE, fig.cap="Figure 1. IGOs and states in the world system, 1816-2014"}
# Summarize
igos_by_year <- igo_year_format3 %>%
  group_by(year) %>%
  summarise(value = n(), .groups = "keep") %>%
  mutate(variable = "Total IGOs")

countries_by_year <- state_year_format3 %>%
  group_by(year) %>%
  summarise(value = n(), .groups = "keep") %>%
  mutate(variable = "Number of COW states")

all_by_year <- igos_by_year %>%
  bind_rows(countries_by_year) %>%
  # For labelling the plot
  mutate(variable = factor(variable,
    levels = c("Total IGOs", "Number of COW states")
  ))


# Plot
ggplot(all_by_year, aes(x = year, y = value)) +
  geom_line(color = "black", aes(linetype = variable)) +
  scale_x_continuous(limits = c(1800, 2014)) +
  scale_linetype_manual(values = c("solid", "dashed")) +
  geom_vline(xintercept = c(1945, 1989)) +
  ylim(0, 400) +
  theme_igor
```

### IGO Births and deaths

This plot shows how many IGOs were "born" and "died" on each year

```{r Fig2, message=FALSE, warning=FALSE, fig.cap="Figure 2. Birth and death rates of IGOs, 1816-2014"}
# Births and deads by year

df <- igo_search()

births <- df %>%
  mutate(year = sdate) %>%
  group_by(year) %>%
  summarise(value = n(), .groups = "keep") %>%
  mutate(variable = "IGO Births")

deads <- df %>%
  mutate(year = deaddate) %>%
  group_by(year) %>%
  summarise(value = n(), .groups = "keep") %>%
  mutate(variable = "IGO Deaths")


births_and_deads <- births %>%
  bind_rows(deads) %>%
  filter(!is.na(year))

# Plot
ggplot(births_and_deads, aes(x = year, y = value)) +
  geom_line(color = "black", aes(linetype = variable)) +
  scale_linetype_manual(values = c("solid", "dashed")) +
  scale_x_continuous(
    limits = c(1815, 2015),
    breaks = seq(1815, 2015, by = 25)
  ) +
  ylim(0, 15) +
  theme_igor
```

### IGOs across regions

A plot with the number of IGOs by region. The definition of region is based on
the original definition by @pevehouse2020, as provided in the complementary
replication data set [@priorep]:

```{r regions_code}
# crossreg and universal codes not included

asia <- c(
  550, 560, 570, 580, 590, 600, 610, 640, 650, 660,
  670, 725, 750, 825, 1030, 1345, 1400, 1530, 1532, 2300,
  2770, 3185, 3330, 3560, 3930, 4115, 4150, 4160, 4170,
  4190, 4200, 4220, 4265, 4440
)

middle_east <- c(
  370, 380, 390, 400, 410, 420, 430, 440, 450, 460,
  470, 490, 500, 510, 520, 1110, 1410, 1990, 2000,
  2220, 3450, 3800, 4140, 4270, 4380
)

europe <- c(
  20, 300, 780, 800, 832, 840, 860, 1020, 1050, 1070, 1080,
  1125, 1140, 1390, 1420, 1440, 1563, 1565, 1580, 1585, 1590,
  1600, 1610, 1620, 1630, 1640, 1645, 1653, 1660, 1670, 1675,
  1680, 1690, 1700, 1710, 1715, 1720, 1730, 1740, 1750, 1760,
  1770, 1780, 1790, 1800, 1810, 1820, 1830, 1930, 1970, 1980,
  2310, 2325, 2345, 2440, 2450, 2550, 2575, 2610, 2650, 2705,
  2890, 2972, 3010, 3095, 3230, 3290, 3360, 3485, 3505, 3585,
  3590, 3600, 3610, 3620, 3630, 3640, 3650, 3655, 3660, 3665,
  3762, 3810, 3855, 3860, 3910, 4000, 4350, 4450, 4460, 4510,
  4520, 4540
)

africa <- c(
  30, 40, 50, 60, 80, 90, 100, 110, 115, 120, 125, 130, 140,
  150, 155, 160, 170, 180, 190, 200, 210, 225, 240, 250, 260, 280,
  290, 690, 700, 710, 940, 1060, 1150, 1170, 1260, 1290, 1310,
  1320, 1330, 1340, 1355, 1430, 1450, 1460, 1470, 1475, 1480,
  1500, 1510, 1520, 1870, 2080, 2090, 2230, 2330, 2795, 3300,
  3310, 3470, 3480, 3510, 3520, 3570, 3740, 3760, 3761, 3790,
  3820, 3875, 3905, 3970, 4010, 4030, 4050, 4055, 4080, 4110,
  4120, 4130, 4230, 4240, 4250, 4251, 4340, 4365, 4480, 4485,
  4490, 4500, 4501, 4503
)

americas <- c(
  310, 320, 330, 340, 720, 760, 815, 875, 880, 890, 900,
  910, 912, 913, 920, 950, 970, 980, 990, 1000, 1010, 1095,
  1130, 1486, 1489, 1490, 1860, 1890, 1920, 1950, 2070, 2110,
  2120, 2130, 2140, 2150, 2160, 2170, 2175, 2180, 2190, 2200,
  2203, 2206, 2210, 2260, 2340, 2490, 2560, 2980, 3060,
  3340, 3370, 3380, 3390, 3400, 3410, 3420, 3428, 3430, 3670,
  3680, 3812, 3830, 3880, 3890, 3900, 3925, 3980, 4070, 4100,
  4260, 4280, 4370
)

regions <- igo_search() %>%
  mutate(region = case_when(
    ionum %in% africa ~ "Africa",
    ionum %in% americas ~ "Americas",
    ionum %in% asia ~ "Asia",
    ionum %in% europe ~ "Europe",
    ionum %in% middle_east ~ "Middle East",
    TRUE ~ NA
  )) %>%
  select(ioname, region)
```

After we have created a data frame with the regions, we can classify the IGOs by
region.

```{r Fig3, message=FALSE, warning=FALSE, fig.cap="Figure 3. IGO counts across regions, 1816-2014"}
# regions dataset created on previous chunk

# All IGOs
alligos <- igo_year_format3 %>%
  select(ioname, year)

regionsum <- alligos %>%
  left_join(regions) %>%
  group_by(year, region) %>%
  summarise(value = n(), .groups = "keep") %>%
  filter(!is.na(region)) %>%
  # For plotting
  mutate(region = factor(region,
    levels = c(
      "Asia", "Europe", "Africa", "Americas",
      "Middle East"
    )
  ))


# Plot
ggplot(regionsum, aes(x = year, y = value)) +
  geom_line(color = "black", aes(linetype = region)) +
  scale_linetype_manual(
    values = c("solid", "dashed", "dotted", "dotdash", "longdash")
  ) +
  guides(linetype = guide_legend(ncol = 2, byrow = TRUE)) +
  ylim(0, 80) +
  scale_x_continuous(
    limits = c(1815, 2015),
    breaks = seq(1815, 2015, by = 25)
  ) +
  theme_igor
```

### Selected Countries: Asia

Number of memberships of a country. We select here five countries on Asia:
India, China, Pakistan, Indonesia and Bangladesh.

```{r Fig4, message=FALSE, warning=FALSE, fig.cap="Figure 4. IGO membership: five states in Asia, 1865-2014"}
asia5_cntries <- c("China", "India", "Pakistan", "Indonesia", "Bangladesh")

# Five countries of Asia
asia5_igos <- igo_state_membership(
  state = asia5_cntries, year = 1865:2014,
  status = "Full Membership"
)

asia5 <- asia5_igos %>%
  group_by(statenme, year) %>%
  summarise(values = n(), .groups = "keep") %>%
  mutate(statenme = factor(statenme, levels = asia5_cntries))

# Plot
ggplot(asia5, aes(x = year, y = values)) +
  geom_line(color = "black", aes(linetype = statenme)) +
  scale_linetype_manual(
    values = c("solid", "dashed", "dotted", "dotdash", "longdash")
  ) +
  guides(linetype = guide_legend(ncol = 3, byrow = TRUE)) +
  theme(axis.title.y.left = element_text(
    family = "sans", size = 12,
    margin = margin(r = 6)
  )) +
  scale_x_continuous(
    limits = c(1865, 2015),
    breaks = seq(1865, 2015, by = 25)
  ) +
  scale_y_continuous("Number of memberships",
    breaks = seq(0, 100, 20),
    limits = c(0, 100)
  ) +
  theme_igor
```

### Shared memberships

Number of shared full memberships between Spain and four selected countries:

```{r Fig5, message=FALSE, warning=FALSE, fig.cap="Figure 5. Number of IGOs with full shared memberships with Spain (selected countries), 1816-2014"}
selected_countries <- c("France", "Morocco", "China", "USA")

spain_selected <- igo_dyadic("Spain", selected_countries)

# Compute number of shared memberships
spain_selected <- spain_selected %>%
  rowwise() %>%
  mutate(values = sum(c_across(aaaid:wassen) == 1))

# Plot
ggplot(spain_selected, aes(x = year, y = values)) +
  geom_line(color = "black", aes(linetype = statenme2)) +
  scale_linetype_manual(values = c("solid", "dashed", "dotted", "dotdash")) +
  guides(linetype = guide_legend(ncol = 2, byrow = TRUE)) +
  theme(axis.title.y.left = element_text(
    family = "sans", size = 10,
    margin = margin(r = 6)
  )) +
  scale_x_continuous(
    limits = c(1815, 2015),
    breaks = seq(1815, 2015, by = 25)
  ) +
  scale_y_continuous("Number of memberships",
    breaks = seq(0, 110, 20),
    limits = c(0, 110)
  ) +
  theme_igor +
  geom_vline(xintercept = 1939, alpha = 0.2) +
  annotate("label", x = 1938, y = 60, size = 3, label = "Spanish \nCivil War") +
  geom_vline(xintercept = 1978, alpha = 0.2) +
  annotate("label",
    x = 1970, y = 100, size = 3,
    label = "Constitution \nof Spain"
  )
```

## References