diff --git a/NAMESPACE b/NAMESPACE index cbc3588..5693112 100755 --- a/NAMESPACE +++ b/NAMESPACE @@ -4,7 +4,6 @@ export("%>%") export(acled_access) export(acled_api) export(acled_deletions_api) -export(acled_filter_actors) export(acled_rounding) export(acled_transform_interaction) export(acled_transform_longer) diff --git a/R/acled_api.R b/R/acled_api.R index 36fec98..89e9f6a 100755 --- a/R/acled_api.R +++ b/R/acled_api.R @@ -1,10 +1,10 @@ #' @title Request data from ACLED API #' @name acled_api -#' @description This function allows users to easily request data from the ACLED API. Users can include variables such as countries, regions, dates of interest and the type of file (monadic or dyadic). The function returns a tibble of the desired ACLED events. +#' @description 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 type of file (monadic or dyadic). The function returns a tibble of the desired ACLED events. #' @param email character string. Email associated with your ACLED account registered at . #' @param key character string. Access key associated with your ACLED account registered at . -#' @param countries character vector. Default is NULL, which will return events for all countries. Pass a vector of country names to retrieve events from specific countries. The list of ACLED country names may be found via acledR::acled_countries. -#' @param 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. +#' @param 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. +#' @param 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. #' @param start_date character string. Format 'yyyy-mm-dd'. The earliest date for which to return events. The default is `1997-01-01`, which is the earliest date available. #' @param 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. #' @param 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. @@ -13,12 +13,12 @@ #' @param ... string. Any additional parameters that users would like to add to their API calls (e.g. interaction or ISO) #' @param acled_access logical. If TRUE (default), you have used the acled_access function and the email and key arguments are not required. #' @param 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. -#' @param prompt logical. If TRUE (default), users will receive an interactive prompt providing information about their call (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. +#' @param 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. #' @returns Returns a tibble of of ACLED events. #' @family API and Access #' @seealso #' \itemize{ -#' \item ACLED API guide. +#' \item ACLED API guide. #' } #' @examples #' \dontrun{ @@ -26,7 +26,7 @@ #' # 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 = jane.doe.email, key = jane.doe.key, -#' countries = "Argentina", start_date = "2022-01-01", end_date="2022-02-01", +#' 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. @@ -55,7 +55,7 @@ acled_api <- function(email = NULL, key = NULL, - countries = NULL, + country = NULL, regions = NULL, start_date = floor_date(Sys.Date(), "year") - years(1), end_date = Sys.Date(), @@ -83,13 +83,8 @@ acled_api <- function(email = NULL, # Stoppers for typos ---- - if(hasArg("country") | hasArg("Country")){ - stop("Country is not a valid option. Please utilize \"countries\"") - - } - - if(hasArg("Countries")){ - stop("Countries is not a valid option. Please utilize \"countries\", without capitalizing") + if(hasArg("Country")){ + stop("Country is not a valid option. Please utilize \"country\", without capitalizing ") } @@ -142,8 +137,8 @@ acled_api <- function(email = NULL, } key_internal <- paste0("&key=", key) - if(!is.null(countries) & sum(unique(countries) %in% acledR::acled_countries[["country"]]) < length(unique(countries))) { - stop("One or more of the requested countries are not in ACLED's Country list. The full list of countries is available at 'acledR::acled_countries") + if(!is.null(country) & sum(unique(country) %in% acledR::acled_countries[["country"]]) < length(unique(country))) { + stop("One or more of the requested countries are not in ACLED's countries list. The full list of countries is available at 'acledR::acled_countries") } # Checking if regions are input incorrectly ---- @@ -157,17 +152,19 @@ acled_api <- function(email = NULL, # Setup base data to check how many country-days are being requested - if(!is.null(countries) & is.null(regions)) { - df <- acledR::acled_countries %>% - filter(.data$country %in% countries) + if(!is.null(country) & is.null(regions)) { + test <- country - # Subset acled_multipliers (subset is faster than filter in our case) by relevant country & year - ex1_df <- subset(acledR::acled_multipliers, country %in% countries, select = country:avg_month_bin) + df <- acledR::acled_countries %>% + filter(.data$country %in% test) + + # Subset acled_multipliers (subset is faster than filter in our case) by relevant country & year + ex1_df <- subset(acledR::acled_multipliers, country %in% test, select = country:avg_month_bin) ex1_df <- subset(ex1_df, year <= lubridate::year(end_date) & year >= lubridate::year(start_date)) } - else if(is.null(countries) & !is.null(regions)) { + else if(is.null(country) & !is.null(regions)) { if(is.numeric(regions)){ regions <- acledR::acled_regions %>% filter(.data$region %in% regions) %>% @@ -182,15 +179,17 @@ acled_api <- function(email = NULL, } - else if(!is.null(countries) & !is.null(regions)){ + else if(!is.null(country) & !is.null(regions)){ if(is.numeric(regions)){ regions <- acledR::acled_regions %>% filter(.data$region %in% regions) %>% pull(.data$region_name)} + test <- country + df <- acledR::acled_countries %>% - filter((.data$country %in% countries) | (.data$region %in% regions)) + filter((.data$country %in% test) | (.data$region %in% regions)) ex1_df <- subset(acledR::acled_multipliers, country %in% unique(df$country), select = country:avg_month_bin) ex1_df <- subset(ex1_df, year <= lubridate::year(end_date) & year >= lubridate::year(start_date)) @@ -249,6 +248,7 @@ acled_api <- function(email = NULL, ee_events = avg_daily_bin * n_days ) + out <- df %>% mutate(t_start = lubridate::as_date(start_date_check), t_end = lubridate::as_date(end_date_check), @@ -264,19 +264,18 @@ acled_api <- function(email = NULL, # Note for how much data is being requested size_note <- paste("Requesting data for", length(unique(ex1_df$country)), - "countries.", + "country.", "Accounting for the requested time period and ACLED coverage dates, this request includes approximately", format(acled_rounding(sum(ex1_df$ee_events)), big.mark = ","), "events.") message(size_note) - # Approx how many calls are required with 1 call sized at 600k country-days - Increase in the call size thanks to the more approximate approach. - # bcse of my testing, at around 900k the call falls. + # Current ceilling 400k time_units <- ceiling(sum(ex1_df$ee_events) / 400000) # Split call into roughly equally sized groups depending on how many country-days are in each country - # This randomly assigns countries into bins + # This randomly assigns country into bins out_groups <- split(out, sample(1:time_units, nrow(out), replace = T)) if(log == T){ @@ -321,7 +320,7 @@ acled_api <- function(email = NULL, # } # Where - ## Countries + ## country countries_internal <- vector("list", length = length(out_groups)) for(i in 1:length(out_groups)){ @@ -435,6 +434,7 @@ acled_api <- function(email = NULL, event_types_internal, ..., "&limit=0") } + # Loop through the api requests response <- vector("list", length = length(out_groups)) message("Processing API request") diff --git a/R/acled_filter_actors.R b/R/acled_filter_actors.R deleted file mode 100755 index beefe68..0000000 --- a/R/acled_filter_actors.R +++ /dev/null @@ -1,53 +0,0 @@ -#' @title Filter ACLED Data by Actor -#' @name acled_filter_actors -#' @description This function allows users to filter ACLED data by actor. -#' @param df dataframe. ACLED data to filter. -#' @param actors character vector or vector of character strings. Actor name or list of actor names to use for filtering. -#' @param filter_cols character string. Columns to use for filtering. Default is "all", which filters based on all actor columns (i.e. actor1, actor2, assoc_actor_1, assoc_actor_2). "Primary" filters based on actor1 and actor2 column only. -#' @returns Returns a tibble of ACLED data filtered to selected actors. -#' @family Data Manipulation -#' @examples -#' \dontrun{ -#' -#' # Request events from Yemen -#' df_events <- acled_api(countries = "Yemen", -#' start_date = "2022-01-01", -#' end_date = "2022-07-30", -#' monadic = F, -#' acled_access = TRUE) -#' -#' # Create vector of actors of interest -#' yemen_actors <- c('Military Forces of Yemen (2016-) Supreme Political Council', -#' 'Military Forces of Yemen (2012-)') -#' -#' # Filter to selected actors -#' filtered_df <- filter_actors(df = df_events, actors = yemen_actors, filter_cols = 'all') -#' } -#' @md -#' @import dplyr -#' @import stringr -#' @importFrom rlang .data -#' @export - -acled_filter_actors <- function(df, actors, filter_cols='all'){ - if(filter_cols=='all'){ - if(!'assoc_actor_1' %in% names(df) | !'assoc_actor_2' %in% names(df)){ - stop("Dataframe is missing 'assoc_actor_1' or 'assoc_actor_2' column.") - } - - aa_regex <- str_replace_all(actors, '\\(', '\\\\(') - aa_regex <- str_replace_all(aa_regex, '\\)', '\\\\)') - aa_regex <- paste0('((^|; )', paste0(aa_regex, collapse = '($|;)|(^|; )'), '($|;))') - - filtered_df <- df %>% - filter(.data$actor1 %in% actors | .data$actor2 %in% actors | - str_detect(.data$assoc_actor_1, aa_regex) | str_detect(.data$assoc_actor_2, aa_regex)) - } else if (filter_cols=='primary') { - filtered_df <- df %>% - filter(.data$actor1 %in% actors | .data$actor2 %in% actors) - } else { - stop("filter_cols argument must be 'all' or 'primary'.") - } - - return(filtered_df) -} diff --git a/R/acled_transform_interaction.R b/R/acled_transform_interaction.R index df27b03..2d72bb0 100644 --- a/R/acled_transform_interaction.R +++ b/R/acled_transform_interaction.R @@ -10,7 +10,7 @@ #' #' # Load data frame #' argen_acled <- acled_api(email = jane.doe.email, key = jane.doe.key, -#' countries = "Argentina", start_date = "2022-01-01", end_date="2022-02-01", +#' country = "Argentina", start_date = "2022-01-01", end_date="2022-02-01", #' acled_access = FALSE) #' #' # Transform the interactions diff --git a/R/acled_transform_longer.R b/R/acled_transform_longer.R index 05e4903..c62b417 100644 --- a/R/acled_transform_longer.R +++ b/R/acled_transform_longer.R @@ -13,7 +13,7 @@ #' @family Data Manipulation #' @examples #' \dontrun{ -#' #argen_acled <- acled_api(countries = "Argentina",start_date = "2022-01-01", +#' #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, @@ -67,7 +67,11 @@ acled_transform_longer <- function(data,type="full_actors") { mutate(actor = str_trim(actor)) %>% pivot_longer(cols = c("inter1", "inter2"),names_to = "inter_type",values_to = "inter") %>% filter(str_sub(type_of_actor,start=nchar(type_of_actor)) == str_sub(inter_type, start=nchar(inter_type))) %>% - relocate(c("inter_type","inter"),.after="actor") + relocate(c("inter_type","inter"),.after="actor") %>% + # Removing inters when the actor is an assoc_actor_1/2 + mutate(inter = case_when( + str_detect(type_of_actor, "assoc_*") ~ NA, + TRUE ~ inter)) message("Be aware, inter1 and inter2 represent the actor type of actor1 and actor2 respectively.") diff --git a/R/acled_transform_wider.R b/R/acled_transform_wider.R index 1528083..a7ef6a9 100644 --- a/R/acled_transform_wider.R +++ b/R/acled_transform_wider.R @@ -14,7 +14,7 @@ #' @family Data Manipulation #' @examples #' \dontrun{ -#' #argen_acled <- acled_api(countries = "Argentina",start_date = "2022-01-01", +#' #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 @@ -60,12 +60,14 @@ acled_transform_wider <- function(data, type = "full_actors") { # Transform inter into character for collapsing mutate(inter1 = as.character(inter1), inter2 = as.character(inter2)) %>% + mutate(inter1 = replace_na(inter1, ""))%>% + mutate(inter2 = replace_na(inter2, ""))%>% group_by(across(c(-actor1,-actor2, -inter1, -inter2, -assoc_actor_1, -assoc_actor_2))) %>% # Collapse repeated inters and actors summarise(actor1 = str_c(actor1, collapse = ""), actor2 = str_c(actor2, collapse = ""), - inter1 = str_trim(str_remove_all(str_c(inter1, collapse = " "), "9999")), - inter2 = str_trim(str_remove_all(str_c(inter2, collapse = " "), "9999")), + inter1 = str_trim(str_remove_all(str_c(inter1, collapse = " "), "9999|\\s0\\s")), + inter2 = str_trim(str_remove_all(str_c(inter2, collapse = " "), "9999|\\s0\\s")), assoc_actor_1 = str_c(assoc_actor_1, collapse = ""), assoc_actor_2 = str_c(assoc_actor_2, collapse = "")) %>% ungroup() %>% @@ -76,6 +78,7 @@ acled_transform_wider <- function(data, type = "full_actors") { actor1 = na_if(actor1,""), assoc_actor_1 = na_if(assoc_actor_1,""), assoc_actor_2 = na_if(assoc_actor_2,""), + inter1 = replace_na(inter1, 0), inter2 = replace_na(inter2, 0)) %>% # Match column structure for an acled dataset select(names(acledR::acled_old_dummy)) @@ -99,6 +102,8 @@ acled_transform_wider <- function(data, type = "full_actors") { # Transform inter into character for collapsing mutate(inter1 = as.character(inter1), inter2 = as.character(inter2)) %>% + mutate(inter1 = replace_na(inter1, ""))%>% + mutate(inter2 = replace_na(inter2, ""))%>% group_by(across(c(-actor1,-actor2, -inter1, -inter2))) %>% # Collapse repeated inters and actors summarise(actor1 = str_c(actor1, collapse = ""), @@ -114,6 +119,7 @@ acled_transform_wider <- function(data, type = "full_actors") { actor1 = na_if(actor1,""), assoc_actor_1 = na_if(assoc_actor_1,""), assoc_actor_2 = na_if(assoc_actor_2,""), + inter1 = replace_na(inter1, 0), inter2 = replace_na(inter2, 0))%>% # Match column structure for an acled dataset select(names(acledR::acled_old_dummy)) @@ -141,6 +147,7 @@ acled_transform_wider <- function(data, type = "full_actors") { actor1 = na_if(actor1,""), assoc_actor_1 = na_if(assoc_actor_1,""), assoc_actor_2 = na_if(assoc_actor_2,""), + inter1 = replace_na(inter1, 0), inter2 = replace_na(inter2, 0))%>% # Match column structure for an acled dataset select(names(acledR::acled_old_dummy)) diff --git a/R/acled_update.R b/R/acled_update.R index 4e34a3e..ba3f8d9 100644 --- a/R/acled_update.R +++ b/R/acled_update.R @@ -123,7 +123,7 @@ acled_update <- function(df, key = key, start_date = start_date, end_date = end_date, - countries = additional_countries, + country = additional_countries, regions = regions, event_types = event_types, acled_access = acled_access, diff --git a/R/multipliertest.R b/R/multipliertest.R deleted file mode 100644 index bdebf94..0000000 --- a/R/multipliertest.R +++ /dev/null @@ -1,54 +0,0 @@ -# # The call -# -# library(lubridate) -# library(tidyverse) -# library(acledR) -# -# country <- c("Argentina", "Brazil") -# start_date <- ymd("2020-01-01") -# end_date <- ymd("2022-12-31") -# -# -# -# middle_point <- paste0(year(end_date) - 1, "-12-31") -# -# n_days_dates <- as.numeric((ymd(end_date) - ymd(start_date)) / 365) -# -# -# ymd(start_date) + 365 -# -# -# estimate <- function(countries,start_date, end_date) { -# -# multipliers <- acledR::acled_multipliers %>% -# rename(country1 = country) %>% -# filter(country1 %in% country) -# -# start_date <- as.Date(start_date) -# end_date <- as.Date(end_date) -# -# # Create a data frame with a sequence of dates from start_date to end_date -# date_seq <- data.frame(date = seq.Date(start_date, end_date, by = "day")) %>% -# mutate(year = format(date, "%Y")) %>% -# group_by(year) %>% -# summarise(days_in_year = n()) %>% -# mutate(year = as.integer(year)) -# -# joined_multipliers <- date_seq %>% -# left_join(multipliers, by = "year") %>% -# filter(!is.na(avg_month_bin)) %>% -# mutate(estimated_events = ((avg_month_bin/30) * days_in_year)) -# -# -# return(joined_multipliers) -# } -# -# ee <- estimate(country,start_date,end_date) -# -# -# received_data <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",countries = c("Argentina","Brazil"), start_date="2020-01-01",end_date = "2022-12-31",prompt = F, acled_access = T, log = F) -# -# received_data %>% -# group_by(country, year) %>% -# summarise(n = n()) -# diff --git a/R/test.R b/R/test.R deleted file mode 100644 index 52acaaa..0000000 --- a/R/test.R +++ /dev/null @@ -1,30 +0,0 @@ -# #test -# -# disorder_type <- c( -# "Political violence", -# "Demonstrations" -# ) -# -# -# data_check <- df_br %>% -# separate_rows(disorder_type, sep = "; ") -# -# if(sum(str_to_sentence(disorder_type) %in% unique(data_check[["disorder_type"]])) < length(disorder_type)){ -# stop("One or more requested disorder types not in data.") -# } -# -# -# test <- acled_generate_counts( -# df_br, -# unit_id = "country", -# time_id = "event_date", -# time_target = "month", -# event_type = c("Protests", "Riots") -# ) - - - -# df <- data.frame(x=c("actor1", "actor2", "actor3"), -# y=c(9,0.5,0.5)) -# -# acled_actor_concentration(df$y, method = "Concentration", acled_dataframe = F) diff --git a/man/acled_api.Rd b/man/acled_api.Rd index 2d44992..8ffb657 100755 --- a/man/acled_api.Rd +++ b/man/acled_api.Rd @@ -7,7 +7,7 @@ acled_api( email = NULL, key = NULL, - countries = NULL, + country = NULL, regions = NULL, start_date = floor_date(Sys.Date(), "year") - years(1), end_date = Sys.Date(), @@ -25,9 +25,9 @@ acled_api( \item{key}{character string. Access key associated with your ACLED account registered at \url{https://developer.acleddata.com}.} -\item{countries}{character vector. Default is NULL, which will return events for all countries. Pass a vector of country names to retrieve events from specific countries. The list of ACLED country names may be found via acledR::acled_countries.} +\item{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.} -\item{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.} +\item{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.} \item{start_date}{character string. Format 'yyyy-mm-dd'. The earliest date for which to return events. The default is \code{1997-01-01}, which is the earliest date available.} @@ -43,7 +43,7 @@ acled_api( \item{acled_access}{logical. If TRUE (default), you have used the acled_access function and the email and key arguments are not required.} -\item{prompt}{logical. If TRUE (default), users will receive an interactive prompt providing information about their call (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.} +\item{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.} \item{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.} } @@ -51,7 +51,7 @@ acled_api( Returns a tibble of of ACLED events. } \description{ -This function allows users to easily request data from the ACLED API. Users can include variables such as countries, regions, dates of interest and the type of file (monadic or dyadic). The function returns a tibble of the desired ACLED events. +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 type of file (monadic or dyadic). The function returns a tibble of the desired ACLED events. } \examples{ \dontrun{ @@ -59,7 +59,7 @@ This function allows users to easily request data from the ACLED API. Users can # 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 = jane.doe.email, key = jane.doe.key, - countries = "Argentina", start_date = "2022-01-01", end_date="2022-02-01", + 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. @@ -78,7 +78,7 @@ carib_acled } \seealso{ \itemize{ -\item ACLED API guide. \url{https://acleddata.com/acleddatanew//wp-content/uploads/dlm_uploads/2021/11/API-User-Guide_Feb2022.pdf} +\item ACLED API guide. \url{https://apidocs.acleddata.com/} } Other API and Access: diff --git a/man/acled_filter_actors.Rd b/man/acled_filter_actors.Rd deleted file mode 100755 index 391c4fc..0000000 --- a/man/acled_filter_actors.Rd +++ /dev/null @@ -1,46 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/acled_filter_actors.R -\name{acled_filter_actors} -\alias{acled_filter_actors} -\title{Filter ACLED Data by Actor} -\usage{ -acled_filter_actors(df, actors, filter_cols = "all") -} -\arguments{ -\item{df}{dataframe. ACLED data to filter.} - -\item{actors}{character vector or vector of character strings. Actor name or list of actor names to use for filtering.} - -\item{filter_cols}{character string. Columns to use for filtering. Default is "all", which filters based on all actor columns (i.e. actor1, actor2, assoc_actor_1, assoc_actor_2). "Primary" filters based on actor1 and actor2 column only.} -} -\value{ -Returns a tibble of ACLED data filtered to selected actors. -} -\description{ -This function allows users to filter ACLED data by actor. -} -\examples{ -\dontrun{ - -# Request events from Yemen -df_events <- acled_api(countries = "Yemen", - start_date = "2022-01-01", - end_date = "2022-07-30", - monadic = F, - acled_access = TRUE) - -# Create vector of actors of interest -yemen_actors <- c('Military Forces of Yemen (2016-) Supreme Political Council', - 'Military Forces of Yemen (2012-)') - -# Filter to selected actors -filtered_df <- filter_actors(df = df_events, actors = yemen_actors, filter_cols = 'all') -} -} -\seealso{ -Other Data Manipulation: -\code{\link{acled_transform_interaction}()}, -\code{\link{acled_transform_longer}()}, -\code{\link{acled_transform_wider}()} -} -\concept{Data Manipulation} diff --git a/man/acled_transform_interaction.Rd b/man/acled_transform_interaction.Rd index d294513..50a04c2 100644 --- a/man/acled_transform_interaction.Rd +++ b/man/acled_transform_interaction.Rd @@ -22,7 +22,7 @@ This function allows users to change from numeric interaction codes (i.e. 1, 2, # Load data frame argen_acled <- acled_api(email = jane.doe.email, key = jane.doe.key, - countries = "Argentina", start_date = "2022-01-01", end_date="2022-02-01", + country = "Argentina", start_date = "2022-01-01", end_date="2022-02-01", acled_access = FALSE) # Transform the interactions @@ -31,7 +31,6 @@ argen_acled_transformed <- acled_transformation_interaction(argen_acled, only_in } \seealso{ Other Data Manipulation: -\code{\link{acled_filter_actors}()}, \code{\link{acled_transform_longer}()}, \code{\link{acled_transform_wider}()} } diff --git a/man/acled_transform_longer.Rd b/man/acled_transform_longer.Rd index 4d90c28..f2c106e 100644 --- a/man/acled_transform_longer.Rd +++ b/man/acled_transform_longer.Rd @@ -25,7 +25,7 @@ Function to convert your ACLED's API calls (if dyadic) into desired monadic form } \examples{ \dontrun{ -#argen_acled <- acled_api(countries = "Argentina",start_date = "2022-01-01", +#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, @@ -40,7 +40,6 @@ Function to convert your ACLED's API calls (if dyadic) into desired monadic form } \seealso{ Other Data Manipulation: -\code{\link{acled_filter_actors}()}, \code{\link{acled_transform_interaction}()}, \code{\link{acled_transform_wider}()} } diff --git a/man/acled_transform_wider.Rd b/man/acled_transform_wider.Rd index d3cd0f7..746353a 100644 --- a/man/acled_transform_wider.Rd +++ b/man/acled_transform_wider.Rd @@ -26,7 +26,7 @@ Function to convert your ACLED's API calls (if monadic) back into the original d } \examples{ \dontrun{ -#argen_acled <- acled_api(countries = "Argentina",start_date = "2022-01-01", +#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 @@ -43,7 +43,6 @@ Function to convert your ACLED's API calls (if monadic) back into the original d } \seealso{ Other Data Manipulation: -\code{\link{acled_filter_actors}()}, \code{\link{acled_transform_interaction}()}, \code{\link{acled_transform_longer}()} } diff --git a/tests/testthat/_snaps/acled_update.md b/tests/testthat/_snaps/acled_update.md deleted file mode 100644 index b09d549..0000000 --- a/tests/testthat/_snaps/acled_update.md +++ /dev/null @@ -1,35 +0,0 @@ -# acled_update without deletions actually returns events that should be deleted - - Code - acled_update(acledR::acled_old_dummy, email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - deleted = FALSE, acled_access = F, prompts = F) - Message - Requesting data for 1 countries. Accounting for the requested time period and ACLED coverage dates, this request includes approximately 350 events. - Processing API request - Extracting content from API request - Dataset updated. - Old number of events: 326. - New events: 1. - Total new & modified events: 64 - Output - # A tibble: 327 x 31 - event_id_cnty event_date year time_precision disorder_type event_type - - 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 - 7 ARG10621 2022-06-30 2022 1 Demostrations Protests - 8 ARG10613 2022-06-30 2022 1 Demostrations Protests - 9 ARG10614 2022-06-30 2022 1 Demostrations Protests - 10 ARG10617 2022-06-30 2022 1 Demostrations Protests - # i 317 more rows - # i 25 more variables: sub_event_type , actor1 , assoc_actor_1 , - # inter1 , actor2 , assoc_actor_2 , inter2 , - # interaction , civilian_targeting , iso , region , - # country , admin1 , admin2 , admin3 , location , - # latitude , longitude , geo_precision , source , - # source_scale , notes , fatalities , tags , ... - diff --git a/tests/testthat/setup-acled_api.R b/tests/testthat/setup-acled_api.R index 519deba..8663517 100644 --- a/tests/testthat/setup-acled_api.R +++ b/tests/testthat/setup-acled_api.R @@ -1,24 +1,25 @@ # Helpers for test-acled_api.R -received_data <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",countries = "Argentina", start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = T, log = F) -received_data_monadic <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",countries = "Argentina", start_date="2022-01-01",end_date = "2022-12-31",prompt = F, monadic = T, acled_access = F, log = F) +received_data <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",country="Argentina", start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = T, log = F) +received_data_monadic <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",country = "Argentina", start_date="2022-01-01",end_date = "2022-12-31",prompt = F, monadic = T, acled_access = F, log = F) log_received_data <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",regions = c("Western Africa", "Eastern Africa", "Europe"),end_date = "2022-12-31",prompt = F, acled_access = F, log = T) received_data_numeric_region <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",regions = 1,end_date = "2022-12-31",prompt = F, acled_access = F) timestamp_numeric_check <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", + country = "Argentina", start_date="2023-01-01",end_date = "2023-06-06", timestamp = 1681622333, # as numeric prompt = F, acled_access = F, log = F) timestamp_string_check <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", + country = "Argentina", start_date="2023-01-01",end_date = "2023-06-06", timestamp = "2023-04-16", # as numeric prompt = F, acled_access = F, log = F) # For checking credentials -log_received_data_check_credential <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",regions = c("Western Africa", "Eastern Africa", "Europe"),end_date = "2022-12-31",prompt = F, acled_access = T, log = T) +log_received_data_check_credential <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", + regions = c("Western Africa", "Eastern Africa", "Europe"),end_date = "2022-12-31",prompt = F, acled_access = T, log = T) columns <- c("event_id_cnty","event_date","year","time_precision","disorder_type", @@ -28,7 +29,7 @@ columns <- c("event_id_cnty","event_date","year","time_precision","disorder_type received_data_country_and_region <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", + country = "Argentina", regions = "Central America", start_date="2022-01-01", end_date = "2022-12-31", @@ -36,7 +37,7 @@ received_data_country_and_region <- acled_api(email = "acledexamples@gmail.com", received_data_country_and_region_num <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", + country = "Argentina", regions = 14, start_date="2022-01-01", end_date = "2022-12-31", diff --git a/tests/testthat/setup-acled_transform_interaction.R b/tests/testthat/setup-acled_transform_interaction.R index 63de2c1..84f0b58 100644 --- a/tests/testthat/setup-acled_transform_interaction.R +++ b/tests/testthat/setup-acled_transform_interaction.R @@ -1,5 +1,5 @@ test <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", start_date="2022-01-01",end_date = "2022-12-31", + country = "Argentina", start_date="2022-01-01",end_date = "2022-12-31", prompt = F, acled_access = F, log = F) test_changes <- test %>% diff --git a/tests/testthat/test-acled_api.R b/tests/testthat/test-acled_api.R index 0d22da2..eb6c3ab 100644 --- a/tests/testthat/test-acled_api.R +++ b/tests/testthat/test-acled_api.R @@ -13,7 +13,7 @@ test_that("names of columns are correct", { test_that("event_type filters work or not",{ expect_equal(unique(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - start_date="2022-01-01",end_date = "2022-12-31",countries = "Argentina", + start_date="2022-01-01",end_date = "2022-12-31", country = "Argentina", event_type = "Protests", prompt = F, acled_access = F, log = F)$event_type), "Protests" ) }) @@ -30,7 +30,7 @@ test_that("country days are calculated as expected",{ unit_test = t_end - ymd(paste0(start_year, "-01-01"))) argentina_test_call <- acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", start_date="1998-01-01", + country = "Argentina", start_date="1998-01-01", end_date = "2021-01-01",prompt = F, acled_access = F, log = T) expect_equal(argentina_test_call$time, argentina_country_days$unit_test) @@ -58,9 +58,9 @@ local({ test_that("Users continue call", { expect_equal(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - start_date="2022-01-01",end_date = "2022-12-31",countries = "Argentina", + start_date="2022-01-01",end_date = "2022-12-31",country = "Argentina", prompt = T, acled_access = F, log = F), acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - start_date="2022-01-01",end_date = "2022-12-31",countries = "Argentina", + start_date="2022-01-01",end_date = "2022-12-31",country = "Argentina", prompt = F, acled_access = F, log = F)) }) }) # test on whether they can continue @@ -113,7 +113,7 @@ local({ test_that("A user can stop a call when the provided timestamp is not recognized",{ expect_error(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - start_date="2022-01-01",end_date = "2022-12-31",countries = "Argentina", + start_date="2022-01-01",end_date = "2022-12-31",country = "Argentina", timestamp = "muchachos", prompt = F, acled_access = F, log = F), regexp = "User requested") }) }) @@ -125,7 +125,7 @@ local({ test_that("A user can ignore the provided timestamp if it is not recognized",{ expect_no_error(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - start_date="2022-01-01",end_date = "2022-12-31",countries = "Argentina", + start_date="2022-01-01",end_date = "2022-12-31",country = "Argentina", timestamp = "muchachos", prompt = F, acled_access = F, log = F)) }) }) @@ -135,8 +135,10 @@ local({ test_that("The call actually returns monadics.", { expect_equal(min(received_data_monadic$event_date), min(received_data$event_date)) + expect_equal(max(received_data_monadic$event_date), max(received_data$event_date)) - expect_equal(unique(received_data_monadic$country), min(received_data$country)) + + expect_equal(unique(received_data_monadic$country), unique(received_data$country)) expect_gte(nrow(received_data_monadic), nrow(received_data)) }) @@ -160,9 +162,9 @@ test_that("Error when region number does not exist", { ## Errors when a country requested doesnt exists ---- test_that("Error when one of two countries are wrong",{ - expect_error(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",countries = c("Argentia","Bolivia"), + expect_error(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5",country = c("Argentia","Bolivia"), start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = F), - regexp = "One or more of the requested countries *")}) + regexp = "One or more of the requested *")}) ## Test what happens when someone inputs acled_access as TRUE but it includes email and key. ---- test_that("Acled_access is ignored",{ @@ -172,13 +174,6 @@ test_that("Acled_access is ignored",{ # Test errors from incorrectly input arguments. ---- test_that("acled_api() throws an error when called with invalid arguments", { - expect_error(acled_api(Countries = "Argentina", - start_date="2022-01-01", - end_date = "2022-12-31", - prompt = F, - acled_access = T, - log = F), regexp= - "Countries is not a valid option. Please utilize \"countries\", without capitalizing") expect_error(acled_api(Country = "Argentina", start_date="2022-01-01", @@ -186,15 +181,7 @@ test_that("acled_api() throws an error when called with invalid arguments", { prompt = F, acled_access = T, log = F), regexp= - "Country is not a valid option. Please utilize \"countries\"") - - expect_error(acled_api(country = "Argentina", - start_date="2022-01-01", - end_date = "2022-12-31", - prompt = F, - acled_access = T, - log = F), regexp= - "Country is not a valid option. Please utilize \"countries\"") + "Country is not a valid option. Please utilize \"country\", without capitalizing") expect_error(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", @@ -221,13 +208,13 @@ test_that("acled_api() throws an error when called with invalid arguments", { prompt = F, acled_access = T), regexp= "Event type is not a valid option. Please utilize \"event_types\", without capitalizing") - expect_error(acled_api(countries = "Argentina", + expect_error(acled_api(country = "Argentina", Start_date="2022-01-01", end_date = "2022-12-31", prompt = F, acled_access = T), regexp= "Start_date is not a valid option. Please utilize \"start_date\", without capitalizing") - expect_error(acled_api(countries = "Argentina", + expect_error(acled_api(country = "Argentina", start_date="2022-01-01", End_date = "2022-12-31", prompt = F, @@ -249,10 +236,10 @@ test_that("If access is TRUE and credentials are null, credentials are ignored, test_that("Users gets an error when acled_access is False, but no key or email are provided.", { - expect_error(acled_api(countries = "Argentina", start_date="2022-01-01", + expect_error(acled_api(country = "Argentina", start_date="2022-01-01", end_date = "2022-12-31", prompt = F, acled_access = F), regexp = "Email address required") - expect_error(acled_api(email = "stuff",countries = "Argentina", start_date="2022-01-01", + expect_error(acled_api(email = "stuff",country = "Argentina", start_date="2022-01-01", end_date = "2022-12-31", prompt = F, acled_access = F), regexp = "Key required") @@ -264,7 +251,7 @@ test_that("Users gets an error when acled_access is False, but no key or email a test_that("start_date is after end_date", { expect_error( acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", + country = "Argentina", start_date="2022-01-01", end_date = "2021-01-01", prompt = F, @@ -276,7 +263,7 @@ test_that("start_date is after end_date", { test_that("timestamp is from a latter date than today." ,{ expect_error(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", + country = "Argentina", start_date="2021-01-01", end_date = "2022-01-01", prompt = F, @@ -289,7 +276,7 @@ test_that("timestamp is from a latter date than today." ,{ test_that("Error when non existent event types",{ expect_error(acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Argentina", + country = "Argentina", start_date="2021-01-01", end_date = "2022-01-01", event_types = c("Protests","Superhero fight"), @@ -324,3 +311,4 @@ test_that("Tables display NAs instead of blanks", { }) + diff --git a/tests/testthat/test-acled_filter_actors.R b/tests/testthat/test-acled_filter_actors.R deleted file mode 100644 index 0b9216f..0000000 --- a/tests/testthat/test-acled_filter_actors.R +++ /dev/null @@ -1,99 +0,0 @@ - - -# Test operation---- -## Test that the function returns a tibble when given a valid input. ---- -test_that("function returns a tibble", { - # create sample input data - df <- data.frame(actor1 = c("A", "B"), actor2 = c("C", "D"), - assoc_actor_1 = c("X", "Y"), assoc_actor_2 = c("Z", "W")) - df <- as_tibble(df) - actors <- c("A", "B") - - # call the function - filtered_df <- acled_filter_actors(df, actors) - - # test that the output is a tibble - expect_s3_class(filtered_df, "tbl_df") -}) - - -## Test if the function returns the expected output when filtering by all actor columns ---- -test_that("Filter by all actors returns the expected output", { - # Create a mock dataframe - df <- data.frame( - actor1 = c('Military Forces of Yemen', 'Yemeni Houthi rebels (Ansar Allah)', 'Al-Qaida in the Arabian Peninsula (AQAP)'), - actor2 = c('Yemeni Houthi rebels (Ansar Allah)', 'Military Forces of Yemen', ''), - assoc_actor_1 = c('Al-Qaida in the Arabian Peninsula (AQAP)', '', ''), - assoc_actor_2 = c('', '', '') - ) - actors <- c('Military Forces of Yemen', 'Yemeni Houthi rebels (Ansar Allah)') - expected_df <- df[1:2, ] - actual_df <- acled_filter_actors(df = df, actors = actors, filter_cols = 'all') - # Compare the expected output to the actual output - expect_equal(actual_df, expected_df) -}) - -## Test that the function filters the ACLED data by actor1.---- -test_that("filters by actor1", { - df <- data.frame(actor1 = c('Actor 1', 'Actor 2'), actor2 = c('Actor 3', 'Actor 4'), - assoc_actor_1 = c('Actor 5; Actor 6', 'Actor 7'), assoc_actor_2 = c('Actor 8', 'Actor 9')) - actors <- 'Actor 1' - filtered_df <- acled_filter_actors(df, actors, filter_cols='primary') - expect_equal(nrow(filtered_df), 1) - expect_equal(filtered_df$actor1[1],'Actor 1') -}) - -## Test that the function filters the ACLED data by actor2. ---- -test_that("filters by actor2", { - df <- data.frame(actor1 = c('Actor 1', 'Actor 2'), actor2 = c('Actor 3', 'Actor 4'), - assoc_actor_1 = c('Actor 5; Actor 6', 'Actor 7'), assoc_actor_2 = c('Actor 8', 'Actor 9')) - actors <- 'Actor 3' - filtered_df <- acled_filter_actors(df, actors, filter_cols='primary') - expect_equal(nrow(filtered_df), 1) - expect_equal(filtered_df$actor2[1], 'Actor 3') -}) -## Test that the function filters the ACLED data by assoc_actor_1 and assoc_actor_2. ---- -test_that("filters by assoc_actor_1 and assoc_actor_2", { - df <- data.frame(actor1 = c('Actor 1', 'Actor 2'), actor2 = c('Actor 3', 'Actor 4'), - assoc_actor_1 = c('Actor 5; Actor 6', 'Actor 7'), assoc_actor_2 = c('Actor 8', 'Actor 9')) - actors <- 'Actor 5' - filtered_df <- acled_filter_actors(df, actors, filter_cols='all') - expect_equal(nrow(filtered_df), 1) - expect_true(stringr::str_detect(filtered_df$assoc_actor_1, actors)) -}) - - - -# Error related ---- -## Test if function throws error if dataframe is missing 'assoc_actor_1' or 'assoc_actor_2' column ---- -test_that("function throws error if dataframe is missing 'assoc_actor_1' or 'assoc_actor_2' column", { - df <- data.frame(actor1 = c("A", "B"), actor2 = c("C", "D")) - expect_error(acled_filter_actors(df, actors = c("A"), filter_cols = 'all'), "Dataframe is missing 'assoc_actor_1' or 'assoc_actor_2' column.") -}) - -## Test if function throws error if filter_cols argument is not 'all' or 'primary' ---- -test_that("function throws error if filter_cols argument is not 'all' or 'primary'", { - df <- data.frame(actor1 = c("A", "B"), actor2 = c("C", "D")) - expect_error(acled_filter_actors(df, actors = c("A"), filter_cols = 'All'),"filter_cols argument must be 'all' or 'primary'.") -}) - - - -# Regex related ---- -## Test with multiple actor names and parentheses -test_that("Test that regex can handle multiple actor names and parentheses",{ - df <- data.frame( - actor1 = c("Actor A", "Actor B"), - actor2 = c("Actor C", "Actor D"), - assoc_actor_1 = c("Actor A (Group 1); Actor E", "Actor F; Actor B (Group 2)"), - assoc_actor_2 = c("Actor G", "Actor H; Actor C (Group 3)")) - actors <- c("Actor A (Group 1)", "Actor C (Group 3)") - filtered_df <- acled_filter_actors(df, actors) - expect_equal(nrow(filtered_df), 2) -}) - - - - - -# What happends if not all actor columns are present in the dataset and it is not with filter_cols = all diff --git a/tests/testthat/test-acled_help.R b/tests/testthat/test-acled_help.R deleted file mode 100644 index 8849056..0000000 --- a/tests/testthat/test-acled_help.R +++ /dev/null @@ -1,3 +0,0 @@ -test_that("multiplication works", { - expect_equal(2 * 2, 4) -}) diff --git a/tests/testthat/test-acled_transform_wider.R b/tests/testthat/test-acled_transform_wider.R index 9a0071d..c606ccd 100644 --- a/tests/testthat/test-acled_transform_wider.R +++ b/tests/testthat/test-acled_transform_wider.R @@ -90,13 +90,13 @@ test_that("Function returns NULL when non-existent type is input", { test_that("Can you request data from the monadic api, and convert it back?", { tester <- acledR::acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Brazil", start_date="2022-01-01", + country = "Brazil", start_date="2022-01-01", end_date = "2022-12-31", monadic = T, prompt = F, acled_access = F, log = F)%>% acled_transform_wider(type = "api_monadic") control <- acledR::acled_api(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5", - countries = "Brazil", start_date="2022-01-01", + country = "Brazil", start_date="2022-01-01", end_date = "2022-12-31", monadic = F, prompt = F, acled_access = F, log = F)%>% arrange(desc(event_id_cnty)) diff --git a/tests/testthat/testthat-problems.rds b/tests/testthat/testthat-problems.rds new file mode 100644 index 0000000..ab8236a Binary files /dev/null and b/tests/testthat/testthat-problems.rds differ diff --git a/vignettes/articles/acled_api.Rmd b/vignettes/articles/acled_api.Rmd index 501c87d..4025b12 100644 --- a/vignettes/articles/acled_api.Rmd +++ b/vignettes/articles/acled_api.Rmd @@ -55,7 +55,7 @@ You can confirm that they have been properly stored by running `Sys.getenv("emai ```{r, eval = F} acled_api(email = NULL, key = NULL, - countries = NULL, + country = NULL, regions = NULL, start_date = "1997-01-01", end_date = Sys.Date(), @@ -72,7 +72,7 @@ acled_api(email = NULL, ### Geographical filters -You can use the `countries` and `regions` parameters to specify the locations from which you would like to request data. If both values are `NULL` or are not included, the API will return data for all countries and regions. If you would like to request data for multiple countries, you can do so by using a vector of country names (e.g., `c("Argentina","Spain","Bolivia")`). Similarly, you can request data from one or more regions by using either a vector of region names or numeric codes. `acledR::acled_countries` and `acledR::acled_regions` show the full lists of countries and regions available. Please visit ACLED’s [Geography vignette](`r vignette("Geography")`) for more information. +You can use the `country` and `regions` parameters to specify the locations from which you would like to request data. If both values are `NULL` or are not included, the API will return data for all countries and regions. If you would like to request data for multiple countries, you can do so by using a vector of country names (e.g., `c("Argentina","Spain","Bolivia")`). Similarly, you can request data from one or more regions by using either a vector of region names or numeric codes. `acledR::acled_countries` and `acledR::acled_regions` show the full lists of countries and regions available. Please visit ACLED’s [Geography vignette](`r vignette("Geography")`) for more information. ### Temporal filters @@ -104,7 +104,7 @@ As is common when executing API calls, handling large volumes of data requires s - The number of countries for which data is being requested, -- The number of estimated events requested (based only on country and year, and NOT event type), +- The number of estimated events requested (based only on country and year, and NOT event type), - The number of API calls needed, based on an estimate of how big the call is, @@ -122,7 +122,7 @@ library(dplyr) acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") -df_br <- acled_api(countries = c("Brazil"), +df_br <- acled_api(country = c("Brazil"), start_date = "2022-01-01", end_date = "2022-12-01", monadic = F, @@ -139,7 +139,7 @@ head(df_br, 5) If you wanted data from both “Brazil” and “Colombia”, you would execute the following: ```{r, eval = F} -df_br_co <- acled_api(countries = c("Brazil", "Colombia"), +df_br_co <- acled_api(country = c("Brazil", "Colombia"), start_date = "2022-01-01", end_date = "2022-12-01", monadic = F, @@ -147,7 +147,7 @@ df_br_co <- acled_api(countries = c("Brazil", "Colombia"), prompt = F) ``` -If you are interested in events occurring over a larger area, it may be simpler to omit the `countries` parameter and include a `regions` argument instead. You could also include an `event_type` argument to receive only a specific type of event: +If you are interested in events occurring over a larger area, it may be simpler to omit the `country` parameter and include a `regions` argument instead. You could also include an `event_type` argument to receive only a specific type of event: ```{r, eval = F} df_sa <- acled_api(regions = c("South America"), @@ -162,7 +162,7 @@ df_sa <- acled_api(regions = c("South America"), You can use the *timestamp* column/filter to specify the dates from which you would like to receive new or updated data. You can include the argument as either a string ("yyyy-mm-dd") or a numeric Unix timestamp: ```{r, eval = F} -df_br_co <- acled_api(countries = c("Brazil", "Colombia"), +df_br_co <- acled_api(country = c("Brazil", "Colombia"), start_date = "2022-01-01", end_date = "2022-12-01", monadic = F, @@ -175,7 +175,7 @@ df_br_co <- acled_api(countries = c("Brazil", "Colombia"), If you would like to include only one type of *interaction* (e.g., "Rioters versus Civilians (57)"), then you can add *interaction* code to the `...` argument: ```{r, eval = F} -df_sa <- acled_api(countries = c("Brazil", "Colombia"), +df_sa <- acled_api(country = c("Brazil", "Colombia"), start_date = "2022-01-01", end_date = "2022-12-01", monadic = F, diff --git a/vignettes/articles/acled_deletions_api.Rmd b/vignettes/articles/acled_deletions_api.Rmd index d7ecf2b..d0e27d7 100755 --- a/vignettes/articles/acled_deletions_api.Rmd +++ b/vignettes/articles/acled_deletions_api.Rmd @@ -40,7 +40,7 @@ To simplify this process, `acledR` includes a function which makes the update fo ```{r, eval=F} acled_update( df, - countries = NULL, + additional_countries = NULL, regions = NULL, event_types = NULL, acled_access = TRUE, diff --git a/vignettes/articles/acled_update.Rmd b/vignettes/articles/acled_update.Rmd index d4fbacf..e406ed6 100644 --- a/vignettes/articles/acled_update.Rmd +++ b/vignettes/articles/acled_update.Rmd @@ -108,7 +108,7 @@ The dataset has not been updated since `r print(latest_timestamp)`, so you may w ```{r} new_argen_dataset <- acled_update(argen_dummy_acled_file, - countries = "Argentina", + additional_countries = "Argentina", acled_access = T, prompts = FALSE) ``` diff --git a/vignettes/get_started.Rmd b/vignettes/get_started.Rmd index c73f823..7fa6b29 100644 --- a/vignettes/get_started.Rmd +++ b/vignettes/get_started.Rmd @@ -64,10 +64,10 @@ If the authentication was successful, you will find a message in the console sta Once the credentials are authenticated, users can easily start requesting data from the API. To do so, you can use the `acled_api()` function. The function requires the fields for which to gather the data from. Thus, in the example below we are going to request data from Argentina throughout 2022. ```{r} -argentinian_data <- acled_api(countries = "Argentina", start_date="2022-01-01",end_date = "2022-12-31", prompt=F) +argentinian_data <- acled_api(country = "Argentina", start_date="2022-01-01",end_date = "2022-12-31", prompt=F) ``` -While in our example we utilized only three arguments (`countries`, `start_date` and `end_date`), `acled_api()` features a number of other arguments such as regions, timestamp, event_types, and more. You can find more in `vignette("acled_api")`. +While in our example we utilized only three arguments (`country`, `start_date` and `end_date`), `acled_api()` features a number of other arguments such as regions, timestamp, event_types, and more. You can find more in `vignette("acled_api")`. Additionally, due to the fact that we authenticated our credentials before, we are not required to input these into the function. Otherwise, if we didn't utilize `acled_access()` we would be required to input our email and key.