---
title: "Get Started"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Get Started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
``` {r, echo=FALSE,include = FALSE}
library(acledR)
library(dplyr)
```
This vignette provides a brief overview of the acledR package. You can find more detailed explanations and examples under the 'Using acledR' tab. For general information on ACLED’s methodology, please visit [ACLED's Knowledge Base](https://acleddata.com/conflict-data/knowledge-base).
The main objectives of this package are:
1. Facilitating access to ACLED data via ACLED's API
2. Simplifying the manipulation of ACLED data
You can begin by installing and then loading the package:
```{r, eval=FALSE}
# Install acledR
install.packages("acledR") # from CRAN
devtools::install_github("ACLED/acledR") # or from github.
# Load acledR
library(acledR)
```
## Requesting data from ACLED’s API - `acled_api()`
After authenticating your credentials, you can request data from the API using the `acled_api()` function. This function accepts several fields for filtering and formatting ACLED data. As a running example, let's request all events in Argentina throughout 2022:
```{r, eval=FALSE}
argentinian_data <- acled_api(
# Email address associated with your ACLED account
email = Sys.getenv("ACLED_API_EMAIL"),
# Password associated with your ACLED account. If left blank, you will be prompted to enter interactively.
password = Sys.getenv("ACLED_API_PASSWORD"),
# Country of interest
country = "Argentina",
# Earliest date for requested events
start_date ="2022-01-01",
# Last date for requested events
end_date = "2022-12-31",
# Request 'inter codes' in numeric rather than text form
inter_numeric = TRUE
)
```
Note that while this example uses only five arguments (`country`, `start_date`, `end_date`, `inter_numeric`, and `prompt`), `acled_api()` accepts several other useful arguments, descriptions of which can be found in `vignette("acled_api")`.
The `acled_api()` function does not place constraints on the amount of data requested. As a result, users are able to make potentially very large requests (e.g. events for all countries and years at once) which might strain ACLED's API. For performance reasons, `acled_api()` breaks large requests into multiple smaller requests. You can find more about how `acled_api()` subsets requests by visiting in the `acled_api()` vignette.
## Updating ACLED Data - `acled_update()`
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 event deletions.
To update your dataset, provide the `acled_update` function 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:
```{r, eval = FALSE}
new_data <- acled_update(acledR::acled_old_deletion_dummy,
email = Sys.getenv("ACLED_API_EMAIL"),
password = Sys.getenv("ACLED_API_PASSWORD"),
inter_numeric = TRUE,
prompts = FALSE)
```
## Transforming ACLED Data - `acled_transform_*`
ACLED data has a unique structure which can complicate data manipulation. The `acledR` package provides a suite of functions to simplify this process. You can find a more in-depth treatment of ACLED’s data transformation functions by visiting the `vignette("acled_transformations")`.
### 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.
```{r}
long_data <- acled_transform_longer(acledR::acled_old_dummy, 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`. 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.
### 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.
```{r}
wide_data <- acled_transform_wider(long_data, type = "full_actors")
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`. Note further that the `acled_api()` function returns interaction codes as text strings by default, making this function most useful when the original API call included the parameter value `inter_numeric = TRUE`, as in the running example.
```{r}
transformed_data <- acled_transform_interaction(acledR::acled_old_dummy)
# Note the inter1 and inter2 columns
head(transformed_data)
```
----