diff --git a/.lintr b/.lintr new file mode 100644 index 0000000..57f9f08 --- /dev/null +++ b/.lintr @@ -0,0 +1,6 @@ +linters: linters_with_defaults( + line_length_linter = line_length_linter(120) + + ) + +encoding: "UTF-8" diff --git a/DESCRIPTION b/DESCRIPTION index 9fb9503..f6aa323 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -45,8 +45,8 @@ Imports: RoxygenNote: 7.2.3 Depends: R (>= 3.5.0) -URL: https://github.com/billingtt/acledR, https://billingtt.github.io/acledR/, https://acled.github.io/acledR/ -BugReports: https://github.com/billingtt/acledR/issues +URL: https://github.com/ACLED/acledR, https://acled.github.io/acledR/ +BugReports: https://github.com/ACLED/acledR/issues Suggests: knitr, janitor, diff --git a/R/.lintr b/R/.lintr deleted file mode 100644 index ee4c64b..0000000 --- a/R/.lintr +++ /dev/null @@ -1 +0,0 @@ -lint_config: with_defaults(line_length_linter = NULL) \ No newline at end of file diff --git a/README.Rmd b/README.Rmd index 9cbeb01..7f52d0a 100755 --- a/README.Rmd +++ b/README.Rmd @@ -20,6 +20,11 @@ knitr::opts_chunk$set( [![codecov](https://codecov.io/gh/ACLED/acledR/graph/badge.svg?token=TDJodXhEvx)](https://codecov.io/gh/ACLED/acledR) +Welcome to ACLED's official R package! With this package we want to bring you an even more convenient way to access ACLED data, building on top of our existing API. + +In this repo you can find the source code of the package, as well as the documentation. You can also visit https://acled.github.io/acledR/ for more information and walkthroughs on how to use the package. + + # Overview This package provides tools to extract and manipulate data from the [Armed Conflict Location and Event Data Project (ACLED)](https://acleddata.com/). @@ -39,7 +44,7 @@ Since the package repo is currently private, you need to tell R and Github that usethis::create_github_token() ``` -After you've copied the PAT from the browser, return to R and run this, which will store the PAT locally. +After you've copied the PAT from the browser and saved it somewhere safe, return to R and run this, which will store the PAT locally. ```{r, eval=F} # paste the token where it says YourPAT @@ -48,15 +53,6 @@ credentials::set_github_pat("YourPAT") Sys.getenv("GITHUB_PAT") ``` -I recommend also setting the PAT in your `.Rprofile` so it's stored for all R sessions (i.e., you don't have to save the PAT and paste it in each time you re-install). - -```{r, eval=F} -# to set your PAT for all R sessions, run -file.edit(file.path("~", ".Rprofile")) -# and then paste credentials::set_github_pat("YourPAT") into the .Rprofile script -# save the file -``` - Now you can install the package and it will automatically locate your PAT. ```{r, eval=F} @@ -67,8 +63,12 @@ devtools::install_github("ACLED/acledR") ## Installation (for public use) -Until the acledR package gets added into the Comprehensive R Archive Network (CRAN), users can utilize devtools to install the package from Github. Thankfully, the installation is rather simple. You can install it through the following code: - +The package is on the process to get submited to the Comprehensive R Archive Network (CRAN). In the meantime, you can install the package from Github. ```{r, eval = F} devtools::install_github("ACLED/acledR") ## if you are interested in a particular branch, please add a 'ref' argument. ``` + +Once the package is uploaded to CRAN, you can install it with the following command: +```{r, eval = F} +install.packages("acledR") +``` diff --git a/inst/rmarkdown/templates/template1.Rmd b/inst/rmarkdown/templates/template1.Rmd deleted file mode 100644 index 96fe4c0..0000000 --- a/inst/rmarkdown/templates/template1.Rmd +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: "Automatic Report of `r params$country`" -output: - html_document: - toc: true - fig_crop: no - toc_float: true - pdf_document: - toc: true - fig_crop: no -params: - acled_email: email - acled_key: key - end_date: !r Sys.Date() - country: country - printcode: TRUE - start_date: "1997-01-01" - data: data -subtitle: "Country: `r params$country` - From: `r params$start_date` to `r params$end_date`" - ---- - - - - -```{r loading what we need, echo=FALSE} -library(acledR) -library(knitr) -library(kableExtra) -library(dplyr) -library(tidyr) -library(plotly) -library(viridis) -library(mapview) -library(stringr) -library(sf) - -defaultW <- getOption("warn") - -options(warn = -1) - - -``` - -## 1. General statistics - -```{r table of statistics, echo=FALSE} - - -table_data_source <- acled_transform(params$data, type = "source") %>% - group_by(source) %>% - summarise(frequency = n()) %>% - arrange(-frequency) - -unique_number_of_sources <- length(unique(table_data_source$source)) - -table_data_actor <- acled_transform(params$data, type = "full_actors")%>% - group_by(actor) %>% - summarise(frequency = n()) %>% - arrange(-frequency) - -unique_number_of_actors <- length(unique(table_data_actor$actor)) - - -table_data <- params$data %>% - mutate(event_date = as.character(event_date))%>% - group_by(country) %>% - summarise(total_events = n(), - total_fatalities = sum(fatalities), - eventful_days = n_distinct(event_date)) -table_data$total_actors <- unique_number_of_actors -table_data$total_sources <- unique_number_of_sources - -table_data <- table_data %>% - rename(Country=country, "Total Events" = total_events, "Reported Fatalities" = total_fatalities, "Eventful Days" = eventful_days, "Total Actors" = total_actors, "Total Sources" = total_sources) - -kbl(table_data) %>% - kable_styling() - -``` - -### 1.1 Sub-Event Types frequencies -```{r Sub-Event type,echo = FALSE, fig.align='right',fig.width=10,fig.height=7} -sub_event_table <- params$data %>% - group_by(event_type,sub_event_type) %>% - summarise(frequency = n()) %>% - filter(event_type != "Strategic developments") - -zu <-ggplot(sub_event_table,aes(x=frequency,fill=event_type, - text= c( - paste0("Sub-Event type: ", sub_event_type,"\n", - "Event Type: ",event_type, "\n", - "Frequency: ", frequency))))+ - geom_bar(aes(y=reorder(sub_event_type,frequency)),stat="identity", size=10)+ - scale_x_continuous(trans="log10")+ - labs(title = "Magnitude of Sub-Event types in a log10 scale", - x="Frequency in a 10 logarithmic scale", - y="Sub-Event Types", - fill = "Event Types") - -ggplotly(zu, tooltip = "text") - -``` -### 1.2 Most Frequent Actors - -```{r actor breakdown, echo = FALSE, fig.align='right',fig.width=10,fig.height=7} -fu <- ggplot(slice_max(table_data_actor,order_by = frequency,n=30), - aes(frequency,reorder(actor,frequency),text=c(paste0("Actor: ", actor,"\n","Frequency: ", frequency))))+ - geom_bar(stat="identity", fill= "slateblue3")+ - theme(legend.position="none")+ - labs(title = "Top 30 most frequent actors in the dataset", - x="Frequency", - y="Actor") - -ggplotly(fu, tooltip = "text") -``` - -### 1.3 Most Frequent Sources - -```{r sources brealdown, echo = FALSE, fig.align='right',fig.width=10,fig.height=7} -su <- ggplot(slice_max(.data = table_data_source,order_by = frequency, n=30),aes(frequency,reorder(source,frequency),fill=source,text=c(paste0("Source: ", source,"\n","Frequency: ", frequency)))) + - geom_bar(stat="identity",fill= "slateblue3")+ - theme(legend.position = "none")+ - labs(title = "Top 30 most frequent sources utilized in the dataset", - x= "Frequency", - y= "Source") -ggplotly(su,tooltip = "text") -``` - - -## 2. Monthly average of events in `r params$country` - -```{r moving avergeas, echo = FALSE, fig.align='right',fig.width=10,fig.height=7} - -df1 <- params$data %>% - generate_counts(., - unit_id = "country", - time_id = "event_date", - time_target = "month") - -# Generate 3 moving average of total events per month -df1m <- - generate_movers(data = df1, - var = "total_events", - unit_id = "country", - time_id = "event_month", - slide_funs = "mean", - slide_periods = 3) - -average_per_year <- df1 %>% - mutate(year = lubridate::floor_date(event_month,unit = "year")) %>% - group_by(year) %>% - summarise(average_events_per_month = mean(total_events)) - -ha <- ggplot(df1m, aes(x=event_month, text = paste0("Month & Year: ",lubridate::format_ISO8601(event_month,precision = "ym"),"\n","3 months moving average: ", total_events_moving_mean_3, "\n", "Total number of events this month: ", total_events)))+ - geom_point(aes(y=total_events))+ - geom_line(aes(y=total_events_moving_mean_3, group=1, color = "3 Months Moving Average"))+ - # geom_line(data=average_per_year,aes(x=year,y=average_events_per_month), color = "green")+ - labs(title = paste0("Moving 3 months average of total events in ", params$country), - x= "Month - Year", - y= "Number of Events")+ - scale_colour_manual(name = 'Legend', - values=c('3 Months Moving Average' = 'blue')) - -ggplotly(ha, tooltip = "text") - -``` - - - -## 3. Map of events distribution in the country per admin1 levels - -```{r map of stuff,echo = FALSE, fig.align='right',fig.width=10,fig.height=7} - - -admin1_country <- raster::getData(name = "GADM", country = params$country, level = 1) %>% - # convert to sf object - st_as_sf() - -country_counts <- - params$data %>% - # full_join(select(admin1_country, NAME_1, NAME_0), by = c("admin1" = "NAME_1", "country" = "NAME_0")) %>% - group_by(admin1) %>% - tally() %>% - full_join(admin1_country, by = c("admin1" = "NAME_1")) %>% - mutate(n = case_when( - is.na(n) ~ 0L, - TRUE ~ n - )) %>% - sf::st_as_sf() - -library(mapview) -mapviewOptions(fgb = FALSE) # needed when creating web pages -mapview(country_counts["n"], at = seq(1,2500,200)) - -``` - -## 4. Strategic Developments - -Strategic developments are events coded by ACLED, not because of them being events of political violence, but because of these being events that may trigger future events of political violence. As such, it is important to know that these may not be sistematically coded the same way. However, Users may found it useful to know which are the latest strategic developments. - -### 4.1 Number of Strategic Developments -```{r strategic develop[ments counts} -strategic_devs_counts <- params$data %>% - filter(event_type == "Strategic Development") %>% - group_by(sub_event_type) %>% - summarise("Number of Strategic Developments" = n())%>% - ggplot(aes(x+sub_event_type,y="Number of Strategic Developments"))+ - geom_bar()+ - labs(title = "Strategic Development counts", - x = "Type of Strategic Development", - y = "Number of Events") -``` - -### 4.2 Stream of latest Strategic Developments - -```{r Latest strategic developments} - -strategic_devs <- params$data %>% - filter(event_type == "Strategic Developments") %>% - select(event_id_cnty, event_date,Sub_event_type,actor1,assoc_actor_1,actor2,assoc_actor_2, region, country, admin1,admin2,admin3, - location,latitude,longitude,source,notes) %>% - arrange(-event_date) %>% - slice_head(n=10) -``` - - - diff --git a/test.r b/test.r deleted file mode 100644 index 1f5f90d..0000000 --- a/test.r +++ /dev/null @@ -1,30 +0,0 @@ -# library(tidyverse) -# library(acledR) -# -# acled_multipliers <- read.csv("/Users/lfagli/Documents/Github/acledPy/data/acledpy_multipliers.csv") -# -# save(acled_multipliers,file = "data/acled_multipliers.rda") -# -# -# -# -# - # library(trackdown) -# -# rpkgpath <- "Data Management/R Package/Documentation docs 4 feedback" -# -# # acled_api - Ready -# # trackdown::download_file(shared_drive = "ACLED Management",gpath=rpkgpath,file = "~/GitHub/acledR/vignettes/articles/acled_api.rmd") -# -# # acled_transformations - ready -# # trackdown::download_file(shared_drive = "ACLED Management",gpath=rpkgpath,file = "C:/Users/luki9/Documents/GitHub/acledR/vignettes/articles/acled_transformations.Rmd") -# -# -# # acled_update - Ready -# trackdown::download_file(shared_drive = "ACLED Management",gpath=rpkgpath,file = "C:/Users/luki9/Documents/GitHub/acledR/vignettes/articles/acled_update.Rmd") -# - - # rpkgpath <- "Data Management/R Package/Documentation docs 4 feedback/Methodology vignettes" - -# acled_codebook - ready - # trackdown::download_file(shared_drive = "ACLED Management",gpath=rpkgpath,file = "C:/Users/luki9/Documents/GitHub/acledR/vignettes/acled_codebook.Rmd") diff --git a/vignettes/.trackdown/acled_codebook.Rmd-chunk_info.rds b/vignettes/.trackdown/acled_codebook.Rmd-chunk_info.rds deleted file mode 100644 index e28e5f6..0000000 Binary files a/vignettes/.trackdown/acled_codebook.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/acled_codebook.Rmd-header_info.rds b/vignettes/.trackdown/acled_codebook.Rmd-header_info.rds deleted file mode 100644 index fb2d6f3..0000000 Binary files a/vignettes/.trackdown/acled_codebook.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/acled_deletions_api.Rmd-chunk_info.rds b/vignettes/.trackdown/acled_deletions_api.Rmd-chunk_info.rds deleted file mode 100644 index 3852442..0000000 Binary files a/vignettes/.trackdown/acled_deletions_api.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/acled_deletions_api.Rmd-header_info.rds b/vignettes/.trackdown/acled_deletions_api.Rmd-header_info.rds deleted file mode 100644 index 1764880..0000000 Binary files a/vignettes/.trackdown/acled_deletions_api.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/acled_sources.Rmd-chunk_info.rds b/vignettes/.trackdown/acled_sources.Rmd-chunk_info.rds deleted file mode 100644 index 6bb96c4..0000000 Binary files a/vignettes/.trackdown/acled_sources.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/acled_sources.Rmd-header_info.rds b/vignettes/.trackdown/acled_sources.Rmd-header_info.rds deleted file mode 100644 index 0106a60..0000000 Binary files a/vignettes/.trackdown/acled_sources.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/actors_interactions.Rmd-chunk_info.rds b/vignettes/.trackdown/actors_interactions.Rmd-chunk_info.rds deleted file mode 100644 index 509b2c5..0000000 Binary files a/vignettes/.trackdown/actors_interactions.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/actors_interactions.Rmd-header_info.rds b/vignettes/.trackdown/actors_interactions.Rmd-header_info.rds deleted file mode 100644 index 2e73bbf..0000000 Binary files a/vignettes/.trackdown/actors_interactions.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/event_types.Rmd-chunk_info.rds b/vignettes/.trackdown/event_types.Rmd-chunk_info.rds deleted file mode 100644 index 13b1afe..0000000 Binary files a/vignettes/.trackdown/event_types.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/event_types.Rmd-header_info.rds b/vignettes/.trackdown/event_types.Rmd-header_info.rds deleted file mode 100644 index f6c493e..0000000 Binary files a/vignettes/.trackdown/event_types.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/fatalities.Rmd-chunk_info.rds b/vignettes/.trackdown/fatalities.Rmd-chunk_info.rds deleted file mode 100644 index 2d9d8e9..0000000 Binary files a/vignettes/.trackdown/fatalities.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/fatalities.Rmd-header_info.rds b/vignettes/.trackdown/fatalities.Rmd-header_info.rds deleted file mode 100644 index 5c8f9bd..0000000 Binary files a/vignettes/.trackdown/fatalities.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/geography.Rmd-chunk_info.rds b/vignettes/.trackdown/geography.Rmd-chunk_info.rds deleted file mode 100644 index 396b832..0000000 Binary files a/vignettes/.trackdown/geography.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/geography.Rmd-header_info.rds b/vignettes/.trackdown/geography.Rmd-header_info.rds deleted file mode 100644 index 8e23256..0000000 Binary files a/vignettes/.trackdown/geography.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/time.Rmd-chunk_info.rds b/vignettes/.trackdown/time.Rmd-chunk_info.rds deleted file mode 100644 index 5325df2..0000000 Binary files a/vignettes/.trackdown/time.Rmd-chunk_info.rds and /dev/null differ diff --git a/vignettes/.trackdown/time.Rmd-header_info.rds b/vignettes/.trackdown/time.Rmd-header_info.rds deleted file mode 100644 index 3d9136d..0000000 Binary files a/vignettes/.trackdown/time.Rmd-header_info.rds and /dev/null differ diff --git a/vignettes/acled_codebook.Rmd b/vignettes/acled_codebook.Rmd deleted file mode 100755 index 8e71594..0000000 --- a/vignettes/acled_codebook.Rmd +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "ACLED Codebook" -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{ACLED Codebook} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - - -Pages in the ACLED Codebook tab describe the variables found in ACLED's data, while also providing examples of their use. You can consult the complete guide summarizing ACLED's methodology [here](https://acleddata.com/download/2827/) for a more thorough description of the methodology underlying each column. - -# ACLED Overview - -The ACLED project codes and standardizes reported information on the type, agents, location, date, and other characteristics of events of political violence, demonstrations, and politically relevant non-violent events (referred to as 'Strategic developments'). ACLED focuses on tracking a range of violent and non-violent actions by political agents, including governments, rebels, militias, identity groups, political parties, external actors, rioters, protesters and civilians. - - -The fundamental unit of observation in ACLED is the *event*. Events involve designated actors -- e.g. a named rebel group, a militia or state forces. They occur at a specific named location (identified by name and geographic coordinates) and on a specific day. For more information on what qualifies as an event, and how ACLED codes long-running conflicts, please see our [knowledge base](https://acleddata.com/knowledge-base/how-are-events-disaggregated/). Every event is described by information in a standardized set of columns comprising ACLED’s core dataset. Below you can find a brief description of each column. - -## Column List - -```{r, echo = FALSE, warning=F, message=FALSE} -library(kableExtra) -library(dplyr) - - -returned_data_acled <- data.frame(`Column Name` = c("event_id_cnty", "event_date", "year", "time_precision", "disorder_type", - "event_type", "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", "timestamp"), - Type = c("string", "date", "double", "double", "string", "string", "string", "string", "string", "double", - "string", "string", "double", "double", "string", "double", "string", "string", "string", "string", - "string", "string", "double", "double", "double", "string", "string", "string", "double", - "string", "double"), - Description = c("A unique alphanumeric event identifier by number and country acronym. This identifier remains constant even when the event details are updated.", - "The date on which the event took -place. Recorded as Year-Month-Day.", "The year in which the event took -place.", - "A numeric code between 1 and 3 -indicating the level of precision of -the date recorded for the event. -The higher the number, the lower -the precision.", - "The disorder category an event -belongs to. -", - "The type of event; further -specifies the nature of the event.", "A subcategory of the event type.", "One of two main actors involved -in the event (does not necessarily -indicate the aggressor).", - "Actor(s) involved in the event -alongside ‘Actor 1’ or actor -designations that further identify -‘Actor 1’", "A numeric code between 0 and -8 indicating the type of ‘Actor 1’. -", - "One of two main actors involved -in the event (does not necessarily -indicate the target or victim).", "Actor(s) involved in the event -alongside ‘Actor 2’ or actor -designation further identifying -‘Actor 2’. ", - "A numeric code between 0 to 8 -indicating the type of ‘Actor 2’.", "A two-digit numeric code -(combination of ‘Inter 1’ and ‘Inter -2’) indicating the two actor types -interacting in the event.", - "This column indicates whether -the event involved civilian -targeting. ", "A unique three-digit numeric -code assigned to each country or -territory according to ISO 3166.", - "The region of the world where the -event took place.", "The country or territory in which -the event took place.", - "The largest sub-national -administrative region in which the -event took place.", - "The second largest sub-national administrative region in which the event took place.", - "The third largest sub-national administrative region in which the event took place.", - "The name of the location at which -the event took place.", "The latitude of the location in -four decimal degrees notation -(EPSG:3857).", "The longitude of the location in -four decimal degrees notation -(EPSG:3857).", - "A numeric code between 1 and -3 indicating the level of certainty -of the location recorded for the -event. The higher the number, -the lower the precision.", - "The sources used to record the -event. Separated by a semicolon.", "An indication of the geographic -closeness of the used sources to -the event", "A short description of the event.", - "The number of reported fatalities -arising from an event. When there -are conflicting reports, the most -conservative estimate is recorded", "Additional structured information -about the event. Separated by a -semicolon.", - "An automatically generated Unix timestamp that represents the exact date and time an event was last uploaded to the ACLED API."), check.names = F -) - -returned_data_acled %>% - kable(align=rep('c')) %>% - kable_styling("striped", full_width = F) %>% - column_spec(2, width = "20em") %>% - column_spec(3, width = "50em") - -``` - -## ACLED Help - -Rather than referring to this table during coding, and to provide a deeper understanding of a column’s meaning, you can use the `acledR::acled_help()` function. This function will redirect you to the relevant documentation for the column in question. - -```{r,eval=FALSE} - -acled_help(column = NULL) - -``` - -The function is very straightforward, requiring only one argument. `column` refers to the column for which you would like to be provided with more information. - -**Note**: `acled_help()` only supports one column at a time. - -For example, if you would like to know more about the *fatalities* column, you can run`acled_help(column="fatalities")`, prompting the fatalities vignette to appear in the RStudio Help pane. - -While some columns have their own vignette, e.g. fatalities; others may be grouped together with documentation of similar columns, e.g. admins are in the geographical vignette. diff --git a/vignettes/acled_codebook_cache/html/__packages b/vignettes/acled_codebook_cache/html/__packages deleted file mode 100644 index 1ca8e77..0000000 --- a/vignettes/acled_codebook_cache/html/__packages +++ /dev/null @@ -1,2 +0,0 @@ -kableExtra -dplyr diff --git a/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.RData b/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.RData deleted file mode 100644 index ce3d865..0000000 Binary files a/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.RData and /dev/null differ diff --git a/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.rdb b/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.rdb deleted file mode 100644 index 0b2efd5..0000000 Binary files a/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.rdb and /dev/null differ diff --git a/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.rdx b/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.rdx deleted file mode 100644 index fb7c491..0000000 Binary files a/vignettes/acled_codebook_cache/html/unnamed-chunk-2_c9e325535bb706abfd651628c829b57b.rdx and /dev/null differ diff --git a/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.RData b/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.RData deleted file mode 100644 index 2265c31..0000000 Binary files a/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.RData and /dev/null differ diff --git a/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.rdb b/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.rdb deleted file mode 100644 index e69de29..0000000 diff --git a/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.rdx b/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.rdx deleted file mode 100644 index 6fb2189..0000000 Binary files a/vignettes/acled_codebook_cache/html/unnamed-chunk-3_fca967ebd16904e05c9b014e76f67b71.rdx and /dev/null differ diff --git a/vignettes/get_started.Rmd b/vignettes/get_started.Rmd index 7fa6b29..8747a49 100644 --- a/vignettes/get_started.Rmd +++ b/vignettes/get_started.Rmd @@ -23,9 +23,15 @@ library(dplyr) Welcome! -In this vignette you are going to get a brief explanation on how the package works and how to get started with its core functions. Aside from this walkthrough, you are going to be able to find more detailed explanations and examples under the ACLED Codebook Tab and Articles tab. Alternatively, for metholodgy-related questions, please visit [ACLED's Knowledge Base](https://acleddata.com/knowledge-base/). +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 ACLED Codebook Tab and Utilizing acledR tab. Alternatively, for information relating to ACLED’s methodology, please visit [ACLED's Knowledge Base](https://acleddata.com/knowledge-base/). -Naturally, the first step is loading installing the package: +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 general workflow for which this package was designed, and therefore the layout of this vignette, is as follows: + +![Authenticate your API credentials. Request data from ACLED API. Transform data received from the API. Generate initial analysis from the data.](workflow.png) + +You can begin by installing the package: ```{r, eval=FALSE} @@ -38,20 +44,11 @@ devtools::install_github("ACLED/acledR") # To install the developer's branch fro library(acledR) ``` - -The main objective of this package is to allow R users easier access to ACLED data by providing a wrapper to submit GET requests to the ACLED's API, as well as other functions to manipulate ACLED data. - -This means users can request data through a more acccesible approach rather than utilizing lengthy and often comboluted API calls. The general workflow for which this package was designed was as follows: - -![Authenticate your API credentials. Request data from ACLED API. Transform data received from the API. Generate initial analysis from the data.](workflow.png) - -This vignette will follow the same general layout. - ## Authenticating your credentials - `acled_update()` -To be able to access the API, you require an API key. If you are not registered in ACLED's Access portal, you can visit it [here](developer.acleddata.com). If you would like a detail guide on how to create your account and get your API, you can utilize [ACLED's Access Guide](https://acleddata.com/download/35300/). +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/). -Once you are registered, we encourage you to save your credentials and authenticate them through `acled_access()`. This function allows you to test that your credentials are working as intended, and save them into your enviorment, which in turn allows users to avoid having to input the credentials every time there is a request to the API. +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. ```{r} acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") # This is an example, you will need to input your credentials. @@ -59,21 +56,18 @@ acled_access(email = "acledexamples@gmail.com", key = "M3PWwg3DIdhHMuDiilp5") # If the authentication was successful, you will find a message in the console stating "Authorization accepted". -## Requesting data from ACLED API - `acled_api()` +## Requesting data from ACLED’s API - `acled_api()` -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. +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: ```{r} 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 (`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. +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. -Finally, acled_api allows you to gather vast amounts of data from the API, however, to make these big calls of data, we need to segment these calls into multiple smaller ones. Thus, the function includes a `prompt` parameter which is set to `TRUE` (default). When `TRUE`, you will receive a message with the number of API requests that this will require (an important aspect to consider if you have a limited number of calls), and a confirmation message if you want to request data. Alternatively, when it is marked as `FALSE`, you will not receive the prompt and execute the required number of API requests -The data you receive will be a data frame of the events throughout the request dates and the requested region/country. We can inspect the Argentinian data we gathered now. +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”). ```{r, echo=F} glimpse(argentinian_data) @@ -82,11 +76,11 @@ glimpse(argentinian_data) ## Updating ACLED Data - `acled_update()` -To ensure your ACLED dataset remains current and accurate, regular updates are essential. The acledR package facilitates this process with 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. +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. -For utilizing `acled_update`, you must provide it the old dataset to update. There other options that you can also utilize, which are mostly aimed at giving you options on how to update the dataset. You can find more information in `vignette("acled_update") +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") -Here is an example of how to use `acled_update()` to update an old dataset: +Here is an example of how you can use `acled_update()` to update an old dataset: ```{r} new_data <- acled_update(acledR::acled_old_deletion_dummy, prompts = F) @@ -94,7 +88,7 @@ new_data <- acled_update(acledR::acled_old_deletion_dummy, prompts = F) ## Transforming ACLED Data - `acled_transform_*` -The `acledR` package provides a suite of functions to manipulate and transform ACLED data, these may aid you on simplifying part of the transformations required for your desired analysis. You can visit all the information obout our transformation functions in vignette("acled_transformations"). +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()` @@ -117,11 +111,11 @@ long_data <- acled_transform_longer(argentinian_data, type = "full_actors") head(long_data) ``` -You can specify the type of transformation using the type argument, choosing from `full_actors`, `main_actors`, `assoc_actors`, or `source`. This function provides flexibility and control over the transformation process, allowing you to tailor the data structure to your specific needs. +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()` -Conversely, the `acled_transform_wider()` function enables you to pivot your data back to a wide format, useful if you have previously used `acled_transform_longer()` and wish to revert to the original data structure. +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. ```{r} wide_data <- acled_transform_wider(long_data, type = "full_actors") @@ -129,8 +123,8 @@ wide_data <- acled_transform_wider(long_data, type = "full_actors") head(wide_data) ``` -Like its counterpart, this function requires the data and type arguments, ensuring consistency and ease of use across the transformation functions. +Like its counterpart, this function requires the data and type arguments. ---- -Now your dataset should be ready for you to analyse! Remember to always consult [ACLED's Methodology](https://acleddata.com/resources/) when analysing to get a better understanding of our dataset. +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.