---
title: "Get started with contentiousR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with contentiousR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`contentiousR` creates reproducible country-year panels for contentious politics and civil conflicts research, offers diagnostics and visualization tools, and allows interoperation with `peacesciencer`. Every public loader supports Correlates of War (`"cow"`) and Gleditsch-Ward (`"gw"`) country codes.

## Build and enrich a panel

Construct a state panel, then add data.

```{r}
library(contentiousR)

panel <- build_states_panel(
  start_year = 2000,
  end_year = 2002,
  coding_system = "cow"
)

analysis_data <- panel |>
  add_gdp() |>
  add_conflict("ucdp_prio") |>
  add_leader_data("archigos")

analysis_data[1:4, c(
  "country", "year", "gdp_pcap", "ucdp_prio_incidence", "leader"
)]
```

An unmatched row remains `NA`, as a source may not cover a
country-year.

## Load data separately

Standalone loaders are useful when you want to inspect or aggregate data
before joining them.

```{r}
conflicts <- conflict_data(
  start_year = 2000,
  end_year = 2002,
  dataset = "ucdp_prio",
  coding_system = "gw"
)

head(conflicts)
```

UCDP/PRIO distinguishes active conflict-years (`ucdp_prio_incidence`) from the
first year of an episode (`ucdp_prio_onset`). See
`vignette("data-sources", package = "contentiousR")` before interpreting any
source-specific variable.

## Conflict spells (peace-years)

`add_spell_duration()` turns a binary conflict column into a duration
counter — years since the last event for that state, restarting after
each new one. This is the same construct as `peacesciencer::add_spells()`
(named differently here to avoid colliding with it when both packages are
attached), useful as a control for temporal dependence in event-history
models (e.g. with cubic splines). It needs a column without `NA`, so
filter first:

```{r}
spell_data <- build_states_panel(1990, 2005, coding_system = "gw") |>
  add_conflict("ucdp_prio") |>
  tidyr::drop_na(ucdp_prio_onset) |>
  add_spell_duration(event = "ucdp_prio_onset")

spell_data[spell_data$gw == 2, c("gw", "year", "ucdp_prio_onset", "ucdp_prio_spell")]
```

If `event` is omitted, `add_spell_duration()` looks for exactly one column ending in
`_onset`, `_incidence`, or `_ongoing` and uses that; it errors if none or
several are found. `_onset`-style columns treat every `1` as an independent
event by default; `_incidence`/`_ongoing`-style columns collapse a run of
consecutive `1`s into one event, leaving the continuation years `NA` in the
output (override this with the `ongoing` argument).

## Lagged variables

`add_lag()` adds a lagged version of one or more columns, computed within
each state after sorting by year and grouping by state before lagging. 
Unlike a plain `dplyr::lag()`, it checks that the preceding row is
genuinely `n` years earlier, so a gap in the year sequence produces `NA`
rather than silently reaching further back than intended:

```{r}
build_states_panel(1990, 1995, coding_system = "cow") |>
  add_gdp() |>
  add_lag(vars = c("gdp_pcap", "gdp_growth"), n = 1) |>
  dplyr::filter(cow == 2) |>
  dplyr::select(cow, year, gdp_pcap, gdp_pcap_l, gdp_growth_l)
```

Each requested variable gets one new column named `<var>_l`. Call
`add_lag()` again (optionally with a different `n`) for additional lags.

## Visualizing onsets

`plot_coverage()` draws a state-by-year heatmap of a binary (0/1) event
column: `1` years are shaded as an event, `0` years as no event, and years
where the source has no data — either `var` is `NA`, or the state does not
appear in the panel that year at all, e.g. before independence — are left
blank. States that never have the event are dropped by default
(`drop_empty = TRUE`), since an all-blank/grey row adds clutter without
showing where events actually happened.

```{r fig.width = 7, fig.height = 6}
if (requireNamespace("ggplot2", quietly = TRUE)) {
  build_states_panel(1990, 2015, coding_system = "cow") |>
    add_conflict("ucdp_prio") |>
    plot_coverage("ucdp_prio_onset")
}
```

