Add estimated latent territorial threat to a data frame

add_latent_territorial_threat() allows you to add estimates of latent, external territorial threat to a dyad-year, leader-year, or leader-dyad-year, or state-year data frame. The estimates come by way of Miller (2022).

Usage

add_latent_territorial_threat(data, keep)

Arguments

data

a data frame with appropriate peacesciencer attributes

keep

an optional parameter, specified as a character vector, about what capability estimates the user wants to return from this function. If not specified, everything from the underlying capabilities data is returned.

Value

add_latent_territorial_threat() takes a data frame and adds estimates of latent, external territorial threat derived from a random item response model (as described by Miller (2022)).

Details

The data are stored in terrthreat in this package, which also communicates what the variables are and what they mean in the case of overlapping column names. Miller (2022) describes the random item response model in more detail.

The standard caveat applies that the data are fundamentally state-year (though derived from dyad-year analyses). Extensions to leader-level data sets should be understood as approximate. For example, it's reasonable to infer the territorial threat for Germany under Friedrich Ebert in 1918 would differ from what Wilhelm II would've experienced in the same year. However, the data would have no way of knowing that (as they are).

The state-year nature of the data also carry implications for its use in dyad-year analyses. The function returns estimates of state-year levels of territorial threat for the first state and second state in the dyad, and not the level of territorial threat between each state in the dyad for the given year.

The keep argument must include one or more of the capabilities estimates included in terrthreat. Otherwise, it will return an error that it cannot subset columns that do not exist.

References

Miller, Steven V. 2022. "A Random Item Response Model of External Territorial Threat, 1816-2010" Journal of Global Security Studies 7(4): ogac012.

Author

Steven V. Miller

Examples

# \donttest{
# just call `library(tidyverse)` at the top of the your script
create_stateyears() |> add_latent_territorial_threat(keep=c('lterrthreat'))
#> Joining with `by = join_by(ccode, year)`
#> # A tibble: 17,511 × 4
#>    ccode cw_name                   year lterrthreat
#>    <dbl> <chr>                    <dbl>       <dbl>
#>  1     2 United States of America  1816       0.268
#>  2     2 United States of America  1817       0.190
#>  3     2 United States of America  1818       0.266
#>  4     2 United States of America  1819       0.192
#>  5     2 United States of America  1820       0.150
#>  6     2 United States of America  1821       0.146
#>  7     2 United States of America  1822       0.149
#>  8     2 United States of America  1823       0.146
#>  9     2 United States of America  1824       0.137
#> 10     2 United States of America  1825       0.132
#> # ℹ 17,501 more rows
# }