Package {contentiousR}

Type:	Package
Title:	Contentious Politics and Civil Conflict Research
Version:	0.1.0
Description:	Constructs reproducible country-year panels for research on contentious politics and civil conflict, as described in Guseinov (2026) <doi:10.2139/ssrn.7506799>. Functions build state panels keyed by Correlates of War or Gleditsch-Ward country codes and join curated socioeconomic, leadership, democracy, conflict, protest, and revolutionary-episode data on that common key, with diagnostics and plots for comparing source coverage. Bundled sources include Gapminder; the Nonviolent and Violent Campaigns and Outcomes (NAVCO) 2.1 data, Chenoweth and Shay (2019) <doi:10.7910/DVN/MHOXDV>; the Social Conflict Analysis Database, Salehyan et al. (2012) <doi:10.1080/03050629.2012.697426>; the Uppsala Conflict Data Program and Peace Research Institute Oslo (UCDP/PRIO) Armed Conflict Dataset, Gleditsch et al. (2002) <doi:10.1177/0022343302039005007>; and the Major Episodes of Contention data, Chenoweth and Kang (2026) <doi:10.1093/jopres/xjaf008>. Varieties of Democracy (V-Dem) indicators require the optional 'vdemdata' package, which is not on CRAN and can be installed from https://github.com/vdeminstitute/vdemdata.
License:	MIT + file LICENSE
Copyright:	See file COPYRIGHTS for the third-party data bundled in inst/extdata.
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
Imports:	countrycode, dplyr, readr, states, stats, tidyr
Suggests:	brglm2, ggplot2, knitr, peacesciencer (≥ 1.2.0), readxl, rmarkdown, testthat (≥ 3.0.0), vdemdata
Config/testthat/edition:	3
VignetteBuilder:	knitr
URL:	https://rguseinov.github.io/contentiousR/, https://github.com/rguseinov/contentiousR
BugReports:	https://github.com/rguseinov/contentiousR/issues
Config/Needs/website:	r-lib/pkgdown
LazyData:	true
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-10-04 11:44:56 UTC; manin
Author:	Ruslan Guseinov [aut, cre]
Maintainer:	Ruslan Guseinov <rigusseinov@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-15 16:20:09 UTC

contentiousR: Contentious Politics and Civil Conflict Research

Description

contentiousR creates COW- or Gleditsch-Ward-coded state-year panels and joins bundled socioeconomic, conflict, protest, and leader data. V-Dem data are available through the optional vdemdata package.

Details

The main workflow starts with build_states_panel() and continues with the ⁠add_*()⁠ functions. The corresponding ⁠load_*()⁠ functions return source data without joining it to a state panel.

Country-code conversions

Conversions use countrycode::countrycode(). Rows with no equivalent in the requested coding system are omitted. Historical entities can differ between COW and Gleditsch-Ward; users should inspect coverage for their study period.

Data provenance

See vignette("data-sources", package = "contentiousR") and citation("contentiousR") for dataset versions, source links, licenses, and requested citations.

Author(s)

Maintainer: Ruslan Guseinov rigusseinov@gmail.com (ORCID)

Authors:

• Ruslan Guseinov rigusseinov@gmail.com (ORCID)

See Also

Useful links:

• https://rguseinov.github.io/contentiousR/

• https://github.com/rguseinov/contentiousR

• Report bugs at https://github.com/rguseinov/contentiousR/issues

Add conflict or protest data to a state panel

Description

Joins a conflict, protest, or revolutionary episode dataset onto an existing state panel at the country-year level.

Country-year datasets ("scad", "ucdp_prio", "ucdp_vpp", "mm", "mmad") are already at the country-year level when loaded, so the aggregate argument has no effect for them.

Campaign and episode datasets ("navco1.3", "navco2.1", "beissinger", "csra", "mec") can have multiple rows per country-year. With aggregate = TRUE (the default) these are collapsed to country-year by taking the maximum of all numeric columns, and an n_campaigns count column is added. Set aggregate = FALSE to keep campaign-level rows (may produce duplicates).

Usage

add_conflict(panel, dataset, aggregate = TRUE)

Arguments

Value

The input panel with conflict/protest columns added via left join. Unmatched country-years remain NA; the function does not assume that an unobserved event indicator is zero.

References

Chenoweth, E., & Shay, C. W. (2020). List of Campaigns in NAVCO 1.3. Harvard Dataverse. doi:10.7910/DVN/ON9XND

Chenoweth, E., & Shay, C. W. (2019). NAVCO 2.1 Dataset. Harvard Dataverse. doi:10.7910/DVN/MHOXDV

Beissinger, M. (2022). Revolutionary Episodes Dataset.

Ustyuzhanin, V., Semichev, D., Grinin, L., & Korotaev, A. (2026). Revolutionary Database (2000-2024), Version 1.102. HSE University, Centre for Stability and Risk Analysis. https://social.hse.ru/mr/rev_bd

Salehyan, I., Hendrix, C. S., Hamner, J., Case, C., Linebarger, C., Stull, E., & Williams, J. (2012). Social conflict in Africa: A new database. International Interactions, 38(4), 503-511. doi:10.1080/03050629.2012.697426

Gleditsch, N. P., Wallensteen, P., Eriksson, M., Sollenberg, M., & Strand, H. (2002). Armed conflict 1946-2001: A new dataset. Journal of Peace Research, 39(5), 615-637. doi:10.1177/0022343302039005007

Svensson, I., Schaftenaar, S., & Allansson, M. (2022). Violent political protest: Introducing a new Uppsala Conflict Data Program data set on organized violence, 1989-2019. Journal of Conflict Resolution, 66(9), 1703-1730.