## Optional V-Dem data

V-Dem is not bundled and its R data package is not on CRAN. Install it from its
official repository, then request only the indicators you need:

```{r eval = FALSE}
remotes::install_github("vdeminstitute/vdemdata")

panel |>
  add_vdem(c("v2x_polyarchy", "v2x_libdem"))
```

## `build_states_panel()`

Creates a state-year panel with optional filters:

```{r eval = FALSE}
panel <- build_states_panel(
  start_year        = 1946,
  end_year          = 2019,
  coding_system     = "cow",   # or "gw"
  exclude_microstates = TRUE,
  exclude_non_un    = TRUE,
  exclude_islands   = FALSE
)
```

## `load_gdp_data()` / `add_gdp()`

Two GDP sources are available via `dataset`. `"gapminder"` (default) returns
`gdp_pcap`, `log_gdp_pcap`, and `gdp_growth`. `"fariss"` returns the latent
GDP and GDP per capita estimates from Fariss, Anders, Markowitz, and Barnum
(2022) as `fariss_gdp` and `fariss_gdppc`, with much wider coverage
(1500–2019) but units that are not independently verified in this package —
see `vignette("data-sources", package = "contentiousR")`.

```{r eval = FALSE}
# Standalone
gdp <- load_gdp_data(start_year = 1990, end_year = 2015, coding_system = "cow")
fariss_gdp <- load_gdp_data(1700, 2015, dataset = "fariss", coding_system = "cow")

# Pipeline
panel |> add_gdp()
panel |> add_gdp(dataset = "fariss")
```

## `load_population_data()` / `add_population()`

Three population sources are available via `dataset`.

