This vignette provides a brief overview of the acledR package. You can find more detailed explanations and examples under the ‘Using acledR’ tab. For general information on ACLED’s methodology, please visit ACLED’s Knowledge Base.
The main objectives of this package are:
- Facilitating access to ACLED data via ACLED’s API
- Simplifying the manipulation of ACLED data
You can begin by installing and then loading the package:
# Install acledR
install.packages("acledR") # from CRAN
devtools::install_github("ACLED/acledR") # or from github.
# Load acledR
library(acledR)Requesting data from ACLED’s API - acled_api()
After authenticating your credentials, you can request data from the
API using the acled_api() function. This function accepts
several fields for filtering and formatting ACLED data. As a running
example, let’s request all events in Argentina throughout 2022:
argentinian_data <- acled_api(
# Email address associated with your ACLED account
email = Sys.getenv("ACLED_API_EMAIL"),
# Password associated with your ACLED account. If left blank, you will be prompted to enter interactively.
password = Sys.getenv("ACLED_API_PASSWORD"),
# Country of interest
country = "Argentina",
# Earliest date for requested events
start_date ="2022-01-01",
# Last date for requested events
end_date = "2022-12-31",
# Request 'inter codes' in numeric rather than text form
inter_numeric = TRUE
)Note that while this example uses only five arguments
(country, start_date, end_date,
inter_numeric, and prompt),
acled_api() accepts several other useful arguments,
descriptions of which can be found in
vignette("acled_api").
The acled_api() function does not place constraints on
the amount of data requested. As a result, users are able to make
potentially very large requests (e.g. events for all countries and years
at once) which might strain ACLED’s API. For performance reasons,
acled_api() breaks large requests into multiple smaller
requests. You can find more about how acled_api() subsets
requests by visiting in the acled_api() vignette.
Updating ACLED Data - acled_update()
ACLED data are regularly updated. You can ensure that your own
dataset remains current by using the acled_update()
function. acled_update() is designed to handle the
intricacies of updating your ACLED dataset, accounting for new events,
modifications to existing events, and event deletions.
To update your dataset, provide the acled_update
function a dataframe of your old dataset. Note that there are other
options providing more control over how your dataset is updated, more
information for which can be found in the
vignette("acled_update").
Here is an example of how you can use acled_update() to
update an old dataset:
new_data <- acled_update(acledR::acled_old_deletion_dummy,
email = Sys.getenv("ACLED_API_EMAIL"),
password = Sys.getenv("ACLED_API_PASSWORD"),
inter_numeric = TRUE,
prompts = FALSE)Transforming ACLED Data - acled_transform_*
ACLED data has a unique structure which can complicate data
manipulation. The acledR package provides a suite of
functions to simplify this process. You can find a more in-depth
treatment of ACLED’s data transformation functions by visiting the
vignette("acled_transformations").
1. Reshaping Data: Wide to Long Format -
acled_transform_longer()
The acled_transform_longer() function transforms ACLED
data from a wide format, where multiple actors are represented in each
row, to a long format, with separate rows for each actor. This is
particularly useful for actor-based analyses.
long_data <- acled_transform_longer(acledR::acled_old_dummy, type = "full_actors")
head(long_data)
#> # A tibble: 6 × 29
#> event_id_cnty event_date year time_precision disorder_type event_type
#> <chr> <date> <dbl> <dbl> <chr> <chr>
#> 1 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> 2 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> 3 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> 4 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> 5 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> 6 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> # ℹ 23 more variables: sub_event_type <chr>, type_of_actor <chr>, actor <chr>,
#> # inter_type <chr>, inter <dbl>, interaction <dbl>, civilian_targeting <chr>,
#> # iso <dbl>, region <chr>, country <chr>, admin1 <chr>, admin2 <chr>,
#> # admin3 <lgl>, location <chr>, latitude <dbl>, longitude <dbl>,
#> # geo_precision <dbl>, source <chr>, source_scale <chr>, notes <chr>,
#> # fatalities <dbl>, tags <chr>, timestamp <dbl>You can specify the type of transformation using the type argument,
choosing from full_actors, main_actors,
assoc_actors, or source. For instance,
specifying full_actors will result in you transforming the
data frame such that every actor and associate actor for a given event
is represented in a separate row. This function provides flexibility and
control over the transformation process, allowing you to tailor the data
structure to your specific needs.
2. Reshaping Data: Long to Wide Format -
acled_transform_wider()
Conversely, the acled_transform_wider() function enables
you to pivot your data back to a wide format. This function may be
useful if you used acled_transform_longer() and wish to
revert to the original data structure.
wide_data <- acled_transform_wider(long_data, type = "full_actors")
head(wide_data)
#> # A tibble: 6 × 31
#> event_id_cnty event_date year time_precision disorder_type event_type
#> <chr> <date> <dbl> <dbl> <chr> <chr>
#> 1 ARG10295 2022-06-01 2022 1 Demostrations Protests
#> 2 ARG10296 2022-06-01 2022 1 Demostrations Protests
#> 3 ARG10297 2022-06-01 2022 1 Demostrations Protests
#> 4 ARG10298 2022-06-01 2022 1 Demostrations Protests
#> 5 ARG10299 2022-06-01 2022 1 Demostrations Protests
#> 6 ARG10300 2022-06-02 2022 1 Demostrations Protests
#> # ℹ 25 more variables: sub_event_type <chr>, actor1 <chr>, assoc_actor_1 <chr>,
#> # inter1 <dbl>, actor2 <chr>, assoc_actor_2 <chr>, inter2 <dbl>,
#> # interaction <dbl>, civilian_targeting <chr>, iso <dbl>, region <chr>,
#> # country <chr>, admin1 <chr>, admin2 <chr>, admin3 <lgl>, location <chr>,
#> # latitude <dbl>, longitude <dbl>, geo_precision <dbl>, source <chr>,
#> # source_scale <chr>, notes <chr>, fatalities <dbl>, tags <chr>,
#> # timestamp <dbl>Like its counterpart, this function requires the data and type arguments.
3. Converting Interaction Codes -
acled_transform_interaction()
The acled_transform_interaction() function allows you to
convert between numeric and text interaction codes, facilitating easier
interpretation and analysis of ACLED data. The function requires your
ACLED dataset and an optional boolean argument only_inters,
which determines whether to include only inter1 and
inter2 columns or also the interaction column
in the output. By default, only_inters is set to
FALSE. Note further that the acled_api()
function returns interaction codes as text strings by default, making
this function most useful when the original API call included the
parameter value inter_numeric = TRUE, as in the running
example.
transformed_data <- acled_transform_interaction(acledR::acled_old_dummy)
# Note the inter1 and inter2 columns
head(transformed_data)
#> # A tibble: 6 × 31
#> event_id_cnty event_date year time_precision disorder_type event_type
#> <chr> <date> <dbl> <dbl> <chr> <chr>
#> 1 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> 2 ARG10626 2022-06-30 2022 1 Demostrations Protests
#> 3 ARG10618 2022-06-30 2022 1 Demostrations Protests
#> 4 ARG10615 2022-06-30 2022 1 Demostrations Protests
#> 5 ARG10627 2022-06-30 2022 1 Demostrations Protests
#> 6 ARG10625 2022-06-30 2022 1 Demostrations Protests
#> # ℹ 25 more variables: sub_event_type <chr>, actor1 <chr>, assoc_actor_1 <chr>,
#> # inter1 <chr>, actor2 <chr>, assoc_actor_2 <chr>, inter2 <chr>,
#> # interaction <chr>, civilian_targeting <chr>, iso <dbl>, region <chr>,
#> # country <chr>, admin1 <chr>, admin2 <chr>, admin3 <lgl>, location <chr>,
#> # latitude <dbl>, longitude <dbl>, geo_precision <dbl>, source <chr>,
#> # source_scale <chr>, notes <chr>, fatalities <dbl>, tags <chr>,
#> # timestamp <dbl>