Clark, D. H., & Regan, P. M. (2016). Mass Mobilization Protest Data. Harvard Dataverse. doi:10.7910/DVN/HTTWYL

Weidmann, N. B., & Rød, E. G. (2019). The Internet and Political Protest in Autocracies. Oxford University Press.

Chenoweth, E., & Kang, S. (2026). The Major Episodes of Contention (MEC) Data Project: An introduction. Journal of Peace Research, 63(4), 724-734. doi:10.1093/jopres/xjaf008

Examples

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_conflict(dataset = "navco2.1")

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_conflict(dataset = "ucdp_prio")

panel <- build_states_panel(2005, 2020, coding_system = "cow") |>
  add_conflict(dataset = "mmad")

# Raw join for legacy datasets — researcher handles aggregation manually
panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_conflict(dataset = "navco1.3", aggregate = FALSE)

# MEC is episode-level; keep individual episodes with aggregate = FALSE
panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_conflict(dataset = "mec", aggregate = FALSE)

Add data from peacesciencer and restore the contentiousR schema

Description

Temporarily adapts a contentiousR state-year panel to the column names and metadata expected by a peacesciencer ⁠add_*()⁠ function. After that function returns, the temporary ccode or gwcode alias and dispatch attributes are removed. The original cow or gw key is retained.

Usage

add_from_peacesciencer(panel, .fun, ...)

Arguments

Details

This helper is intended for peacesciencer functions that support state-year data. It does not alter country codes: ccode is simply peacesciencer's name for the COW code stored as cow by contentiousR.

Use as_peacesciencer_panel() instead when several peacesciencer functions will be applied in one uninterrupted pipeline and retaining the compatibility metadata until the end is preferable.

Value

The data frame returned by .fun, restored to the input contentiousR key schema. A pre-existing ccode or gwcode column and pre-existing ps_system or ps_data_type attributes are preserved.

Examples

if (requireNamespace("peacesciencer", quietly = TRUE)) {
  library(peacesciencer)

  panel <- build_states_panel(1990, 1995, coding_system = "cow") |>
    add_from_peacesciencer(add_archigos)
}

Add GDP data to a state panel

Description

Joins GDP data onto an existing state panel. The coding system ("cow" or "gw") and year range are detected automatically from the panel.

Usage

add_gdp(panel, dataset = c("gapminder", "fariss"))

Arguments

Value

The input panel with GDP columns added via left join.

References

Gapminder. (2024). GDP per capita in constant PPP dollars. https://www.gapminder.org/gdp-per-capita/

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. doi:10.1177/00220027211054432

Examples

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_gdp()

panel <- build_states_panel(1900, 2010, coding_system = "cow") |>
  add_gdp(dataset = "fariss")

Add lagged variables to a state panel

Description

