README.Rmd

---
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%"
)
```

# acledr

<!-- badges: start -->
[![Travis build status](https://travis-ci.com/andybega/acledr.svg?branch=master)](https://travis-ci.com/andybega/acledr)
[![Codecov test coverage](https://codecov.io/gh/andybega/acledr/branch/master/graph/badge.svg)](https://codecov.io/gh/andybega/acledr?branch=master)
<!-- badges: end -->

The goal of acledr is to download and read ACLED event data with R. 

ACLED provides two options for programmatic access: a API that allows specific event queries, and several Excel data dump files for each of region datasets, e.g. Africa. This package solely uses the data dump files. Thus downloading the data means the entire dump files will be downloaded. This might not be the most efficient method if you only need data for a single country. In that case it's maybe easier to point and click the web API. 

## Installation

Install from GitHub with:

```r
library(remotes)
install_github("andybega/acledr")
```

<!--
You can install the released version of acledr from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("acledr")
```
-->

## Example

**acledr** downloads the ACLED continent data dump files to a local directory. The download and read functions are setup by default to consult the `acledr.data_dir` option for the location of that directory. To make life easier, set that option in your `.Rprofile` file:

```{r, eval=FALSE}
library("usethis")
usethis::edit_r_profile()
# add:
#
# # acledr data directory
# options(acledr.data_dir = "path/to/acled/data")
```

Then, to download and read all ACLED events into memory:

```{r example, eval=FALSE}
library("acledr")

download_acled()

events <- read_acled()
```

A sample of the event data is included in the package. 

```{r}
data("acled_sample")
str(acled_sample)
```

### Country coverage start

An additional salient piece of information when trying to turn the raw event data into time series or panel data for countries over time is the country-specific coverage time range. E.g. there are not many ACLED events for Romania, but nomially the coverage starts on 2018-01-01, and thus if we want to turn a sparse set of events in Romania into a time series, we should use 0 values back to 2018-01-01. 

ACLED lists the country coverages in a [PDF document on their website](https://www.acleddata.com/wp-content/uploads/dlm_uploads/2018/02/Country-and-Time-Period-coverage_updatedJune2019-1.pdf). This is included in the package:

```{r}
data("acled_coverage")
str(acled_coverage)
```