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:
This package was designed with the following workflow in mind:
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)acled_access()ACLED API access requires an API key for authentication. To register for API access, please visit ACLED’s Access Portal here. You can also find a detailed guide on creating your account and obtaining your API key in ACLED’s Access Guide.
Once you are registered, we encourage authenticating your credentials
using the acled_access() function. Using this function both
ensures that your credentials are working as intended and saves them in
your R environment, eliminating the need for repeated authentication
with each API request.
acled_access(email = "email@example.com", key = "your_key") # This is an example, you will need to input your credentials.If the authentication was successful, you will find a message in the console stating that your credentials were authorized.
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(
# 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,
# Turn off acled_api() interactive prompt
prompt = FALSE
)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"). If you do not use the
acled_access function to store your credentials, you will
also need to specify your email and API key in each request.
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.
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:
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").
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.
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.
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>