Adds a lagged version of each requested column, computed within each state (group_by(cow) or group_by(gw), matching the panel's coding system) after sorting by year — required for lags to be meaningful in panel data. Unlike a plain dplyr::lag(), the lag is NA wherever the preceding row is not exactly n years earlier, so gaps in the year sequence (e.g. after filtering with tidyr::drop_na()) do not silently produce a lag from the wrong year.

Usage

add_lag(panel, vars, n = 1)

Arguments

Value

The input panel with one additional column per entry in vars, named ⁠<var>_l⁠, holding the value of ⁠<var>⁠ from n years earlier for the same state (or NA if that year is not present in panel).

Examples

panel <- build_states_panel(1990, 2000, coding_system = "cow") |>
  add_gdp() |>
  add_lag(vars = c("gdp_pcap", "gdp_growth"), n = 1)

Add leader data to a state panel

Description

Joins country-year leader data onto an existing state panel. The coding system and year range are detected automatically from the panel.

Each country-year is assigned the leader who held power at the end of that year (i.e., the leader with the latest start date when multiple leaders served in the same year).

Usage

add_leader_data(panel, dataset = c("archigos", "reign"))

Arguments

Value

The input panel with leader columns added via left join.

References

Goemans, H. E., Gleditsch, K. S., & Chiozza, G. (2009). Introducing Archigos: A dataset of political leaders. Journal of Peace Research, 46(2), 269-283.

Bell, C., Besaw, C., & Frank, M. (2021). The Rulers, Elections, and Irregular Governance (REIGN) Dataset.

Examples

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_leader_data(dataset = "archigos")

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_leader_data(dataset = "reign")

Add military expenditure data to a state panel

Description

Joins country-year military expenditure data onto an existing state panel. The coding system and year range are detected automatically from the panel.

Usage

add_military_expenditure(panel, dataset = c("sipri", "nmc", "barnum"))

Arguments

Value

The input panel with military expenditure columns added via left join.

References

Singer, J. D., Bremer, S., & Stuckey, J. (1972). Capability distribution, uncertainty, and major power war, 1820-1965. In B. Russett (Ed.), Peace, War, and Numbers (pp. 19-48). Sage.

Singer, J. D. (1988). Reconstructing the Correlates of War dataset on material capabilities of states, 1816-1985. International Interactions, 14, 115-132.

Stockholm International Peace Research Institute. (2025). SIPRI Military Expenditure Database. doi:10.55163/CQGC9685

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. doi:10.1177/00220027241232964

Examples

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_military_expenditure()

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_military_expenditure(dataset = "nmc")

Add population data to a state panel

Description

Joins country-year population data onto an existing state panel. The coding system and year range are detected automatically from the panel.

Usage

add_population(panel, dataset = c("wpp", "nmc", "fariss"))

Arguments

Value

The input panel with population columns added via left join.

References

United Nations, Department of Economic and Social Affairs, Population Division. (2024). World Population Prospects 2024. https://population.un.org/wpp/

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. doi:10.1177/00220027211054432

Singer, J. D., Bremer, S., & Stuckey, J. (1972). Capability distribution, uncertainty, and major power war, 1820-1965. In B. Russett (Ed.), Peace, War, and Numbers (pp. 19-48). Sage.

Singer, J. D. (1988). Reconstructing the Correlates of War dataset on material capabilities of states, 1816-1985. International Interactions, 14, 115-132.

Examples

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_population(dataset = "wpp")

panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_population(dataset = "nmc")

Add region names to a state panel

Description

Joins region names onto an existing state panel via countrycode::countrycode(), mapping the panel's cow/gw codes to one or more of countrycode's regional classifications. The coding system is detected automatically from the panel.

Usage

add_regions(panel, region = "region")

Arguments

Value

The input panel with one additional column per entry in region, named after the classification (e.g. region, region23), holding the corresponding region name for each row (NA where countrycode() finds no match).

Examples

panel <- build_states_panel(1990, 2000, coding_system = "cow") |>
  add_regions()

panel <- build_states_panel(1990, 2000, coding_system = "cow") |>
  add_regions(region = c("region", "un.regionsub.name"))

Add conflict spell (peace-years) durations to a state panel

Description

Computes a BTSCS-style spell/duration counter from a binary conflict column already present in the panel (typically added by add_conflict()): the number of years since the last event for that state, restarting after each new event. This is the same construct as peacesciencer::add_spells(), generalized to work with any binary column rather than a fixed set of bundled column names. Named add_spell_duration(), not add_spells(), to avoid colliding with peacesciencer::add_spells() when both packages are attached.

Usage

add_spell_duration(panel, event = NULL, ongoing = NULL)

Arguments

Details

event must not contain NA. add_conflict()'s output frequently has NA for country-years unmatched by the source (documented behavior: absence from a source is not evidence of zero events), and a spell count cannot be computed across a gap of unknown conflict status. Filter or otherwise resolve these NAs before calling add_spell_duration().

Value

The input panel with one additional integer column, named after event with its onset/incidence/ongoing suffix (if any) replaced by ⁠_spell⁠. In a fresh spell, the first observed year is 0 and each subsequent year without a new event increments by one; the event year itself carries the final count of the spell it closes.

Examples

panel <- build_states_panel(1990, 2010, coding_system = "gw") |>
  add_conflict(dataset = "ucdp_prio") |>
  tidyr::drop_na(ucdp_prio_onset) |>
  add_spell_duration(event = "ucdp_prio_onset")

Add V-Dem indicators to a state panel

Description

Joins V-Dem country-year data onto an existing state panel. The coding system and year range are detected automatically from the panel.

Requires the vdemdata package: remotes::install_github("vdeminstitute/vdemdata")

Usage

add_vdem(panel, vars = NULL)

Arguments

Value

The input panel with V-Dem columns added via left join.

References

Coppedge, M., Gerring, J., Knutsen, C. H., Lindberg, S. I., Teorell, J., Altman, D., Bernhard, M., Fish, M. S., Glynn, A., Hicken, A., et al. (2025). V-Dem [Country-Year/Country-Date] Dataset v15. Varieties of Democracy.

Examples

if (requireNamespace("vdemdata", quietly = TRUE)) {
panel <- build_states_panel(1990, 2010, coding_system = "cow") |>
  add_vdem(vars = c("v2x_polyarchy", "v2x_libdem", "v2x_rule"))
}

Make a state panel compatible with peacesciencer

Description

Adds the key alias and metadata expected by state-year functions from the peacesciencer package. The original cow or gw column is retained, so the result remains compatible with all contentiousR functions.

Usage

as_peacesciencer_panel(panel)

Arguments

Details

peacesciencer dispatches its ⁠add_*()⁠ functions using attributes created by peacesciencer::create_stateyears(). It also expects its own key names: ccode for COW panels and gwcode for Gleditsch-Ward panels. This adapter supplies that interface without replacing contentiousR's cow or gw key.

Place the adapter immediately before the first peacesciencer function, or earlier in the pipeline. Dplyr joins used by contentiousR preserve these attributes.

Value

The input data frame with an additional ccode (COW) or gwcode (Gleditsch-Ward) alias and the attributes ps_system and ps_data_type = "state_year". Rows and analytical variables are not changed.

Examples

panel <- build_states_panel(1990, 1995, coding_system = "cow") |>
  add_gdp() |>
  as_peacesciencer_panel()

names(panel)
attr(panel, "ps_system")
attr(panel, "ps_data_type")

Build a COW-coded state panel

Description

Build a COW-coded state panel

Usage

build_states_cow_panel(
  start_year = 1946,
  end_year = 2013,
  exclude_microstates = TRUE,
  exclude_non_un = TRUE,
  exclude_islands = FALSE
)

Arguments

Value

A data frame with COW-coded state-year observations.

Build a state panel

Description

Build a state panel

Usage

build_states_panel(
  start_year = 1946,
  end_year = 2013,
  coding_system = c("cow", "gw"),
  exclude_microstates = TRUE,
  exclude_non_un = TRUE,
  exclude_islands = FALSE
)

Arguments

Value

A data frame with state-year observations.

Check a logical flag

Description

Check a logical flag

Usage

check_flag(value, name)

Arguments

Value

Invisibly TRUE if value is a single non-missing logical; otherwise an error is raised.

Check that data are uniquely identified by key columns

Description

Check that data are uniquely identified by key columns

Usage

check_unique_key(data, keys)

Arguments

Value

Invisibly, data unchanged if the keys are unique; otherwise an error is raised.

Check year range

Description

Check year range

Usage

check_year_range(start_year, end_year, min_year = NULL, max_year = NULL)

Arguments

Value

Invisibly TRUE if the range is valid; otherwise an error is raised.

Bundled bibliography for cn_cite()

Description

A bibentry object with one entry per bundled or interoperable data source, used by cn_cite(). Each entry's keywords field lists the contentiousR function(s) and/or ⁠dataset =⁠ value(s) it documents.

Usage

cn_bib

Format

A bibentry object of length 22.

Source

data-raw/contentiousR_bib.bib and data-raw/contentiousR_bib.R.

Cite a bundled data source

Description

Looks up the bundled bibliography (cn_bib) by keyword or BibTeX key and returns the matching entries. Printing the result (e.g. at the console) shows them as BibTeX text, ready to paste into your own .bib file.

Usage

cn_cite(x, column = c("keywords", "bibtexkey"))

Arguments

Value

A bibentry object (with the additional class cn_citation) holding the matching entries. Its print() method displays them as BibTeX; all other bibentry methods, such as format() and toBibtex(), work as usual.

Examples

cn_cite("archigos")
cn_cite("add_conflict()")
cn_cite("gleditschArmedConflict194620012002", column = "bibtexkey")

Compute a BTSCS spell/duration counter

Description

Compute a BTSCS spell/duration counter

Usage

compute_spells(unit, year, event, ongoing)

Arguments

Value

An integer vector of spell values, one per input row (in the original row order).

Load conflict and mobilization data

Description

Loads one of ten conflict, protest, or revolutionary episode datasets bundled with the package. scad, ucdp_prio, ucdp_vpp, mm, and mmad are returned at the country-year level; their event- or conflict-level source rows are aggregated inside this function.

navco1.3, beissinger, csra, and mec return campaign or episode records; navco2.1 returns campaign-year rows. These sources can contain multiple rows for one country-year. Use add_conflict(aggregate = TRUE) (the default) to collapse them to country-year.

Usage

conflict_data(
  start_year = 1945,
  end_year = 2013,
  dataset = c("navco1.3", "navco2.1", "beissinger", "csra", "scad", "ucdp_prio",
    "ucdp_vpp", "mm", "mmad", "mec"),
  coding_system = c("cow", "gw")
)

Arguments

Details

All outputs use the requested cow or gw key and year. Dataset-specific columns have a stable source prefix. A missing country-year row is not created by this loader; after add_conflict(), an unmatched year is NA, not an assumed zero.

SCAD is deduplicated to one row per event before country-year aggregation. Its UCDP placeholder rows are excluded, and documented negative codes for unknown death counts are treated as missing.

For UCDP/PRIO, ucdp_prio_incidence identifies any active conflict-year and ucdp_prio_onset identifies a new episode using the source's start_date2. The VPP source does not include an episode-start variable; ucdp_vpp_incidence should be preferred. The legacy ucdp_vpp_onset column is retained as an incidence alias for compatibility.

The Mass Mobilization source mixes exact participant counts with text such as ranges and inequalities. mm_participants is the maximum among genuinely numeric values; mm_participants_reported preserves the source strings.

MEC is kept at its published episode level. Its source byear becomes year, ccode becomes cow, and all other source columns receive the mec_ prefix. mec_episode equals one for every returned episode record. Fourteen left-censored records have an actual mec_bdate before 1955 while their source byear is 1955. With GW coding, COW 679 (Yemen) maps to GW 678 and COW 817 (South Vietnam) maps to GW 817; Tonga has no GW state equivalent and is omitted.

Value

A data frame. navco1.3, beissinger, csra, and mec contain one row per campaign or episode record; navco2.1 contains campaign-year rows. The other datasets contain one row per country-year.

Source

NAVCO 2.1: doi:10.7910/DVN/MHOXDV.

Beissinger Revolutionary Episodes: https://web.archive.org/web/20250331220952/https://mbeissinger.scholar.princeton.edu/revolutionary-episodes-dataset.

HSE Revolutionary Database: https://social.hse.ru/mr/rev_bd.

SCAD: https://www.strausscenter.org/ccaps-research-areas/social-conflict/database/.

UCDP: https://ucdp.uu.se/downloads/replication_data.html.

MMAD: https://mmadatabase.org/.

MEC: Chenoweth and Kang (2026), doi:10.1093/jopres/xjaf008; data release doi:10.7910/DVN/JQWQNW.

References

Chenoweth, E., & Shay, C. W. (2020). List of Campaigns in NAVCO 1.3. Harvard Dataverse. doi:10.7910/DVN/ON9XND

Chenoweth, E., & Shay, C. W. (2019). NAVCO 2.1 Dataset. Harvard Dataverse. doi:10.7910/DVN/MHOXDV

Beissinger, M. (2022). Revolutionary Episodes Dataset.

Ustyuzhanin, V., Semichev, D., Grinin, L., & Korotaev, A. (2026). Revolutionary Database (2000-2024), Version 1.102. HSE University, Centre for Stability and Risk Analysis. https://social.hse.ru/mr/rev_bd

Salehyan, I., Hendrix, C. S., Hamner, J., Case, C., Linebarger, C., Stull, E., & Williams, J. (2012). Social conflict in Africa: A new database. International Interactions, 38(4), 503-511. doi:10.1080/03050629.2012.697426

Gleditsch, N. P., Wallensteen, P., Eriksson, M., Sollenberg, M., & Strand, H. (2002). Armed conflict 1946-2001: A new dataset. Journal of Peace Research, 39(5), 615-637. doi:10.1177/0022343302039005007

Svensson, I., Schaftenaar, S., & Allansson, M. (2022). Violent political protest: Introducing a new Uppsala Conflict Data Program data set on organized violence, 1989-2019. Journal of Conflict Resolution, 66(9), 1703-1730.

Clark, D. H., & Regan, P. M. (2016). Mass Mobilization Protest Data. Harvard Dataverse. doi:10.7910/DVN/HTTWYL

Weidmann, N. B., & Rød, E. G. (2019). The Internet and Political Protest in Autocracies. Oxford University Press.

Chenoweth, E., & Kang, S. (2026). The Major Episodes of Contention (MEC) Data Project: An introduction. Journal of Peace Research, 63(4), 724-734. doi:10.1093/jopres/xjaf008

Examples

navco <- conflict_data(1990, 2010, dataset = "navco2.1", coding_system = "cow")

scad  <- conflict_data(1995, 2015, dataset = "scad",      coding_system = "cow")

ucdp  <- conflict_data(1990, 2020, dataset = "ucdp_prio", coding_system = "gw")

mec   <- conflict_data(1990, 2010, dataset = "mec",       coding_system = "cow")

Detect coding system from a panel data frame

Description

Detect coding system from a panel data frame

Usage

detect_coding_system(panel)

Arguments

Value

"cow" or "gw".

Fetch one row per campaign/episode onset from several conflict datasets

Description

Fetch one row per campaign/episode onset from several conflict datasets

Usage

fetch_campaign_events(datasets, start_year, end_year, coding_system)

Arguments

Details

"navco1.3", "beissinger", "csra", and "mec" are already one row per campaign/episode. "navco2.1" is not: conflict_data() returns one row per campaign-year, so a single long-running campaign contributes many rows. Comparing that directly against onset-coded datasets would overstate NAVCO 2.1's event counts by roughly the average campaign duration. To keep the comparison on the same onset-level footing as the source article, "navco2.1" is filtered here to nvc2.1_ONSET == 1, conflict_data()'s own per-campaign onset flag (keyed on the numeric campaign id, not the free-text campaign name, which is not unique – e.g. three distinct "Myanmar Regime Change Campaign" entries share that name). That flag is computed over the dataset's full native coverage before start_year/end_year filtering, so campaigns already under way at start_year are not mistaken for new onsets.

countrycode::countrycode()'s "region" destination is not a clean 7-category classification: a handful of pre-1990 historical entities (Yemen Arab Republic, Yemen People's Republic, the United Arab Republic) still carry the World Bank's older "Middle East & North Africa" label, while every other country in that region carries the newer, longer "Middle East, North Africa, Afghanistan & Pakistan" label – these historical COW/GW codes do appear in campaign data covering the 1950s-80s, so left as-is they'd split one region into two bars. The newer label is recoded to the shorter, older one here (kept as the canonical form for display) so the region breakdown stays at exactly 7 categories.