| Dataset | Source | Coverage | Returned columns |
|---|---|---|---|
| `"wpp"` (default) | [UN World Population Prospects 2024](https://population.un.org/wpp/) | 1949–2023 | `wpp_pop` |
| `"nmc"` | [Correlates of War NMC v7.0](https://correlatesofwar.org/data-sets/national-material-capabilities/) | 1816–2022 | `nmc_tpop`, `nmc_upop` |
| `"fariss"` | Fariss et al. (2022) latent estimate | 1500–2019 | `fariss_pop` |

```{r eval = FALSE}
# Standalone
pop_wpp <- load_population_data(1990, 2015, dataset = "wpp", coding_system = "cow")
pop_nmc <- load_population_data(1900, 2015, dataset = "nmc", coding_system = "cow")

# Pipeline
panel |> add_population()
panel |> add_population(dataset = "nmc")
```

## `load_military_expenditure_data()` / `add_military_expenditure()`

Three military expenditure sources are available via `dataset`.

| Dataset | Source | Coverage | Returned columns |
|---|---|---|---|
| `"sipri"` (default) | [SIPRI Military Expenditure Database](https://doi.org/10.55163/CQGC9685) | 1949–2025 | `sipri_milex`, `sipri_milburden` |
| `"nmc"` | [National Material Capabilities v7.0](https://correlatesofwar.org/data-sets/national-material-capabilities/) | 1816–2022 | `nmc_milex` |
| `"barnum"` | Barnum et al. (2025) latent estimate | 1816–2019 | `barnum_milburden`, `barnum_sipri`, `barnum_nmc` |

```{r eval = FALSE}
# Standalone
milex_sipri <- load_military_expenditure_data(1990, 2015, dataset = "sipri", coding_system = "cow")
milex_barnum <- load_military_expenditure_data(1900, 2015, dataset = "barnum", coding_system = "cow")

# Pipeline
panel |> add_military_expenditure()
panel |> add_military_expenditure(dataset = "barnum")
```

Unlike the Fariss GDP/population estimates, Barnum et al.'s underlying model
does not publish a single combined military expenditure value on a real
monetary scale, so `barnum_sipri` and `barnum_nmc` are the model's posterior
estimate of two specific indicators rather than one "latent" series. See
`vignette("data-sources", package = "contentiousR")` for what each
represents and why they are not directly comparable to `sipri_milex` /
`nmc_milex`.

## `load_vdem_data()` / `add_vdem()`

V-Dem indicators. A default set of democracy, civil society, civil liberties, and rule-of-law variables is loaded when `vars = NULL`.

```{r eval = FALSE}
# Standalone
vdem <- load_vdem_data(
  vars          = c("v2x_polyarchy", "v2x_libdem"),
  start_year    = 1990,
  end_year      = 2015,
  coding_system = "cow"
)

# Pipeline
panel |> add_vdem(vars = c("v2x_polyarchy", "v2x_libdem"))
```

## `load_leader_data()` / `add_leader_data()`

Country-year leader data from two sources. Each row contains the leader who held power at the end of the year; in transition years the latest-starting leader is kept.

| Dataset | Source | Coverage | Key variables |
|---|---|---|---|
| `"archigos"` | [Archigos 4.1](https://web.archive.org/web/20241206095059/http://ksgleditsch.com/archigos.html) | 1875–2015 | `entry`, `exit`, `irregular_entry`, `irregular_exit`, `female_leader`, `yrborn`, `posttenurefate`, `leader_tenure` |
| `"reign"` | [REIGN Leader List](https://oefdatascience.github.io/REIGN.github.io/menu/reign_current.html) | 1921–2021 | `female_leader`, `military_bg`, `birthyear`, `leader_tenure` |

```{r eval = FALSE}
# Standalone
arch  <- load_leader_data(1990, 2015, dataset = "archigos", coding_system = "cow")
reign <- load_leader_data(1990, 2015, dataset = "reign",    coding_system = "gw")

# Pipeline
panel |> add_leader_data(dataset = "archigos")
panel |> add_leader_data(dataset = "reign")
```

## Interoperate with `peacesciencer`

`contentiousR` supports `peacesciencer` (see Miller 2022). It means you can add data from `peacesciencer` 
within the same data construction pipeline. 

Functions such as `peacesciencer::add_archigos()` expect `ccode`/`gwcode`
keys plus attributes that describe the state system and unit of analysis. Use
`add_from_peacesciencer()` to supply these temporarily and return a panel with
only contentiousR's original country-code key:

```{r eval = FALSE}
library(peacesciencer)

analysis_data |>
  add_from_peacesciencer(peacesciencer::add_archigos)
```

For multiple consecutive additions, call `as_peacesciencer_panel()` once and
then apply the `peacesciencer` functions directly. Neither helper changes
country codes, rows, or substantive variables.

## References

Barnum, M., Fariss, C. J., Markowitz, J. N., & Morales, G. (2025). Measuring arms: Introducing the global military spending dataset. Journal of Conflict Resolution, 69(2-3), 540-567. [https://doi.org/10.1177/00220027241232964](https://doi.org/10.1177/00220027241232964)

Fariss, C. J., Anders, T., Markowitz, J. N., & Barnum, M. (2022). New estimates of over 500 years of historic GDP and population data. Journal of Conflict Resolution, 66(3), 553-591. [https://doi.org/10.1177/00220027211054432](https://doi.org/10.1177/00220027211054432)

Miller, S. V. (2022). {peacesciencer}: An R package for quantitative peace science research. Conflict Management and Peace Science, 39(6), 755-779. [https://doi.org/10.1177/07388942221077926](https://doi.org/10.1177/07388942221077926)

Singer, J. David. (1988). Reconstructing the Correlates of War Dataset on Material Capabilities of States, 1816-1985. International Interactions, 14: 115-32.

Singer, J. David, Stuart Bremer, and John Stuckey. (1972). “Capability Distribution, Uncertainty, and Major Power War, 1820-1965.” in Bruce Russett (ed) Peace, War, and Numbers, Beverly Hills: Sage, 19-48.