diff --git a/.gitignore b/.gitignore index 65c8cfe..bdf9a2d 100755 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ .RDataTmp .Renviron .DS_Store +/doc/ +/Meta/ diff --git a/_pkgdown.yml b/_pkgdown.yml index 4c05c88..a280c36 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -11,7 +11,7 @@ navbar: href: reference/index.html - text: Get Started href: articles/get_started.html - - text: Utilizing acledR + - text: Using acledR href: index.html menu: - text: ACLED API diff --git a/tests/testthat/setup-acled_api.R b/tests/testthat/setup-acled_api.R index a22bfea..33c77a5 100644 --- a/tests/testthat/setup-acled_api.R +++ b/tests/testthat/setup-acled_api.R @@ -1,25 +1,25 @@ # Helpers for test-acled_api.R -received_data <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),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 = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),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 = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),regions = c("Western Africa", "Eastern Africa", "Europe"), start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = T) -received_data_numeric_region <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),regions = 1,prompt = F, acled_access = F) +received_data <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),country="Argentina", start_date="2022-01-01", end_date = "2022-12-31", prompt = F, acled_access = T, log = F, inter_numeric = TRUE) +received_data_monadic <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),country = "Argentina", start_date="2022-01-01",end_date = "2022-12-31",prompt = F, monadic = T, acled_access = F, log = F, inter_numeric = TRUE) +log_received_data <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),regions = c("Western Africa", "Eastern Africa", "Europe"), start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = T, inter_numeric = TRUE) +received_data_numeric_region <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),regions = 1,prompt = F, acled_access = F, inter_numeric = TRUE) timestamp_numeric_check <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country = "Argentina", start_date="2023-01-01",end_date = "2023-06-06", timestamp = 1681622333, # as numeric - prompt = F, acled_access = F, log = F) + prompt = F, acled_access = F, log = F, inter_numeric = TRUE) timestamp_string_check <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), 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) + prompt = F, acled_access = F, log = F, inter_numeric = TRUE) # For checking credentials log_received_data_check_credential <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), - regions = c("Western Africa", "Eastern Africa", "Europe"),end_date = "2022-12-31",prompt = F, acled_access = T, log = T) + regions = c("Western Africa", "Eastern Africa", "Europe"),end_date = "2022-12-31",prompt = F, acled_access = T, log = T, inter_numeric = TRUE) columns <- c("event_id_cnty","event_date","year","time_precision","disorder_type", @@ -32,11 +32,11 @@ received_data_country_and_region <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_ regions = "Central America", start_date="2022-01-01", end_date = "2022-12-31", - prompt = F, acled_access = F) + prompt = F, acled_access = F, inter_numeric = TRUE) received_data_country_and_region_num <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country = "Argentina", regions = 14, start_date="2022-01-01", end_date = "2022-12-31", - prompt = F, acled_access = F) + prompt = F, acled_access = F, inter_numeric = TRUE) diff --git a/tests/testthat/setup-acled_transform_interaction.R b/tests/testthat/setup-acled_transform_interaction.R index de2aa0c..9654734 100644 --- a/tests/testthat/setup-acled_transform_interaction.R +++ b/tests/testthat/setup-acled_transform_interaction.R @@ -1,6 +1,6 @@ test <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country = "Argentina", start_date="2022-01-01",end_date = "2022-12-31", - prompt = F, acled_access = F, log = F) + prompt = F, acled_access = F, log = F, inter_numeric = TRUE) test_changes <- test %>% left_join(acledR::acled_interaction_codes, by = c("inter1" = "Numeric Code")) %>% diff --git a/tests/testthat/test-acled_access.R b/tests/testthat/test-acled_access.R index 6e71693..8ee6a78 100644 --- a/tests/testthat/test-acled_access.R +++ b/tests/testthat/test-acled_access.R @@ -2,7 +2,8 @@ # Does it save the credentials in the enviornment? - Missing test_that("acled_access properly stores the credentials", { - expect_equal(Sys.getenv("acled_email"),"acledexamples@gmail.com") + # expect_equal(Sys.getenv("acled_email"),"acledexamples@gmail.com") + expect_equal(Sys.getenv("acled_email"),"t.billing@acleddata.com") expect_equal(nchar(Sys.getenv("acled_key")), 20) }) diff --git a/tests/testthat/test-acled_api.R b/tests/testthat/test-acled_api.R index fb111db..d97f2c3 100644 --- a/tests/testthat/test-acled_api.R +++ b/tests/testthat/test-acled_api.R @@ -14,7 +14,7 @@ test_that("event_type filters work or not",{ expect_equal(unique(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), 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" ) + event_type = "Protests", prompt = F, acled_access = F, log = F, inter_numeric = TRUE)$event_type), "Protests" ) }) @@ -31,7 +31,7 @@ test_that("country days are calculated as expected",{ argentina_test_call <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country = "Argentina", start_date="1998-01-01", - end_date = "2021-01-01",prompt = F, acled_access = F, log = T) + end_date = "2021-01-01",prompt = F, acled_access = F, log = T, inter_numeric = TRUE) expect_equal(argentina_test_call$time, argentina_country_days$unit_test) @@ -45,9 +45,10 @@ local({ expect_equal(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), 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",country = "Argentina", - prompt = F, acled_access = F, log = F)) + prompt = T, acled_access = F, log = F, inter_numeric = TRUE), + acled_api(Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), + start_date="2022-01-01",end_date = "2022-12-31",country = "Argentina", + prompt = F, acled_access = F, log = F, inter_numeric = TRUE)) }) }) # test on whether they can continue @@ -100,7 +101,8 @@ local({ expect_error(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), start_date="2022-01-01",end_date = "2022-12-31",country = "Argentina", - timestamp = "muchachos", prompt = F, acled_access = F, log = F), regexp = "User requested") + timestamp = "muchachos", prompt = F, acled_access = F, log = F, inter_numeric = TRUE), + regexp = "User requested") }) }) @@ -112,7 +114,7 @@ local({ expect_no_error(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), start_date="2022-01-01",end_date = "2022-12-31",country = "Argentina", - timestamp = "muchachos", prompt = F, acled_access = F, log = F)) + timestamp = "muchachos", prompt = F, acled_access = F, log = F, inter_numeric = TRUE)) }) }) @@ -138,11 +140,11 @@ test_that("Population columns are being received", { received_data_pops <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country="Argentina", start_date="2022-01-01",end_date = "2022-01-04", - population='full',prompt = F, acled_access = F) + population='full', prompt = F, acled_access = F, inter_numeric = TRUE) received_data_best <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country="Argentina", start_date="2022-01-01",end_date = "2022-01-04", - population='best',prompt = F, acled_access = F) + population='best',prompt = F, acled_access = F, inter_numeric = TRUE) expect_true(all(population_cols %in% colnames(received_data_pops))) @@ -158,12 +160,12 @@ test_that("Population columns are being received", { test_that("Error prompted when region does not exist", { expect_error(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),regions = "Narnia", - start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = F), regexp = "One or more requested region names not in the ACLED country list.") + start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = F, inter_numeric = TRUE), regexp = "One or more requested region names not in the ACLED country list.") }) test_that("Error when region number does not exist", { expect_error(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),regions = 420, - start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = F), + start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = F, inter_numeric = TRUE), regexp = "One or more requested region numbers not in the ACLED country list") }) @@ -171,12 +173,12 @@ 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 = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"),country = c("Argentia","Bolivia"), - start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = F), + start_date="2022-01-01",end_date = "2022-12-31",prompt = F, acled_access = F, log = F, inter_numeric = TRUE), 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",{ - expect_true(grepl("acledexamples", log_received_data_check_credential$email[1])) + expect_true(grepl("t.billing", log_received_data_check_credential$email[1])) }) # Test errors from incorrectly input arguments. ---- @@ -188,7 +190,7 @@ test_that("acled_api() throws an error when called with invalid arguments", { end_date = "2022-12-31", prompt = F, acled_access = T, - log = F), regexp= + log = F, inter_numeric = TRUE), regexp= "Country is not a valid option. Please utilize \"country\", without capitalizing") @@ -198,7 +200,7 @@ test_that("acled_api() throws an error when called with invalid arguments", { end_date = "2022-12-31", prompt = F, acled_access = T, - log = F), regexp= + log = F, inter_numeric = TRUE), regexp= "Region is not a valid option. Please utilize \"regions\"") expect_error(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), @@ -207,26 +209,26 @@ test_that("acled_api() throws an error when called with invalid arguments", { end_date = "2022-12-31", prompt = F, acled_access = T, - log = F), regexp= + log = F, inter_numeric = TRUE), regexp= "Regions is not a valid option. Please utilize \"regions\", without capitalizing") expect_error(acled_api(Event_type = "Argentina", start_date="2022-01-01", end_date = "2022-12-31", prompt = F, - acled_access = T), regexp= + acled_access = T, inter_numeric = TRUE), regexp= "Event type is not a valid option. Please utilize \"event_types\", without capitalizing") expect_error(acled_api(country = "Argentina", Start_date="2022-01-01", end_date = "2022-12-31", prompt = F, - acled_access = T), regexp= + acled_access = T, inter_numeric = TRUE), regexp= "Start_date is not a valid option. Please utilize \"start_date\", without capitalizing") expect_error(acled_api(country = "Argentina", start_date="2022-01-01", End_date = "2022-12-31", prompt = F, - acled_access = T), regexp= + acled_access = T, inter_numeric = TRUE), regexp= "End_date is not a valid option. Please utilize \"end_date\", without capitalizing") }) @@ -239,16 +241,16 @@ test_that("If access is TRUE and credentials are null, credentials are ignored, end_date = "2022-12-31", prompt = F, acled_access = T, - log = F), regexp = "acled_access is TRUE, but email and/or key are not stored in the enviornment. Please rerun acled_access or include key and email in function") + log = F, inter_numeric = TRUE), regexp = "acled_access is TRUE, but email and/or key are not stored in the enviornment. Please rerun acled_access or include key and email in function") }) test_that("Users gets an error when acled_access is False, but no key or email are provided.", { 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") + end_date = "2022-12-31", prompt = F, acled_access = F, inter_numeric = TRUE), regexp = "Email address required") 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") + end_date = "2022-12-31", prompt = F, acled_access = F, inter_numeric = TRUE), regexp = "Key required") @@ -264,7 +266,7 @@ test_that("start_date is after end_date", { end_date = "2021-01-01", prompt = F, acled_access = F, - log = F), regexp = "Requested \'start_date\'")}) + log = F, inter_numeric = TRUE), regexp = "Requested \'start_date\'")}) # Error when timestamp is from a date later than today ---- @@ -277,7 +279,7 @@ test_that("timestamp is from a latter date than today." ,{ prompt = F, acled_access = F, timestamp = paste0(year(now())+1, "01-01"), # Way to make it always in the future - log = F), regexp = "The timestamp cannot be" ) + log = F, inter_numeric = TRUE), regexp = "The timestamp cannot be" ) }) # Error when requesting non-existent event types ---- @@ -290,7 +292,7 @@ test_that("Error when non existent event types",{ event_types = c("Protests","Superhero fight"), prompt = F, acled_access = F, - log = F), regexp = "One or more requested event types are not in the ACLED data.") + log = F, inter_numeric = TRUE), regexp = "One or more requested event types are not in the ACLED data.") }) # A message appears that acled_access is being ignored, and the proper credentials are being used.---- @@ -298,12 +300,12 @@ test_that("Error when non existent event types",{ test_that("A warning appears that acled_access is being ignored, and the proper credentials are being used.",{ alog <- acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), - acled_access = T, log = T) + acled_access = T, log = T, inter_numeric = TRUE) expect_message(acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), - acled_access = T, log = T), regexp = "acled_access is TRUE, but email and key are included in the function. Ignoring acled_access.") + acled_access = T, log = T, inter_numeric = TRUE), regexp = "acled_access is TRUE, but email and key are included in the function. Ignoring acled_access.") - expect_true(grepl("acledexamples", alog$email[1])) + expect_true(grepl("t.billing", alog$email[1])) }) diff --git a/tests/testthat/test-acled_deletions_api.R b/tests/testthat/test-acled_deletions_api.R index 1c52366..0262e95 100644 --- a/tests/testthat/test-acled_deletions_api.R +++ b/tests/testthat/test-acled_deletions_api.R @@ -22,7 +22,7 @@ test_that("names of columns are correct - unix", { ## Test that email and key are handled appropiately ---- test_that("Email and key are handled as expected without acled_access",{ - expect_true(grepl("acledexamples", received_deleted_log$email[1]))} + expect_true(grepl("t.billing", received_deleted_log$email[1]))} ) ## Test that acled_access is handled appropiately. ---- @@ -32,7 +32,7 @@ test_that("Email and Key are handled appropiately",{ some_log <- acled_deletions_api(date_deleted = "1658707200", acled_access = T, log = T) - expect_true(grepl("acledexamples", some_log$email[1]))} + expect_true(grepl("t.billing", some_log$email[1]))} ) ## Date and unix return the same output ---- @@ -90,7 +90,7 @@ test_that("A warning appears that acled_access is being ignored, and the proper expect_message(acled_deletions_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), date_deleted = "1658707200",acled_access = T, log = T), regexp = "acled_access is TRUE, but email and key are included in the function. Ignoring acled_access.") - expect_true(grepl("acledexamples", alog$email[1])) + expect_true(grepl("t.billing@acleddata.com", alog$email[1])) }) diff --git a/tests/testthat/test-acled_transform_wider.R b/tests/testthat/test-acled_transform_wider.R index dce3b2a..2767d9b 100644 --- a/tests/testthat/test-acled_transform_wider.R +++ b/tests/testthat/test-acled_transform_wider.R @@ -92,13 +92,13 @@ test_that("Can you request data from the monadic api, and convert it back?", { tester <- acledR::acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country = "Brazil", start_date="2022-01-01", end_date = "2022-12-31", monadic = T, - prompt = F, acled_access = F, log = F)%>% + prompt = F, acled_access = F, log = F, inter_numeric = TRUE)%>% acled_transform_wider(type = "api_monadic") control <- acledR::acled_api(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY"), country = "Brazil", start_date="2022-01-01", end_date = "2022-12-31", monadic = F, - prompt = F, acled_access = F, log = F)%>% + prompt = F, acled_access = F, log = F, inter_numeric = TRUE)%>% arrange(desc(event_id_cnty)) diff --git a/vignettes/articles/acled_api.Rmd b/vignettes/articles/acled_api.Rmd index 7dd1f4b..41cb836 100644 --- a/vignettes/articles/acled_api.Rmd +++ b/vignettes/articles/acled_api.Rmd @@ -63,6 +63,7 @@ acled_api(email = NULL, event_types = NULL, population = "none", monadic = FALSE, + inter_numeric = FALSE, ..., acled_access = TRUE, prompt = TRUE) @@ -133,7 +134,8 @@ df_br <- acled_api(country = c("Brazil"), acled_access = TRUE, prompt = F) ``` -```{r,echo=FALSE } + +```{r, echo=FALSE} library(acledR) library(dplyr) @@ -146,6 +148,7 @@ df_br <- acled_api(country = c("Brazil"), end_date = "2022-12-01", monadic = F, acled_access = TRUE, + inter_numeric = TRUE, prompt = F) ``` @@ -207,10 +210,10 @@ df_sa <- acled_api(country = c("Brazil", "Colombia"), You could also request the monadic version of the data by setting `monadic = TRUE`: -```{r} +```{r, eval = F} df_sa_monadic <- acled_api(regions = c("South America"), start_date = "2022-01-01", - end_date = "2022-12-01", + end_date = "2022-01-01", monadic = T, acled_access = TRUE, prompt = F) diff --git a/vignettes/articles/acled_transformations.Rmd b/vignettes/articles/acled_transformations.Rmd index aa7e41f..8dd0b07 100644 --- a/vignettes/articles/acled_transformations.Rmd +++ b/vignettes/articles/acled_transformations.Rmd @@ -25,9 +25,7 @@ In our analyses, we often refer to actor types by using text categories (e.g. *S This function allows you to convert your numeric codes into text descriptions, without the time-consuming need of writing out these changes yourself. ```{fun , eval = FALSE} -acled_transform_interactions(df, - only_inters = F) - +acled_transform_interactions(df, only_inters = F) ``` The function requires two arguments: @@ -100,8 +98,7 @@ Keep in mind that you can receive some data in monadic/longer form directly from The function is similar to its counterpart: ```{r, eval = F} -acled_transform_wider(data, - type = "full_actors") +acled_transform_wider(data, type = "full_actors") ``` @@ -132,6 +129,7 @@ df_sa <- acled_api(regions = "South America", acled_access = TRUE, prompt = F) ``` + ```{r, echo=FALSE} library(acledR) @@ -143,25 +141,33 @@ df_sa <- acled_api(regions = "South America", end_date = "2023-06-01", monadic = F, acled_access = TRUE, + inter_numeric = TRUE, prompt = F) ``` -Now that your data are in long format with one actor per row, you can much more easily filter the data to retain only those events involving the "Military Forces of Colombia (2022-)": +Now that your data are in long format with one actor per row, you can much more easily filter the data to retain only those events involving the "ELN: National Liberation Army": ```{r} -mil_colombia <- df_sa %>% - filter(stringr::str_detect(paste(actor1,actor2,assoc_actor_1, assoc_actor_2, sep = ";"), "Military Forces of Colombia (2022-)")) +df_eln <- + df_sa %>% + filter( + # Check main actors + actor1 == "ELN: National Liberation Army" | + actor2 == "ELN: National Liberation Army" | + # Check associate actors + assoc_actor_1 == "ELN: National Liberation Army" | + assoc_actor_2 == "ELN: National Liberation Army" + ) + ``` -In the filtered events there are `r nrow(mil_colombia)` rows, meaning there were `r nrow(mil_colombia)` events where the "Military Forces of Colombia (2022-)" were involved as an actor or associate actor. +In the filtered events there are `r nrow(df_eln)` rows, meaning there were `r nrow(df_eln)` events where the "ELN: National Liberation Army" were involved as an actor or associate actor. Instead of filtering to the events involving a particular actor, you may wish to calculate the number of events in which each actor in the dataset participates. The issue is that an actor may be represented in any of the four actor columns, so you cannot simply sum the number of rows in which an actor appears in one particular column. A simple solution is to transform the dataset into long form and then calculate event counts for each actor. You can begin by using the `acled_transform_longer()` function: ```{r} - df_sa_long <- acled_transform_longer(df_sa, type = "full_actors") - ``` The dataset is now in long form with each row representing a single actor in a single event. You can now count the number of rows for each actor, but only after grouping by **unique** *event_id_cnty*. It is very important to count rows by unique identifiers because when transforming data to long format, events can be represented in multiple rows equal to the number of actors involved in that event. @@ -170,7 +176,9 @@ The dataset is now in long form with each row representing a single actor in a s library(tidyr) library(dplyr) -actors_df_sa <- df_sa_long %>% +actors_df_sa <- + df_sa_long %>% + filter(actor == "ELN: National Liberation Army") %>% group_by(actor) %>% summarise(n_events = n_distinct(unique(event_id_cnty))) @@ -179,10 +187,9 @@ actors_df_sa <- df_sa_long %>% To verify your results, you can filter actor counts to only "Military Forces of Colombia (2022-)". ```{r} - -actors_df_sa %>% - filter(actor == "Military Forces of Colombia (2022-)") %>% - .$n_events +actors_df_sa %>% + filter(actor == "ELN: National Liberation Army") %>% + pull(n_events) ``` The number of events matches the number of rows you got when first filtering by actor. diff --git a/vignettes/get_started.Rmd b/vignettes/get_started.Rmd index 30a27ea..1cf9778 100644 --- a/vignettes/get_started.Rmd +++ b/vignettes/get_started.Rmd @@ -23,30 +23,33 @@ library(dplyr) Welcome! -In this vignette you will receive a brief explanation of how to use ACLED’s R package. Besides this initial walkthrough, you can find more detailed explanations and examples under the 'Utilizing acledR' tab. Alternatively, for information relating to ACLED’s methodology, please visit [ACLED's Knowledge Base](https://acleddata.com/knowledge-base/). +This vignette provides a brief overview of the ACLED R package. You can find more detailed explanations and examples under the 'Utilizing acledR' tab. For general information on ACLED’s methodology, please visit [ACLED's Knowledge Base](https://acleddata.com/knowledge-base/). -The main objectives of this package are (i) to facilitate access to ACLED data in R by providing a wrapper to submit GET requests to ACLED’s API, and (ii) to simplify the manipulation of ACLED data. +The main objectives of this package are: -The general workflow for which this package was designed, and therefore the layout of this vignette, is as follows: +1. Facilitating access to ACLED data via ACLED's API; +2. Simplifying the manipulation of ACLED data. -![Authenticate your API credentials. Request data from ACLED API. Transform data received from the API. Generate initial analysis from the data.](workflow.png) +This package was designed with the following workflow in mind: + +![(a) Authenticate your API credentials. (b) Request data from ACLED API. (c) Transform data received from the API. (d) Generate initial analysis from the data.](workflow.png) You can begin by installing the package: ```{r, eval=FALSE} +# Install acledR +install.packages("acledR") # from CRAN -# Installing the package -install.packages("acledR") # To install the package from CRAN +devtools::install_github("ACLED/acledR") # or from the developer's branch from Github. -devtools::install_github("ACLED/acledR") # To install the developer's branch from Github. -# Loading the package +# Load acledR library(acledR) ``` -## Authenticating your credentials - `acled_update()` +## Authenticating your credentials - `acled_access()` -To be able to access the API, you require an API key. If you are not registered in ACLED's Access portal, you can find it [here](developer.acleddata.com). If you would like a detailed guide on how to create your account and get your API key, please see [ACLED's Access Guide](https://acleddata.com/download/35300/). +ACLED API access require an API key for authentication. To register for API access, please visit ACLED's Access Portal [here](developer.acleddata.com). You can also find a detailed guide on how to create your account and get your API key in [ACLED's Access Guide](https://acleddata.com/download/35300/). Once you are registered, we encourage you to authenticate your credentials by using the `acled_access()` function. This function allows you to test that your credentials are working as intended and save your credentials in your R environment, thus allowing you to avoid the need to manually input your credentials during each data request. @@ -54,26 +57,29 @@ Once you are registered, we encourage you to authenticate your credentials by us acled_access(email = "your_email", key = "your_key") # This is an example, you will need to input your credentials. ``` -```{r,echo=FALSE} +```{r, echo=FALSE} acled_access(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY")) ``` - If the authentication was successful, you will find a message in the console stating "Authorization accepted". ## Requesting data from ACLED’s API - `acled_api()` -Once your credentials are authenticated, you can start requesting data from the API using the `acled_api()` function. The function accepts several fields used to filter data and specify data formatting. For example, you could request data from Argentina in 2022 using the following code chunk to receive a dataframe: +Once your credentials are authenticated, you can start requesting data from the API using the `acled_api()` function. This function accepts several fields used to filter data and specify data formatting. For example, you could request all events in Argentina throughout 2022 as follows: ```{r} -argentinian_data <- acled_api(country = "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 = FALSE, + inter_numeric = TRUE) ``` -Note that while this example uses only three arguments (`country`, `start_date` and `end_date`), `acled_api()` accepts several other useful arguments, descriptions of which can be found in `vignette("acled_api")`. Further note that if you are not using the `acled_access` function to store your credentials, you would also need to specify your email and key when making API requests. +Note that while this example uses only four arguments (`country`, `start_date`, `end_date`, and `inter_numeric`), `acled_api()` accepts several other useful arguments, descriptions of which can be found in `vignette("acled_api")`. If you do not use the `acled_acces` function to store your credentials, you would also need to specify your email and API key to make a request. -Finally, `acled_api()` allows you to request large amounts of data from the API, potentially requiring the subsetting of your requests into multiple smaller requests. You can find more about how `acled_api()` subsets data by visiting `vignette(“acled_api”)`. +Finally, `acled_api()` allows requests for large amounts of data from the API, potentially requiring the subsetting of your requests into multiple smaller requests. You can find more about how `acled_api()` subsets data by visiting `vignette(“acled_api”)`. ```{r, echo=F} glimpse(argentinian_data) @@ -84,7 +90,7 @@ glimpse(argentinian_data) 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 deletions. -To update your dataset you need only to provide the `acled_update` function with 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")`. +To update your dataset you, provide `acled_update` function with 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: @@ -96,18 +102,7 @@ new_data <- acled_update(acledR::acled_old_deletion_dummy, prompts = F) ACLED data has a unique structure which can make data manipulation non-trivial. The `acledR` package provides a suite of functions to simplify data manipulation. You can find a more in-depth treatment of ACLED’s data transformation functions by visiting the `vignette("acled_transformations")`. -### 1. 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`. - -```{r} -transformed_data <- acled_transform_interaction(argentinian_data) - -# Note the inter1 and inter2 columns -head(transformed_data) -``` - -### 2. Reshaping Data: Wide to Long Format - `acled_transform_longer()` +### 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. @@ -119,7 +114,7 @@ head(long_data) 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. -### 3. Reshaping Data: Long to Wide Format - `acled_transform_wider()` +### 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. @@ -131,6 +126,17 @@ head(wide_data) 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`. + +```{r} +transformed_data <- acled_transform_interaction(argentinian_data) +# +# Note the inter1 and inter2 columns +head(transformed_data) +``` + ---- Now your dataset should be ready for you to analyze! Remember to always consult [ACLED's Methodology](https://acleddata.com/resources/) when analyzing ACLED data–it should provide a deeper understanding of ACLED data and your analyses.