Value

A data frame with dataset, unit (the coding-system code), year, and region (World Bank 7-region classification, via countrycode::countrycode()).

Harmonize externally supplied conflict/event data onto a state panel

Description

Joins a conflict or event dataset that the caller supplies directly – downloaded via GDELT, ICEWS, ACLED, or any other source not bundled with contentiousR – onto an existing state panel. Unlike add_conflict(), this function never downloads or bundles any data itself: data is whatever data frame the caller already has in R, in whatever raw column names and country/date encodings that source happens to use.

Usage

harmonize_conflict_data(
  panel,
  data,
  country_col,
  origin_code,
  prefix,
  year_col = NULL,
  date_col = NULL,
  date_format = NULL,
  aggregate = TRUE
)

Arguments

Details

Country matching uses countrycode::countrycode(), so any row whose country_col value it cannot map to the panel's coding system (an unrecognized name, a sub-national/organizational entry, etc.) is dropped, with a message reporting how many rows were dropped.

contentiousR deliberately does not depend on gdeltr2, icews, or acled.api – this function is a generic bridge instead, so the package is not exposed to any of those clients' own dependencies, rate limits, or licensing terms. Cite the original data source directly (this function does not know anything about the specific provenance of data).

Value

panel with the new column(s) joined in via left_join(). Country-years absent from data remain NA – as with add_conflict(), that is not evidence of zero events, only that data doesn't cover that country-year.

