# Get Started

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.

The main objectives of this package are:

1. Facilitating access to ACLED data via ACLED’s API
2. Simplifying the manipulation of ACLED data

This package was designed with the following workflow in mind:

You can begin by installing and then loading the package:

    # Install acledR
    install.packages("acledR") # from CRAN

    devtools::install_github("ACLED/acledR") # or from github.

    # Load acledR
    library(acledR)

## Authenticating your credentials - `acled_access()`

ACLED API access requires an API key for authentication. To register for API access, please visit ACLED’s Access Portal here. You can also find a detailed guide on creating your account and obtaining your API key in ACLED’s Access Guide.

Once you are registered, we encourage authenticating your credentials using the `acled_access()` function. Using this function both ensures that your credentials are working as intended and saves them in your R environment, eliminating the need for repeated authentication with each API request.

    acled_access(email = "email@example.com", key = "your_key") #  This is an example, you will need to input your credentials.

If the authentication was successful, you will find a message in the console stating that your credentials were authorized.

## 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:

    argentinian_data <- acled_api(
      # 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,
      # Turn off acled_api() interactive prompt
      prompt = FALSE
      )

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")`. If you do not use the `acled_access` function to store your credentials, you will also need to specify your email and API key in each request.

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:

    new_data <- acled_update(acledR::acled_old_deletion_dummy,
                             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.

    long_data <- acled_transform_longer(acledR::acled_old_dummy, type = "full_actors")

    head(long_data)
    #> # A tibble: 6 × 29
    #>   event_id_cnty event_date  year time_precision disorder_type event_type
    #>   <chr>         <date>     <dbl>          <dbl> <chr>         <chr>
    #> 1 ARG10607      2022-06-30  2022              1 Demostrations Protests
    #> 2 ARG10607      2022-06-30  2022              1 Demostrations Protests
    #> 3 ARG10607      2022-06-30  2022              1 Demostrations Protests
    #> 4 ARG10607      2022-06-30  2022              1 Demostrations Protests
    #> 5 ARG10607      2022-06-30  2022              1 Demostrations Protests
    #> 6 ARG10607      2022-06-30  2022              1 Demostrations Protests
    #> # ℹ 23 more variables: sub_event_type <chr>, type_of_actor <chr>, actor <chr>,
    #> #   inter_type <chr>, inter <dbl>, interaction <dbl>, civilian_targeting <chr>,
    #> #   iso <dbl>, region <chr>, country <chr>, admin1 <chr>, admin2 <chr>,
    #> #   admin3 <lgl>, location <chr>, latitude <dbl>, longitude <dbl>,
    #> #   geo_precision <dbl>, source <chr>, source_scale <chr>, notes <chr>,
    #> #   fatalities <dbl>, tags <chr>, timestamp <dbl>

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.

    wide_data <- acled_transform_wider(long_data, type = "full_actors")

    head(wide_data)
    #> # A tibble: 6 × 31
    #>   event_id_cnty event_date  year time_precision disorder_type event_type
    #>   <chr>         <date>     <dbl>          <dbl> <chr>         <chr>
    #> 1 ARG10295      2022-06-01  2022              1 Demostrations Protests
    #> 2 ARG10296      2022-06-01  2022              1 Demostrations Protests
    #> 3 ARG10297      2022-06-01  2022              1 Demostrations Protests
    #> 4 ARG10298      2022-06-01  2022              1 Demostrations Protests
    #> 5 ARG10299      2022-06-01  2022              1 Demostrations Protests
    #> 6 ARG10300      2022-06-02  2022              1 Demostrations Protests
    #> # ℹ 25 more variables: sub_event_type <chr>, actor1 <chr>, assoc_actor_1 <chr>,
    #> #   inter1 <dbl>, actor2 <chr>, assoc_actor_2 <chr>, inter2 <dbl>,
    #> #   interaction <dbl>, civilian_targeting <chr>, iso <dbl>, region <chr>,
    #> #   country <chr>, admin1 <chr>, admin2 <chr>, admin3 <lgl>, location <chr>,
    #> #   latitude <dbl>, longitude <dbl>, geo_precision <dbl>, source <chr>,
    #> #   source_scale <chr>, notes <chr>, fatalities <dbl>, tags <chr>,
    #> #   timestamp <dbl>

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.

    transformed_data <- acled_transform_interaction(acledR::acled_old_dummy)

    # Note the inter1 and inter2 columns
    head(transformed_data)
    #> # A tibble: 6 × 31
    #>   event_id_cnty event_date  year time_precision disorder_type event_type
    #>   <chr>         <date>     <dbl>          <dbl> <chr>         <chr>
    #> 1 ARG10607      2022-06-30  2022              1 Demostrations Protests
    #> 2 ARG10626      2022-06-30  2022              1 Demostrations Protests
    #> 3 ARG10618      2022-06-30  2022              1 Demostrations Protests
    #> 4 ARG10615      2022-06-30  2022              1 Demostrations Protests
    #> 5 ARG10627      2022-06-30  2022              1 Demostrations Protests
    #> 6 ARG10625      2022-06-30  2022              1 Demostrations Protests
    #> # ℹ 25 more variables: sub_event_type <chr>, actor1 <chr>, assoc_actor_1 <chr>,
    #> #   inter1 <chr>, actor2 <chr>, assoc_actor_2 <chr>, inter2 <chr>,
    #> #   interaction <chr>, civilian_targeting <chr>, iso <dbl>, region <chr>,
    #> #   country <chr>, admin1 <chr>, admin2 <chr>, admin3 <lgl>, location <chr>,
    #> #   latitude <dbl>, longitude <dbl>, geo_precision <dbl>, source <chr>,
    #> #   source_scale <chr>, notes <chr>, fatalities <dbl>, tags <chr>,
    #> #   timestamp <dbl>