| Title: | Manipulate ACLED Data |
|---|---|
| Description: | Tools working with data from ACLED (Armed Conflict Location and Event Data). Functions include simplified access to ACLED's API (<https://apidocs.acleddata.com/>), methods for keeping local versions of ACLED data up-to-date, and functions for common ACLED data transformations. |
| Authors: | Armed Conflict Location and Event Data ACLED [cph], Trey Billing [aut, cre], Lucas Fagliano [aut], Katayoun Kishi [ctb] |
| Maintainer: | Trey Billing <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.0 |
| Built: | 2025-02-26 14:28:24 UTC |
| Source: | https://github.com/dtacled/acledr |
Simple function to authenticate and store (through Sys.setenv()) ACLED access key for the acled_api() function. If email and key is stored via acled_access, the email and key arguments for acled_api can be NULL.
acled_access(email, key)acled_access(email, key)
email |
This is the email that you register in the ACLED Access portal (https://developer.acleddata.com/) |
key |
This is the key generated by the ACLED Access portal. |
Returns a success message if ACLED credentials are successfully authorized
ACLED API Access guide https://acleddata.com/download/35300/
Other API and Access:
acled_api(),
acled_deletions_api(),
acled_update()
## Not run: acled_access(email = "your_email", key = "your_key") Sys.getenv("acled_email") Sys.getenv("acled_key") ## End(Not run)## Not run: acled_access(email = "your_email", key = "your_key") Sys.getenv("acled_email") Sys.getenv("acled_key") ## End(Not run)
This function allows users to easily request data from the ACLED API. Users can include variables such as country, regions, dates of interest and the format (monadic or dyadic). The function returns a tibble of the desired ACLED events.
acled_api( email = NULL, key = NULL, country = NULL, regions = NULL, start_date = floor_date(Sys.Date(), "year") - years(1), end_date = Sys.Date(), timestamp = NULL, event_types = NULL, population = "none", inter_numeric = FALSE, monadic = FALSE, ..., acled_access = TRUE, prompt = TRUE, log = FALSE )acled_api( email = NULL, key = NULL, country = NULL, regions = NULL, start_date = floor_date(Sys.Date(), "year") - years(1), end_date = Sys.Date(), timestamp = NULL, event_types = NULL, population = "none", inter_numeric = FALSE, monadic = FALSE, ..., acled_access = TRUE, prompt = TRUE, log = FALSE )
email |
character string. Email associated with your ACLED account registered at https://developer.acleddata.com. |
key |
character string. Access key associated with your ACLED account registered at https://developer.acleddata.com. |
country |
character vector. Default is NULL, which will return events for all countries. Pass a vector of countries names to retrieve events from specific countries. The list of ACLED countries. names may be found via acledR::acled_countries. |
regions |
vector of region names (character) or region codes (numeric). Default is NULL, which will return events for all regions. Pass a vector of regions names or codes to retrieve events from countries. within specific regions. The list of ACLED regions may be found via acledR::acled_regions. |
start_date |
character string. Format 'yyyy-mm-dd'. The earliest date for which to return events. The default is |
end_date |
character string. Format 'yyyy-mm-dd'. The latest date for which to return events. The default is Sys.Date(), which is the most present date. |
timestamp |
numerical or character string. Provide a date or datetime written as either a character string of yyyy-mm-dd or as a numeric Unix timestamp to access all events added or updated after that date. |
event_types |
vector of one or more event types (character). Default is NULL, which will return data for all event types. To reurn data for only specific event types, request one or more of the following options (not case sensitive): Battles, Violence against civilians, Protests, Riots, Strategic Developments, and Explosions/Remote violence. |
population |
character. Specify whether to return population estimates for each event. It accepts three options: "none" (default), "best", and "full". |
inter_numeric |
logical. If FALSE (default), interaction code columns (inter1, inter2, and interaction) returned as strings describing the actor types/interactions. If TRUE, the values are returned as numeric values. |
monadic |
logical. If FALSE (default), returns dyadic data. If TRUE, returns monadic actor1 data. |
... |
string. Any additional parameters that users would like to add to their API calls (e.g. interaction or ISO) |
acled_access |
logical. If TRUE (default), you have used the acled_access function and the email and key arguments are not required. |
prompt |
logical. If TRUE (default), users will receive an interactive prompt providing information about their call (countries requested, number of estimated events, and number of API calls required) and asking if they want to proceed with the call. If FALSE, the call continues without warning, but the call is split and returns a message specifying how many calls are being made. |
log |
logical. If TRUE, it provides a dataframe with the countries and days requested, and how many calls it entails. The dataframe is provided INSTEAD of the normal ACLED dataset. |
Returns a tibble of of ACLED events.
ACLED API guide. https://apidocs.acleddata.com/
Other API and Access:
acled_access(),
acled_deletions_api(),
acled_update()
## Not run: # Get all the events coded by ACLED in Argentina from 01/01/2022 until 02/01/2022 # in dyadic-wide form argen_acled <- acled_api( email = "your_email", key = "your_key", country = "Argentina", start_date = "2022-01-01", end_date = "2022-02-01", acled_access = FALSE ) # tibble with all the events from Argentina where each row is one event. argen_acled # Get all events coded by ACLED in the Caribbean from 01/01/2022 to 10/01/2022 # in monadic-long form using email and key saved in environment acled_access(email = "your_email", key = "your_key") carib_acled <- acled_api( regions = "Caribbean", start_date = "2022-01-01", end_date = "2022-01-10", monadic = TRUE, acled_access = TRUE ) ## Tibble with all the events from the Caribbean where each row is one actor carib_acled ## End(Not run)## Not run: # Get all the events coded by ACLED in Argentina from 01/01/2022 until 02/01/2022 # in dyadic-wide form argen_acled <- acled_api( email = "your_email", key = "your_key", country = "Argentina", start_date = "2022-01-01", end_date = "2022-02-01", acled_access = FALSE ) # tibble with all the events from Argentina where each row is one event. argen_acled # Get all events coded by ACLED in the Caribbean from 01/01/2022 to 10/01/2022 # in monadic-long form using email and key saved in environment acled_access(email = "your_email", key = "your_key") carib_acled <- acled_api( regions = "Caribbean", start_date = "2022-01-01", end_date = "2022-01-10", monadic = TRUE, acled_access = TRUE ) ## Tibble with all the events from the Caribbean where each row is one actor carib_acled ## End(Not run)
Codebook for ACLED data
acled_codebookacled_codebook
A data frame:
Variable names
Text description of each variable
Text description of values for each variable
Other Data:
acled_countries,
acled_event_categories,
acled_interaction_codes,
acled_multipliers,
acled_old_deletion_dummy,
acled_old_dummy,
acled_regions
ACLED country names, regions, and coding start year
acled_countriesacled_countries
A data frame:
Country names
Region names
First year coded by ACLED
Other Data:
acled_codebook,
acled_event_categories,
acled_interaction_codes,
acled_multipliers,
acled_old_deletion_dummy,
acled_old_dummy,
acled_regions
This function allows users to pull deleted ACLED event IDs from the Deletions API.
acled_deletions_api( email = NULL, key = NULL, date_deleted = NULL, acled_access = TRUE, log = FALSE )acled_deletions_api( email = NULL, key = NULL, date_deleted = NULL, acled_access = TRUE, log = FALSE )
email |
character string. Email associated with your ACLED account registered at https://developer.acleddata.com. |
key |
character string. Access key associated with your ACLED account registered at https://developer.acleddata.com. |
date_deleted |
character string. Format 'yyyy-mm-dd' or Unix timestamp. The query will return all deleted events including and after the requested date/timestamp. |
acled_access |
logical. If TRUE it means that you have utilized the acled_access function and there is no need for the email and key arguments. |
log |
Only for testing purposes: you can use this to check if all the variables in your call were handled properly. |
Returns a tibble of ACLED data with columns for event_id_cnty and deleted_timestamp.
Other API and Access:
acled_access(),
acled_api(),
acled_update()
## Not run: # Request deleted ACLED events since January 1, 2022 acled_deletions_api(date_deleted = "2022-01-01", acled_acess = TRUE) ## End(Not run)## Not run: # Request deleted ACLED events since January 1, 2022 acled_deletions_api(date_deleted = "2022-01-01", acled_acess = TRUE) ## End(Not run)
ACLED event and sub-event types, grouped by category
acled_event_categoriesacled_event_categories
A data frame:
ACLED event type
ACLED sub-event type
Dummy indicator for whether sub-event type falls within political violence
Dummy indicator for whether sub-event type falls within organized political violence
Dummy indicator for whether sub-event type falls within disorder
Dummy indicator for whether sub-event type falls within demonstrations
Other Data:
acled_codebook,
acled_countries,
acled_interaction_codes,
acled_multipliers,
acled_old_deletion_dummy,
acled_old_dummy,
acled_regions
ACLED interaction and actor types
acled_interaction_codesacled_interaction_codes
A data frame:
Actor type
Numeric equivalent found in the inter1 and inter2 column.
Other Data:
acled_codebook,
acled_countries,
acled_event_categories,
acled_multipliers,
acled_old_deletion_dummy,
acled_old_dummy,
acled_regions
A dataframe with additional information for each country, only for the purpose of estimating events.
acled_multipliersacled_multipliers
A data frame:
Country names
Bin of event frequency
Year corresponding to the bin
Average monthly of the bin
Other Data:
acled_codebook,
acled_countries,
acled_event_categories,
acled_interaction_codes,
acled_old_deletion_dummy,
acled_old_dummy,
acled_regions
Large dataset of multiple regions and countries, purposefully including deleted/modified events.
acled_old_deletion_dummyacled_old_deletion_dummy
A data frame:
An unique individual identifier by number and country acronym (updated annually)
The day, month and year on which an event took place
The year in which an event took place
A numeric code indicating the level of certainty of the date coded for the event
Type of disorder associated with the event and sub event type
The type of event
The type of sub-event
The named actor involved in the event. Note: Actor 1 and Actor 2 do not imply directionality (e.g. attacker or defender)
The named actor associated with or identifying actor1
A numeric code indicating the type of actor1
The named actor involved in the event. Note: Actor 1 and Actor 2 do not imply directionality (e.g. attacker or defender)
The named actor associated with or identifying actor1
A numeric code indicating the type of actor1
A numeric code indicating the interaction between types of actor1 and actor2
Column referencing the presence of civilian targeting
A numeric code for each individual country
The region of the world where the event took place
The country in which the event took place
The largest sub-national administrative region in which the event took place
The second largest sub-national administrative region in which the event took place
The third largest sub-national administrative region in which the event took place
The location in which the event took place
The latitude of the location
The longitude of the location
A numeric code indicating the level of certainty of the location coded for the event
The source of the event report
The scale (local, regional, national, international) of the source
A short description of the event
The number of reported fatalities which occurred during the event
Tags associated with the event.
Numeric code of time
Other Data:
acled_codebook,
acled_countries,
acled_event_categories,
acled_interaction_codes,
acled_multipliers,
acled_old_dummy,
acled_regions
Small dataset of events in Argentina, purposefully including events which are currently deleted/modified.
acled_old_dummyacled_old_dummy
A data frame:
An unique individual identifier by number and country acronym (updated annually)
The day, month and year on which an event took place
The year in which an event took place
A numeric code indicating the level of certainty of the date coded for the event
Type of disorder associated with the event and sub event type
The type of event
The type of sub-event
The named actor involved in the event. Note: Actor 1 and Actor 2 do not imply directionality (e.g. attacker or defender)
The named actor associated with or identifying actor1
A numeric code indicating the type of actor1
The named actor involved in the event. Note: Actor 1 and Actor 2 do not imply directionality (e.g. attacker or defender)
The named actor associated with or identifying actor1
A numeric code indicating the type of actor1
A numeric code indicating the interaction between types of actor1 and actor2
Column referencing the presence of civilian targeting
A numeric code for each individual country
The region of the world where the event took place
The country in which the event took place
The largest sub-national administrative region in which the event took place
The second largest sub-national administrative region in which the event took place
The third largest sub-national administrative region in which the event took place
The location in which the event took place
The latitude of the location
The longitude of the location
A numeric code indicating the level of certainty of the location coded for the event
The source of the event report
The scale (local, regional, national, international) of the source
A short description of the event
The number of reported fatalities which occurred during the event
Tags associated with the event.
Numeric code of time
Other Data:
acled_codebook,
acled_countries,
acled_event_categories,
acled_interaction_codes,
acled_multipliers,
acled_old_deletion_dummy,
acled_regions
ACLED region names, region numbers, and coding start dates
acled_regionsacled_regions
A data frame:
Region number
Region names
First date (yyyy-mm-dd) coded by ACLED
Other Data:
acled_codebook,
acled_countries,
acled_event_categories,
acled_interaction_codes,
acled_multipliers,
acled_old_deletion_dummy,
acled_old_dummy
This function addresses some of the conflicts of rounding in R, especially when trying to round up.
acled_rounding(num, digits = 0)acled_rounding(num, digits = 0)
num |
int. This is the number we are trying to round. |
digits |
int. Where do we want to round up. It accepts 0 (whole number), 1 (tenth place), 2 (hundredths), etc. |
This function is meant to address the problem of rounding in R where the approach is always round to even. The function is meant to round things following the simple rule. If the decimal is 5+ then round up, if not round down. With the 'digits' argument, one can set up the specificity of the rounding, 0= whole number, 1 = tenth place, 2=hundreds place, and so on.
A rounded numeric value
x1 <- 1.569 x2 <- 104.530 x3 <- 54.430 x4 <- 205.49999 acled_rounding(x1) acled_rounding(x2) acled_rounding(x3) acled_rounding(x4)x1 <- 1.569 x2 <- 104.530 x3 <- 54.430 x4 <- 205.49999 acled_rounding(x1) acled_rounding(x2) acled_rounding(x3) acled_rounding(x4)
This function allows users to change from numeric interaction codes (i.e. 1, 2, 3, etc) to string interaction codes (i.e. State Forces, Rebel Group, etc.)
acled_transform_interaction(df, only_inters = FALSE)acled_transform_interaction(df, only_inters = FALSE)
df |
dataframe. ACLED data including at least inter1, inter2 columns. If |
only_inters |
boolean. Option whether to include the interaction column in the transformation (if TRUE) or to only use inter1 and inter2 (if FALSE). |
Returns a tibble of of ACLED events with modified inter1, inter2 and potentially interaction columns .
Other Data Manipulation:
acled_transform_longer(),
acled_transform_wider()
## Not run: # Load data frame argen_acled <- acled_api( email = "your_email", key = "your_key", country = "Argentina", start_date = "2022-01-01", end_date = "2022-02-01", acled_access = FALSE ) # Transform the interactions argen_acled_transformed <- acled_transformation_interaction(argen_acled, only_inters = F) ## End(Not run)## Not run: # Load data frame argen_acled <- acled_api( email = "your_email", key = "your_key", country = "Argentina", start_date = "2022-01-01", end_date = "2022-02-01", acled_access = FALSE ) # Transform the interactions argen_acled_transformed <- acled_transformation_interaction(argen_acled, only_inters = F) ## End(Not run)
Function to convert your ACLED's API calls (if dyadic) into desired monadic forms.
acled_transform_longer(data, type = "full_actors")acled_transform_longer(data, type = "full_actors")
data |
dataframe or tibble containing your dataset. |
type |
character string. One of five types: full_actors, main_actors, assoc_actors, source, or all.
|
A tibble with the data transformed into long form.
Other Data Manipulation:
acled_transform_interaction(),
acled_transform_wider()
## Not run: # argen_acled <- acled_api(country = "Argentina",start_date = "2022-01-01", # end_date="2022-02-01", acled_access = T, prompt = F) # argen_acled_long_actors <- acled_transform_wide_to_long(argen_acled, # type = "full_actor") # Transforming the data # nrow(argen_acled_long_actors) # Number of rows in the dataset # [1] 263 # Long form # nrow(argen_acled) ) # Number of rows in the dataset # [1] 145 # Wide form ## End(Not run)## Not run: # argen_acled <- acled_api(country = "Argentina",start_date = "2022-01-01", # end_date="2022-02-01", acled_access = T, prompt = F) # argen_acled_long_actors <- acled_transform_wide_to_long(argen_acled, # type = "full_actor") # Transforming the data # nrow(argen_acled_long_actors) # Number of rows in the dataset # [1] 263 # Long form # nrow(argen_acled) ) # Number of rows in the dataset # [1] 145 # Wide form ## End(Not run)
Function to convert your ACLED's API calls (if monadic) back into the original dyadic forms.
acled_transform_wider(data, type = "full_actors")acled_transform_wider(data, type = "full_actors")
data |
a dataframe or tibble containing your dataset. |
type |
a character string. One of five types: full_actors, main_actors, assoc_actors, source, or all.
|
A tibble with the data transformed back into wide form.
Other Data Manipulation:
acled_transform_interaction(),
acled_transform_longer()
## Not run: # argen_acled <- acled_api(country = "Argentina",start_date = "2022-01-01", # end_date="2022-02-01", acled_access = T, prompt = F) # argen_acled_long_actors <- acled_transform_longer(argen_acled, # type = "full_actor") # Transforming the data to long form # argen_acled_wide <- acled_transform_wider(argen_acled_long_actors, # type = "full_actor") # Transforming the data back to wide form # nrow(argen_acled_wide) # Number of rows in the dataset # [1] 145 # Wide form # nrow(argen_acled_long_actors) # Number of rows in the dataset # [1] 263 # Long form ## End(Not run)## Not run: # argen_acled <- acled_api(country = "Argentina",start_date = "2022-01-01", # end_date="2022-02-01", acled_access = T, prompt = F) # argen_acled_long_actors <- acled_transform_longer(argen_acled, # type = "full_actor") # Transforming the data to long form # argen_acled_wide <- acled_transform_wider(argen_acled_long_actors, # type = "full_actor") # Transforming the data back to wide form # nrow(argen_acled_wide) # Number of rows in the dataset # [1] 145 # Wide form # nrow(argen_acled_long_actors) # Number of rows in the dataset # [1] 263 # Long form ## End(Not run)
This function is meant to help you keep your dataset updated, by automatically checking for new and modified events, as well as deleted events (if deleted = TRUE). Note: The function makes new API calls to gather new and modified events.
acled_update( df, start_date = min(df$event_date), end_date = max(df$event_date), additional_countries = "current countries", regions = NULL, event_types = NULL, acled_access = TRUE, email = NULL, key = NULL, inter_numeric = FALSE, deleted = TRUE, prompts = TRUE )acled_update( df, start_date = min(df$event_date), end_date = max(df$event_date), additional_countries = "current countries", regions = NULL, event_types = NULL, acled_access = TRUE, email = NULL, key = NULL, inter_numeric = FALSE, deleted = TRUE, prompts = TRUE )
df |
The dataframe to update, it has to have the same structure as ACLED's dyadic dataframe (i.e. the result of |
start_date |
The first date of events you want to update from.. These are the celling and floor of event_date, not of timestamp. |
end_date |
The last date of events you want to update from. These are the celling and floor of event_date, not of timestamp. |
additional_countries |
string. Additional additional_countries to update your dataset. It defaults to “current countries”, which includes all the additional_countries inside your dataset. |
regions |
string. The regions for which you would like events in your dataset updated. |
event_types |
string. The event types for which you would like events in your dataset updated. |
acled_access |
logical. If you have already used |
email |
character string. Email associated with your ACLED account registered at https://developer.acleddata.com. |
key |
character string. Access key associated with your ACLED account registered at https://developer.acleddata.com. |
inter_numeric |
logical. If FALSE (default), interaction code columns (inter1, inter2, and interaction) returned as strings describing the actor types/interactions. If TRUE, the values are returned as numeric values. Must match the inter type (numeric or string) in the dataframe being updated. |
deleted |
logical. If TRUE (default), the function will also remove deleted events using acled_deletions_api(). |
prompts |
logical. If TRUE (default), users will receive an interactive prompt providing information about their call (additional_countries requested, number of country-days, and number of API calls required) and asking if they want to proceed with the call. If FALSE, the call continues without warning, but the call is split and returns a message specifying how many calls are being made. |
Tibble with updated ACLED data and a newer timestamp.
ACLED Keeping your dataset updated guide. https://acleddata.com/download/35179/
Other API and Access:
acled_access(),
acled_api(),
acled_deletions_api()
## Not run: # Updating dataset to include newer data from Argentina acledR::acled_access(email = "your_email", key = "your_key") new_argen_dataset <- acled_update(acledR::acled_old_dummy, additional_countries = "Argentina", acled_access = TRUE, prompts = FALSE ) ## End(Not run)## Not run: # Updating dataset to include newer data from Argentina acledR::acled_access(email = "your_email", key = "your_key") new_argen_dataset <- acled_update(acledR::acled_old_dummy, additional_countries = "Argentina", acled_access = TRUE, prompts = FALSE ) ## End(Not run)