Examples

panel <- build_states_panel(2015, 2018, coding_system = "cow")

# An ACLED-style extract: one row per event, country as free text.
acled_like <- data.frame(
  country    = c("Nigeria", "Nigeria", "Mali", "Mali", "Mali"),
  event_date = c("2016-03-01", "2017-11-20", "2015-06-14",
                  "2015-09-02", "2018-01-30"),
  stringsAsFactors = FALSE
)

panel |>
  harmonize_conflict_data(
    data        = acled_like,
    country_col = "country",
    origin_code = "country.name",
    date_col    = "event_date",
    prefix      = "acled"
  )

# A GDELT-style extract: FIPS country codes, SQLDATE as YYYYMMDD.
gdelt_like <- data.frame(
  Actor1CountryCode = c("NI", "NI", "ML"),
  SQLDATE           = c(20160301L, 20171120L, 20150614L)
)

panel |>
  harmonize_conflict_data(
    data        = gdelt_like,
    country_col = "Actor1CountryCode",
    origin_code = "fips",
    date_col    = "SQLDATE",
    date_format = "%Y%m%d",
    prefix      = "gdelt"
  )

Lag a vector within a panel, respecting gaps in the year sequence

Description

Lag a vector within a panel, respecting gaps in the year sequence

Usage

lag_with_year_gap_check(x, year, n)

