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:

Facilitating access to ACLED data via ACLED’s API
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.

#> Success! Credentials authorized

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
  )
#> Requesting data for 1 country. Accounting for the requested time period and ACLED coverage dates, this request includes approximately 4,258 events.
#> Processing API request
#> Extracting content from API request

This request returns the following data:

glimpse(argentinian_data)
#> Rows: 2,677
#> Columns: 31
#> $ event_id_cnty      <chr> "ARG12068", "ARG11964", "ARG11965", "ARG12064", "AR…
#> $ event_date         <date> 2022-12-31, 2022-12-30, 2022-12-30, 2022-12-30, 20…
#> $ year               <dbl> 2022, 2022, 2022, 2022, 2022, 2022, 2022, 2022, 202…
#> $ time_precision     <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, …
#> $ disorder_type      <chr> "Political violence", "Demonstrations", "Demonstrat…
#> $ event_type         <chr> "Violence against civilians", "Protests", "Protests…
#> $ sub_event_type     <chr> "Attack", "Peaceful protest", "Peaceful protest", "…
#> $ actor1             <chr> "Police Forces of Argentina (2019-2023)", "Proteste…
#> $ assoc_actor_1      <chr> NA, "Health Workers (Argentina)", NA, "Labor Group …
#> $ inter1             <dbl> 1, 6, 6, 6, 6, 6, 6, 6, 3, 6, 6, 6, 6, 6, 6, 6, 6, …
#> $ actor2             <chr> "Civilians (Argentina)", NA, NA, NA, NA, NA, NA, NA…
#> $ assoc_actor_2      <chr> NA, NA, NA, NA, NA, NA, NA, NA, "Journalists (Argen…
#> $ inter2             <dbl> 7, 0, 0, 0, 0, 0, 0, 0, 7, 0, 0, 0, 0, 0, 0, 0, 0, …
#> $ interaction        <dbl> 17, 60, 60, 60, 60, 60, 60, 60, 37, 60, 60, 60, 60,…
#> $ civilian_targeting <chr> "Civilian targeting", NA, NA, NA, NA, NA, NA, NA, "…
#> $ iso                <dbl> 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32,…
#> $ region             <chr> "South America", "South America", "South America", …
#> $ country            <chr> "Argentina", "Argentina", "Argentina", "Argentina",…
#> $ admin1             <chr> "Buenos Aires", "Chubut", "Santa Fe", "San Juan", "…
#> $ admin2             <chr> "Moreno", "Rawson", "Caseros", "Capital", NA, NA, "…
#> $ admin3             <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ location           <chr> "La Reja", "Rawson", "Casilda", "San Juan", "Buenos…
#> $ latitude           <dbl> -34.6397, -43.2993, -33.0441, -31.5347, -34.6141, -…
#> $ longitude          <dbl> -58.8294, -65.0935, -61.1642, -68.5303, -58.4579, -…
#> $ geo_precision      <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, …
#> $ source             <chr> "La Nacion (Argentina)", "Diario Cronica (Argentina…
#> $ source_scale       <chr> "National", "National", "Subnational", "Subnational…
#> $ notes              <chr> "On 31 December 2022, in La Reja (Buenos Aires), a …
#> $ fatalities         <dbl> 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, …
#> $ tags               <chr> NA, "crowd size=no report", "crowd size=no report",…
#> $ timestamp          <dbl> 1705379976, 1673295342, 1673295342, 1673295342, 171…

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)
#> Requesting data for 169 country. Accounting for the requested time period and ACLED coverage dates, this request includes approximately 144,348 events.
#> Processing API request
#> Extracting content from API request
#> Dataset updated. 
#>  Old number of events: 9000. 
#>  New events: 96395. 
#>  Deleted events: 55. 
#>  Total new & modified events: 102174

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(argentinian_data, 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 ARG12068      2022-12-31  2022              1 Political violence Violence aga…
#> 2 ARG12068      2022-12-31  2022              1 Political violence Violence aga…
#> 3 ARG12068      2022-12-31  2022              1 Political violence Violence aga…
#> 4 ARG12068      2022-12-31  2022              1 Political violence Violence aga…
#> 5 ARG11964      2022-12-30  2022              1 Demonstrations     Protests     
#> 6 ARG11964      2022-12-30  2022              1 Demonstrations     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 ARG10000      2022-04-12  2022              1 Demonstrations Protests  
#> 2 ARG10001      2022-04-12  2022              1 Demonstrations Protests  
#> 3 ARG10002      2022-04-12  2022              1 Demonstrations Protests  
#> 4 ARG10003      2022-04-12  2022              1 Demonstrations Protests  
#> 5 ARG10004      2022-04-12  2022              1 Demonstrations Protests  
#> 6 ARG10005      2022-04-12  2022              2 Demonstrations 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(argentinian_data)

# 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 ARG12068      2022-12-31  2022              1 Political violence Violence aga…
#> 2 ARG11964      2022-12-30  2022              1 Demonstrations     Protests     
#> 3 ARG11965      2022-12-30  2022              1 Demonstrations     Protests     
#> 4 ARG12064      2022-12-30  2022              1 Demonstrations     Protests     
#> 5 ARG12078      2022-12-30  2022              1 Demonstrations     Protests     
#> 6 ARG12079      2022-12-30  2022              1 Demonstrations     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>

Authenticating your credentials - acled_access()

Requesting data from ACLED’s API - acled_api()

Updating ACLED Data - acled_update()

Transforming ACLED Data - acled_transform_*

1. Reshaping Data: Wide to Long Format - acled_transform_longer()

2. Reshaping Data: Long to Wide Format - acled_transform_wider()

3. Converting Interaction Codes - acled_transform_interaction()