Get Started

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:

  1. Facilitating access to ACLED data via ACLED’s API
  2. Simplifying the manipulation of ACLED data

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)

Authenticating your credentials - 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.

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(
  # 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.

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, 
                         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>