Arguments

Value

x shifted back by n positions, with NA wherever the corresponding row is not exactly n years earlier (e.g. because that year is missing from the data).

Load GDP data

Description

Loads GDP data from one of two sources included with the package and returns a country-year dataset using either COW or Gleditsch-Ward country codes.

Usage

load_gdp_data(
  start_year = 1945,
  end_year = 2019,
  dataset = c("gapminder", "fariss"),
  coding_system = c("cow", "gw")
)

Arguments

Details

gdp_growth (gapminder only) is NA unless the preceding row is genuinely one year earlier for the same country, the same gap-safety check add_lag() uses, so a missing year never silently produces a growth rate computed against the wrong base year.

fariss_gdp and fariss_gdppc are the model's own latent-scale estimates, taken directly from the "latent_gdp"/"latent_gdppc" rows of the replication files (as opposed to the underlying raw indicator series also present in those files). Their absolute units are not independently verified here; consult Fariss et al. (2022) before using them outside of relative/comparative analysis.

Value

A data frame with country-year GDP indicators. If coding_system = "cow", the data frame contains a cow column. If coding_system = "gw", it contains a gw column. Columns differ by dataset:

gapminder: year, gdp_pcap, log_gdp_pcap, gdp_growth.

fariss: year, fariss_gdp, fariss_gdppc.

Source

Gapminder: GDP per capita data from Gapminder. Gapminder data are distributed under CC BY 4.0; please cite Gapminder and the original data providers.

Fariss: 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.

References

Gapminder. (2024). GDP per capita in constant PPP dollars. https://www.gapminder.org/gdp-per-capita/

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. doi:10.1177/00220027211054432

Examples

gdp_cow <- load_gdp_data(coding_system = "cow")

gdp_gw <- load_gdp_data(coding_system = "gw")

fariss_gdp <- load_gdp_data(1900, 2015, dataset = "fariss", coding_system = "cow")

Load leader data

Description

Loads country-year leader data from one of two datasets included with the package. Each row in the output represents one country-year, with the leader who held power at the end of the year. When multiple leaders served in the same year (i.e., a leadership transition occurred), the leader with the latest start date is retained.

Usage

load_leader_data(
  start_year = 1945,
  end_year = 2015,
  dataset = c("archigos", "reign"),
  coding_system = c("cow", "gw")
)

Arguments

Value

A country-year data frame. Columns differ by dataset:

archigos: cow/gw, year, leader, entry, exit, irregular_entry, irregular_exit, female_leader, yrborn, posttenurefate, leader_tenure.

reign: cow/gw, year, leader, female_leader, military_bg, birthyear, leader_tenure.

Source

Archigos: Goemans, H.E., Gleditsch, K.S., & Chiozza, G. (2009). Introducing Archigos: A Dataset of Political Leaders. Journal of Peace Research, 46(2), 269–283. https://web.archive.org/web/20241206095059/http://ksgleditsch.com/archigos.html

REIGN: Bell, C. (2021). REIGN: Rulers, Elections, and Irregular Governance Dataset. One Earth Future Foundation. https://oefdatascience.github.io/REIGN.github.io/

References

Goemans, H. E., Gleditsch, K. S., & Chiozza, G. (2009). Introducing Archigos: A dataset of political leaders. Journal of Peace Research, 46(2), 269-283.

Bell, C., Besaw, C., & Frank, M. (2021). The Rulers, Elections, and Irregular Governance (REIGN) Dataset.

Examples

arch <- load_leader_data(1990, 2010, dataset = "archigos", coding_system = "cow")

reign <- load_leader_data(1990, 2010, dataset = "reign", coding_system = "gw")

Load military expenditure data

Description

Loads country-year military expenditure data from one of the sources included with the package.

Usage

load_military_expenditure_data(
  start_year = 1945,
  end_year = 2019,
  dataset = c("sipri", "nmc", "barnum"),
  coding_system = c("cow", "gw")
)

Arguments

Details

NMC's -9 missing-data sentinel is recoded to NA in nmc_milex.

The SIPRI workbook lists a small number of rows (e.g. "Africa", "NATO") that are regional or organizational aggregates rather than countries; these have no matching COW/Gleditsch-Ward code and are dropped when countrycode::countrycode() returns NA.

Barnum et al.'s replication files contain one row per country-year for each of 24 underlying source indicators (SIPRI, WMEAT, NCD, IISS, and others), each already reported in its own original currency/unit. Unlike Fariss et al. (2022)'s GDP and population estimates, the paper does not publish a single combined "latent" value on a real monetary scale: "the average by itself does not have a real or direct monetary unit" (p. 550). Instead, barnum_sipri and barnum_nmc are the model's posterior estimate of two specific indicators (the "milex_con_2022_sipri" and "milex_con_2017_nmc" series respectively), which extends each one's coverage back to 1816 using information from all 24 sources, still expressed in that indicator's own original units. barnum_milburden is milexgdp from Barnum et al.'s separate military-burden estimates file, which is unit-free and so is published directly.

Both "_con_" indicators are in constant (inflation-adjusted) dollars, unlike nmc_milex from dataset = "nmc", which NMC documents in current-year dollars. barnum_nmc is therefore not directly comparable to nmc_milex: their ratio varies smoothly over time (e.g. around 2.4 for the United States in 1990, falling toward 1 by the mid-2010s), which reflects cumulative inflation adjustment rather than disagreement between the two sources.

Value

A country-year data frame. Columns differ by dataset:

