diff --git a/.lintr b/.lintr deleted file mode 100644 index 57f9f08..0000000 --- a/.lintr +++ /dev/null @@ -1,6 +0,0 @@ -linters: linters_with_defaults( - line_length_linter = line_length_linter(120) - - ) - -encoding: "UTF-8" diff --git a/vignettes/articles/.trackdown/acled_api.Rmd-chunk_info.rds b/vignettes/articles/.trackdown/acled_api.Rmd-chunk_info.rds deleted file mode 100644 index ab87189..0000000 Binary files a/vignettes/articles/.trackdown/acled_api.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/articles/.trackdown/acled_api.Rmd-header_info.rds b/vignettes/articles/.trackdown/acled_api.Rmd-header_info.rds deleted file mode 100644 index c2ee04b..0000000 Binary files a/vignettes/articles/.trackdown/acled_api.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/articles/.trackdown/acled_deletions_api.Rmd-chunk_info.rds b/vignettes/articles/.trackdown/acled_deletions_api.Rmd-chunk_info.rds deleted file mode 100644 index a60c0f7..0000000 Binary files a/vignettes/articles/.trackdown/acled_deletions_api.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/articles/.trackdown/acled_deletions_api.Rmd-header_info.rds b/vignettes/articles/.trackdown/acled_deletions_api.Rmd-header_info.rds deleted file mode 100644 index 1764880..0000000 Binary files a/vignettes/articles/.trackdown/acled_deletions_api.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/articles/.trackdown/acled_transformations.Rmd-chunk_info.rds b/vignettes/articles/.trackdown/acled_transformations.Rmd-chunk_info.rds deleted file mode 100644 index 5b650ac..0000000 Binary files a/vignettes/articles/.trackdown/acled_transformations.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/articles/.trackdown/acled_transformations.Rmd-header_info.rds b/vignettes/articles/.trackdown/acled_transformations.Rmd-header_info.rds deleted file mode 100644 index 3ea56c8..0000000 Binary files a/vignettes/articles/.trackdown/acled_transformations.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/articles/acled_api.Rmd b/vignettes/articles/acled_api.Rmd index 4025b12..752e04f 100644 --- a/vignettes/articles/acled_api.Rmd +++ b/vignettes/articles/acled_api.Rmd @@ -114,13 +114,28 @@ As is common when executing API calls, handling large volumes of data requires s Imagine you are interested in events from “Brazil” occurring between January 1st, 2022, and December 1st, 2022. -```{r} +```{r, eval = FALSE} +library(acledR) +library(dplyr) + +#Note: This is simply an example–you will need to include your own credentials rather than the email and key placeholders that are included below. + +acled_access(email = "your_email", key = "your_key") + +df_br <- acled_api(country = c("Brazil"), + start_date = "2022-01-01", + end_date = "2022-12-01", + monadic = F, + acled_access = TRUE, + prompt = F) +``` +```{r,echo=FALSE} library(acledR) library(dplyr) #Note: This is simply an example–you will need to include your own credentials rather than the email and key placeholders that are included below. -acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") +acled_access(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY")) df_br <- acled_api(country = c("Brazil"), start_date = "2022-01-01", @@ -130,6 +145,8 @@ df_br <- acled_api(country = c("Brazil"), prompt = F) ``` + + This returns a tibble that includes each ACLED event in “Brazil” during the specified period: ```{r} diff --git a/vignettes/articles/acled_deletions_api.Rmd b/vignettes/articles/acled_deletions_api.Rmd deleted file mode 100755 index d0e27d7..0000000 --- a/vignettes/articles/acled_deletions_api.Rmd +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Deletions API: Keeping your dataset up to date" -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{Deletions API: Keeping your dataset up to date} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r setup, echo=FALSE} -knitr::opts_chunk$set(echo = TRUE) - -defaultW <- getOption("warn") - -options(warn = -1) - -``` - -ACLED is a living dataset, which means changes happen regularly. - -Three types of changes are recurrent in ACLED's dataset: - -- New events - - These are the weekly addition of events, all are published with a new distinctive *event_id_cnty*. -- Updates of previously published events - - In some cases we modify published events, as new information may appear. For example, a particular actor has claimed responsibility over an attack, or the number of fatalities has changed. In these cases, the *event_id_cnty* remains the same, but the new information is updated and the old information overwritten - including the *timestamp*. -- Deletion of events - - In some cases, we have to delete previous events. This happens when new information surfaces indicating that the event no longer fits the scope of ACLED's dataset, or it hints that two events are the same and the events are then merged. In these cases, the event is removed, including the *event_id_cnty*. - -For users with a personal ACLED file, it is advised to check regularly which events are no longer in the actual ACLED dataset, and which have been updated. Otherwise, users risk having an outdated version. In this section we will walk through how to keep your dataset updated with the `acledR` package. - -## Keeping check of updates - `acled_update()` - -As we covered in the more detailed guide about [updating your dataset](https://acleddata.com/download/35179/), in some cases events are updated. When they are updated, their *event_id_cnty* remains the same but all the rest of the information gets updated and overwritten. - -Different from [deleted events](https://acled.github.io/ACLED-api-guide/deleted_endpoint.html), there is no separate API endpoint to check for updated events. When events are updated, their timestamp changes to the timestamp of the update. This means, that you can find the modified events by utilizing `acledR::acled_api()` and providing your latest timestamp (i.e. `max({your ACLED dataset}$timestamp))`) in the `timestamp` argument of the function. If you get duplicated events, these are likely to be updated events, which you should keep only the one with a higher timestamp. - -To simplify this process, `acledR` includes a function which makes the update for you by following the steps previously explained: `acled_update`. - -```{r, eval=F} -acled_update( - df, - additional_countries = NULL, - regions = NULL, - event_types = NULL, - acled_access = TRUE, - email = NULL, - key = NULL, - deleted = TRUE, - prompts = T) -``` - -The function is composed of the following arguments: - `df`: The dataframe to update, it has to have the same structure as ACLED's dyadic dataframes (i.e. the result of `acled_api()`) - `start_date`: Along with `end_date` these determine the temporal range for your update. They default to the date range of `df`. - `end_date`: Along with `start_date` these determine the temporal range for your update. They default to the date range of `df`. - `countries`: In case of your dataset to include particular countries, you can add them here so that the function filter new events to those countries. - `regions`: In case of your dataset to include particular regions, you can add them here so that the function filter new events to those regions. - `event_types`: In case of your dataset to include particular event_types, you can add them here so that the function filter new events to those event_types. - `acled_acess`: If you have already utilized `acled_acess()`, you can set this option as TRUE (default) and you wont be required to input email or key. - `email`: The email registered in [ACLED's Access Portal](https://developer.acleddata.com/). Not required if `acled_access = TRUE`. - `key`: The key registered in [ACLED's Access Portal](https://developer.acleddata.com/). Not required if `acled_access = TRUE`. - `deleted`: If TRUE, this function will also deal with deleted events, utilizing [ACLED API's deleted endpoint](https://acled.github.io/acledR/articles/acled_deletions_api.html). - `prompts`: Use this option to supress or allow prompts regarding your call. See `acled_api()`. - -`acled_update()` will utilize the dataset you provide to gather new events based on the timestamp, and add them to the original dataset, as well as remove any deleted events (if `deleted = TRUE`). - -## Examples - -In this section we will show how to use `acled_update` to keep your datasets updated. - -Load the older dataset: - -```{r, eval = T, message=FALSE} -library(acledR) -library(lubridate) -library(dplyr) -``` - -```{r} -acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") # This is an example, you will need to input your credentials. - -argen_dummy_acled_file <- acledR::acled_old_dummy # Here is our old personal ACLED dataset -``` - -When was the last time you gathered your dataset? The snippet below checks that. - -```{r} -latest_timestamp_unix <- max(argen_dummy_acled_file$timestamp) - -latest_timestamp <- as_datetime(latest_timestamp_unix) -``` - -The dataset has not been updated since `r print(latest_timestamp)`, so you need to update it. To do so, you just have to utilize `acled_update()`. In order to keep the update within the dates of our dataset, you can ignore the `start_date` and `end_date` arguments. Similarly, we going to keep `deleted=TRUE` to also remove deleted events. - -```{r} - -new_argen_dataset <- acled_update(argen_dummy_acled_file, - additional_countries = "Argentina", - acled_access = T, - prompts = FALSE) -``` - -Now your dataset captures modified and newly created events. - -Best of luck! - -```{r, echo=F} -options(warn = defaultW) -``` diff --git a/vignettes/articles/acled_transformations.Rmd b/vignettes/articles/acled_transformations.Rmd index 2314183..3c271b5 100644 --- a/vignettes/articles/acled_transformations.Rmd +++ b/vignettes/articles/acled_transformations.Rmd @@ -119,11 +119,11 @@ In this section you can walk through a potential use case for the transformation For this example, assume that you are interested in data from “South America” during the first half of 2023. **NOTE**: The email and key values below are only examples. You should provide your own credentials that you can create by using [ACLED’s website](https://apidocs.acleddata.com/get_started.html#getting-your-api-key). -```{r} +```{r, eval = False} library(acledR) -acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") +acled_access(email = "your_email", key = "your_key") df_sa <- acled_api(regions = "South America", start_date = "2023-01-01", @@ -132,7 +132,19 @@ df_sa <- acled_api(regions = "South America", acled_access = TRUE, prompt = F) ``` +```{r, echo=FALSE} + +library(acledR) +acled_access(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY")) + +df_sa <- acled_api(regions = "South America", + start_date = "2023-01-01", + end_date = "2023-06-01", + monadic = F, + acled_access = 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-)": ```{r} diff --git a/vignettes/articles/acled_update.Rmd b/vignettes/articles/acled_update.Rmd index e406ed6..29098ea 100644 --- a/vignettes/articles/acled_update.Rmd +++ b/vignettes/articles/acled_update.Rmd @@ -90,9 +90,14 @@ library(lubridate) library(dplyr) ``` -```{r} +```{r, eval=FALSE} acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") # This is an example, you will need to input your credentials. +argen_dummy_acled_file <- acledR::acled_old_dummy # Here is our old personal ACLED dataset +``` +```{r, echo=FALSE} +acled_access(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY")) # This is an example, you will need to input your credentials. + argen_dummy_acled_file <- acledR::acled_old_dummy # Here is our old personal ACLED dataset ``` diff --git a/vignettes/get_started.Rmd b/vignettes/get_started.Rmd index ce8f28d..b1c8180 100644 --- a/vignettes/get_started.Rmd +++ b/vignettes/get_started.Rmd @@ -54,7 +54,7 @@ Once you are registered, we encourage you to authenticate your credentials by us acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") # This is an example, you will need to input your credentials. ``` -```{r} +```{r,echo=FALSE} acled_access(email = Sys.getenv("EMAIL_ADDRESS_EXAMPLES"), key = Sys.getenv("EXAMPLES_KEY")) ```