-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
78 lines (48 loc) · 4.51 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
readRenviron(".Renv") # read in local file with personal ACLED access information
```
# Automated Retrieval of ACLED Conflict Event Data
<!-- badges: start -->
[](https://CRAN.R-project.org/package=acled.api/)
[](https://lifecycle.r-lib.org/articles/stages.html#stable/)
[](https://app.travis-ci.com/gitlab/chris-dworschak/acled.api/)
[](https://creativecommons.org/licenses/by-nc/4.0/)
[](https://CRAN.R-project.org/package=acled.api/)
<!-- badges: end -->
This small package provides functionality to access and manage the application programming interface (API) of the [Armed Conflict Location & Event Data Project (ACLED)](https://acleddata.com/), while requiring a minimal number of dependencies. The function `acled.api()` makes it easy to retrieve a user-defined sample (or all of the available data) of ACLED, enabling a seamless integration of regular data updates into the research work flow.
When using this package, you acknowledge that you have read ACLED's terms and conditions of use, and that you agree with their attribution requirements.
## Installation
You can install the latest release version of acled.api from [CRAN](https://CRAN.R-project.org/package=acled.api/) with:
``` r
install.packages("acled.api") # downloads and installs the package from CRAN
```
You can install the development version from [GitLab](https://gitlab.com/chris-dworschak/) with:
``` r
remotes::install_gitlab("chris-dworschak/acled.api") # downloads and installs the package from GitLab
```
## Example
Using `acled.api` is straight forward. To download data on, for example, all ACLED conflict events in Europe and Central America that happened between June 2019 and July 2020, you can supply:
```{r example}
library(acled.api) # loads the package
my.data.frame <- acled.api( # stores an ACLED sample in object my.data.frame
email.address = Sys.getenv("ACLED_EMAIL_ADDRESS"),
access.key = Sys.getenv("ACLED_ACCESS_KEY"),
region = c("South Asia", "Central America"),
start.date = "2019-09-01",
end.date = "2020-01-31")
my.data.frame[1:5,] # returns the first three observations of the ACLED sample
```
## A note on replicability
After the release of versions 1 through 8, ACLED changed their update system to allow for real-time amendments and post-release corrections, thereby forgoing traditional data versioning. This change requires researchers to take additional steps in order to ensure the replicability of their results when using ACLED data. Some tasks, like real-time forecasting models used by practitioners, may not require replicability of intermediate results. However, most research-related tasks assume the possibility of replication at a later stage. This is especially the case for results that are intended for publication, or for an ongoing data project where constant changes to the underlying sample are not desirable.
To this end, downloaded data intended for replicable use must be permanently stored by the analyst. Data downloaded through `acled.api()` are only stored temporarily in the working space, and may be lost after closing R. Therefore, if replicability is important to the analyst's task, a call through `acled.api()` should occur only once at the beginning of the data project, immediately followed by, e.g., `saveRDS(downloaded.data, file = "my_acled_data.rds")`. This locally stored data file can then be used again at a later point by calling `readRDS(file = "my_acled_data.rds")`, and ensures that the analysis sample stays constant over time.
ACLED provides a time stamp for each individual observation (column *timestamp*), enabling researchers to do "micro versioning" of data points if necessary, and to verify congruence across samples. Starting from version 1.0.9, the function `acled.api()` includes the *timestamp* variable in its default API call. More recently, ACLED also introduced a discussion of data versioning in its [API Guide](https://apidocs.acleddata.com/).