sipri: cow/gw, year, sipri_milex, sipri_milburden.

nmc: cow/gw, year, nmc_milex.

barnum: cow/gw, year, barnum_milburden, barnum_sipri, barnum_nmc.

Source

SIPRI: Stockholm International Peace Research Institute (2025). SIPRI Military Expenditure Database. https://www.sipri.org/databases/milex

NMC: Singer, J. David, Bremer, Stuart & Stuckey, John (1972). Capability Distribution, Uncertainty, and Major Power War, 1820-1965. National Material Capabilities v7.0. https://correlatesofwar.org/data-sets/national-material-capabilities/

Barnum: 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.

References

Singer, J. D., Bremer, S., & Stuckey, J. (1972). Capability distribution, uncertainty, and major power war, 1820-1965. In B. Russett (Ed.), Peace, War, and Numbers (pp. 19-48). Sage.

Singer, J. D. (1988). Reconstructing the Correlates of War dataset on material capabilities of states, 1816-1985. International Interactions, 14, 115-132.

Stockholm International Peace Research Institute. (2025). SIPRI Military Expenditure Database. doi:10.55163/CQGC9685

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. doi:10.1177/00220027241232964

Examples

milex_sipri <- load_military_expenditure_data(1990, 2015, dataset = "sipri", coding_system = "cow")

milex_nmc <- load_military_expenditure_data(1900, 2015, dataset = "nmc", coding_system = "cow")

Load population data

Description

Loads country-year population data from one of three sources included with the package.

Usage

load_population_data(
  start_year = 1945,
  end_year = 2019,
  dataset = c("wpp", "nmc", "fariss"),
  coding_system = c("cow", "gw")
)

Arguments

Details

The bundled UN WPP extract has three rows for some China country-years: a combined mainland+Hong Kong+Macao+Taiwan figure, a mainland-only figure, and a Hong Kong-only figure, all of which matched COW code 710 during country-name conversion upstream. The mainland-only figure is consistently the median of the three, so wpp_pop is computed as the median pop value within each cow-year group; for every other country-year (a single row) this is a no-op.

NMC's -9 missing-data sentinel is recoded to NA in nmc_tpop and nmc_upop.

fariss_pop is the model's own latent-scale estimate, taken directly from the "latent_pop" rows of the replication file. Its absolute units are not independently verified here; consult Fariss et al. (2022) before using it outside of relative/comparative analysis.

Value

A country-year data frame. Columns differ by dataset, each prefixed with the source's dataset key:

wpp: cow/gw, year, wpp_pop.

nmc: cow/gw, year, nmc_tpop, nmc_upop.

fariss: cow/gw, year, fariss_pop.

Source

UN WPP: United Nations, Department of Economic and Social Affairs, Population Division (2024). World Population Prospects 2024. https://population.un.org/wpp/

NMC: Singer, J. David, Bremer, Stuart & Stuckey, John (1972). Capability Distribution, Uncertainty, and Major Power War, 1820-1965. National Material Capabilities v7.0. https://correlatesofwar.org/data-sets/national-material-capabilities/

Fariss: 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.

References

United Nations, Department of Economic and Social Affairs, Population Division. (2024). World Population Prospects 2024. https://population.un.org/wpp/

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. doi:10.1177/00220027211054432

Singer, J. D., Bremer, S., & Stuckey, J. (1972). Capability distribution, uncertainty, and major power war, 1820-1965. In B. Russett (Ed.), Peace, War, and Numbers (pp. 19-48). Sage.

Singer, J. D. (1988). Reconstructing the Correlates of War dataset on material capabilities of states, 1816-1985. International Interactions, 14, 115-132.

Examples

pop_wpp <- load_population_data(1990, 2015, dataset = "wpp", coding_system = "cow")

pop_nmc <- load_population_data(1900, 2015, dataset = "nmc", coding_system = "cow")

Load V-Dem data

Description

Loads selected country-year variables from the V-Dem dataset provided by the vdemdata package. The returned data can use either COW or Gleditsch-Ward country codes.

Usage

load_vdem_data(
  vars = NULL,
  start_year = 1945,
  end_year = 2019,
  coding_system = c("cow", "gw")
)

Arguments

Details

This function requires the vdemdata package. If it is not installed, install it with:

remotes::install_github("vdeminstitute/vdemdata"). Because vdemdata is not distributed through CRAN, it is always checked conditionally.

For coding_system = "gw", V-Dem COW codes are converted to Gleditsch-Ward codes using countrycode::countrycode().

Value

A data frame with country-year V-Dem indicators. If coding_system = "cow", the data frame contains a cow column. If coding_system = "gw", it contains a gw column.

Source

Varieties of Democracy (V-Dem) Project. Please cite V-Dem when using these data.

References

Coppedge, M., Gerring, J., Knutsen, C. H., Lindberg, S. I., Teorell, J., Altman, D., Bernhard, M., Fish, M. S., Glynn, A., Hicken, A., et al. (2025). V-Dem [Country-Year/Country-Date] Dataset v15. Varieties of Democracy.

Examples

if (requireNamespace("vdemdata", quietly = TRUE)) {
vdem_cow <- load_vdem_data(coding_system = "cow")

vdem_selected <- load_vdem_data(
  vars = c("v2x_polyarchy", "v2x_libdem", "v2x_rule"),
  coding_system = "cow"
)

vdem_gw <- load_vdem_data(
  vars = c("v2x_polyarchy", "v2x_libdem"),
  coding_system = "gw"
)
}

Mark every character column of a data frame as UTF-8

Description

Mark every character column of a data frame as UTF-8

Usage

mark_utf8(data)

Arguments

Details

Several bundled sources (NAVCO 1.3/2.1, Beissinger, CSRA) contain genuinely UTF-8-encoded text (e.g. curly apostrophes in campaign names like "Student's Anti-Chun Protest") that R leaves tagged as Encoding() == "unknown" after loading, whether from an .RData file or readr::read_csv() without an explicit locale. An "unknown" encoding is treated as the platform's native encoding wherever it's next converted – harmless on macOS/Linux, where native is already UTF-8, but on Windows this silently corrupts the string (observed as an embedded nul byte, which makes ⁠R CMD check⁠'s vignette rebuild fail outright). Explicitly tagging the bytes as UTF-8, which they already are, avoids that native-encoding guess entirely.

Value

data, with Encoding() set to "UTF-8" on every element of every character column.

Plot country-year onset/event coverage of a binary variable

Description

Draws a country-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 state does not appear in panel at all (e.g. before independence) or var is NA are left blank. Useful for eyeballing when and where events (e.g. conflict onsets) actually occurred, as opposed to just where a source has any data.

Usage

plot_coverage(panel, var, drop_empty = TRUE, show_labels = TRUE)

Arguments

Value

A ggplot object (one tile per country-year, filled by "Event" / "No event", with unobserved country-years left blank). States are ordered top-to-bottom by their number of events, most first. Requires the ggplot2 package.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  build_states_panel(1990, 2015, coding_system = "cow") |>
    add_conflict("ucdp_prio") |>
    plot_coverage("ucdp_prio_onset")

  build_states_panel(1990, 2015, coding_system = "cow") |>
    add_conflict("ucdp_prio") |>
    plot_coverage("ucdp_prio_onset", show_labels = FALSE)
}

Compare regional coverage across conflict/campaign datasets

Description

Draws a grouped bar chart of the regional distribution of events (World Bank 7-region classification) for any set of conflict_data() campaign or episode datasets, in the style of Guseinov, Ustyuzhanin, and Korotayev (2026), Figures 1-3. Comparing several datasets this way shows whether they cover similar parts of the world, or whether one systematically over/under-represents a region relative to the others.

Usage

plot_regional_coverage(
  datasets,
  start_year,
  end_year,
  coding_system = c("cow", "gw"),
  metric = c("share", "count")
)

Arguments

Value

A ggplot object. Requires the ggplot2 package.

Source

Guseinov, R., Ustyuzhanin, V., & Korotayev, A. (2026). Talking about the [same] revolution? A comparative analysis of main datasets of revolutionary events. Defence and Peace Economics, 1–31. doi:10.1080/10242694.2026.2704178

References

Guseinov, R., Ustyuzhanin, V., & Korotayev, A. (2026). Talking about the [same] revolution? A comparative analysis of main datasets of revolutionary events. Defence and Peace Economics, 1-31. doi:10.1080/10242694.2026.2704178

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_regional_coverage(
    c("navco1.3", "navco2.1", "beissinger", "csra"),
    start_year = 1950, end_year = 2013
  )
}

Compare temporal coverage across conflict/campaign datasets

Description

Draws a line chart of the number of events per time period for any set of conflict_data() campaign or episode datasets, in the style of Guseinov, Ustyuzhanin, and Korotayev (2026), Figures 4-5. Comparing several datasets this way shows whether they track the same broad historical trends, and where one dataset picks up a surge or lull that the others miss.

Usage

plot_temporal_coverage(
  datasets,
  start_year,
  end_year,
  coding_system = c("cow", "gw"),
  period_length = 5,
  by_region = FALSE
)

Arguments

Value

A ggplot object. Requires the ggplot2 package.

Source

Guseinov, R., Ustyuzhanin, V., & Korotayev, A. (2026). Talking about the [same] revolution? A comparative analysis of main datasets of revolutionary events. Defence and Peace Economics, 1–31. doi:10.1080/10242694.2026.2704178

References

Guseinov, R., Ustyuzhanin, V., & Korotayev, A. (2026). Talking about the [same] revolution? A comparative analysis of main datasets of revolutionary events. Defence and Peace Economics, 1-31. doi:10.1080/10242694.2026.2704178

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_temporal_coverage(
    c("navco1.3", "navco2.1", "beissinger", "csra"),
    start_year = 1950, end_year = 2013
  )
}

Load an RData file from package extdata

Description

Load an RData file from package extdata

Usage

read_rdata_from_extdata(filename)

Arguments

Value

The single object stored in the .RData file.

Parse one wide SIPRI military expenditure sheet into long format

Description

Parse one wide SIPRI military expenditure sheet into long format

Usage

read_sipri_sheet(path, sheet)

Arguments

Value

A data frame with country, year, value.

Return a typed missing value for an all-missing maximum

Description

Return a typed missing value for an all-missing maximum

Usage

safe_max(x)

Arguments

Value

A length-one vector of the same type as x: the maximum of the non-missing values, or NA if there are none.

Average a vector while preserving all-missing groups

Description

Average a vector while preserving all-missing groups

Usage

safe_mean(x)

Arguments

Value

A length-one numeric: the mean of the non-missing values, or NA_real_ if there are none.

Sum a vector while preserving all-missing groups

Description

Sum a vector while preserving all-missing groups

Usage

safe_sum(x)

Arguments

Value

A length-one numeric: the sum of the non-missing values, or NA_real_ if there are none.

Wrap long axis labels onto multiple lines

Description

Wrap long axis labels onto multiple lines

Usage

wrap_labels(labels, width = 12)

Arguments

Value

labels, each wrapped at word boundaries and joined with ⁠\n⁠.