### Install acledR package

Source: https://github.com/dtacled/acledr/blob/master/README.md

Use these commands to install the package from CRAN or the development version from GitHub.

```r
# Install via cran
install.packages("acledR")

# Install development version from github
devtools::install_github("dtacled/acledR")
```

--------------------------------

### Add GNU GPL License Header to Source Files

Source: https://github.com/dtacled/acledr/blob/master/LICENSE.md

Attach this notice to the start of each source file to declare the program as free software and disclaim warranties.

```text
<one line to give the program's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
```

--------------------------------

### Request Data with acled_api

Source: https://context7.com/dtacled/acledr/llms.txt

Examples of using acled_api to fetch conflict data with various filters including country, region, event type, and population estimates.

```r
library(acledR)

# Basic request: Get all events in Argentina for a specific date range
argentina_data <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  country = "Argentina",
  start_date = "2022-01-01",
  end_date = "2022-12-31"
)

# Request data for multiple countries with numeric interaction codes
multi_country_data <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  country = c("Argentina", "Brazil", "Chile"),
  start_date = "2023-01-01",
  end_date = "2023-06-30",
  inter_numeric = TRUE
)

# Request data by region (e.g., Caribbean)
caribbean_data <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  regions = "Caribbean",
  start_date = "2022-01-01",
  end_date = "2022-01-31",
  monadic = TRUE  # Return monadic (actor-level) data
)

# Filter by specific event types
protests_riots <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  country = "Kenya",
  start_date = "2023-01-01",
  end_date = "2023-12-31",
  event_types = c("Protests", "Riots")
)

# Get events with population estimates
data_with_pop <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  country = "Nigeria",
  start_date = "2023-01-01",
  end_date = "2023-03-31",
  population = "best"  # Options: "none", "best", "full"
)

# Use timestamp to get events added/modified after a specific date
recent_updates <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  country = "Ukraine",
  start_date = "2023-01-01",
  end_date = "2023-12-31",
  timestamp = "2023-06-01"  # Only events added/modified after this date
)

# View the returned data
head(argentina_data)
# Returns tibble with columns: 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
```

--------------------------------

### Display License Notice in Interactive Terminal

Source: https://github.com/dtacled/acledr/blob/master/LICENSE.md

Include this short notice in the program's startup output when running in interactive mode.

```text
<program>  Copyright (C) <year>  <name of author>
    This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type 'show c' for details.
```

--------------------------------

### Full ACLED Data Workflow: Download, Transform, and Analyze

Source: https://context7.com/dtacled/acledr/llms.txt

This snippet demonstrates a complete workflow: downloading ACLED data with numeric interaction codes using `acled_api`, transforming it for readability with `acled_transform_interaction`, and then performing an analysis by actor type using `dplyr` for grouping and summarization.

```r
numeric_data <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  country = "Argentina",
  start_date = "2022-01-01",
  end_date = "2022-12-31",
  inter_numeric = TRUE
)

readable_data <- acled_transform_interaction(numeric_data)

# Analyze by actor type
library(dplyr)
actor_type_summary <- readable_data %>%
  group_by(inter1) %>%
  summarise(
    events = n(),
    fatalities = sum(fatalities, na.rm = TRUE)
  ) %>%
  arrange(desc(events))
```

--------------------------------

### Accessing ACLED Reference Datasets

Source: https://context7.com/dtacled/acledr/llms.txt

The `acledR` package includes several built-in reference datasets for filtering and analysis. These datasets provide information on countries, regions, event categories, interaction codes, and variable definitions.

```r
library(acledR)

# View available ACLED countries with regions and start years
head(acledR::acled_countries)
# Columns: country, region, start_year

# Filter countries by region
african_countries <- acledR::acled_countries %>%
  filter(region %in% c("Eastern Africa", "Western Africa", "Middle Africa"))

# View ACLED regions with codes
acledR::acled_regions
# Columns: region (numeric code), region_name, first_event_date

# View ACLED event types and sub-types
acledR::acled_event_categories
# Columns: event_type, sub_event_type, political_violence,
#          organized_political_violence, disorder, demonstrations

# Filter for political violence events
pv_events <- acledR::acled_event_categories %>%
  filter(political_violence == TRUE)

# View interaction code mappings
acledR::acled_interaction_codes
# Columns: Inter1/Inter2, Numeric Code
# Maps: 1=State Forces, 2=Rebel Groups, 3=Political Militias,
#       4=Identity Militias, 5=Rioters, 6=Protesters, 7=Civilians, 8=Others

# View ACLED codebook for variable definitions
acledR::acled_codebook
# Columns: Variable, Description, Values

# Sample datasets for testing and examples
head(acledR::acled_old_dummy)           # Sample dyadic ACLED data
head(acledR::acled_old_deletion_dummy)  # Sample data with deletion scenarios
```

--------------------------------

### Update Datasets with acled_update

Source: https://context7.com/dtacled/acledr/llms.txt

Automate the process of updating existing local datasets with new or modified events.

```r
library(acledR)

# Update an existing dataset with new and modified events
```

--------------------------------

### Consistent Rounding Function for ACLED Statistics

Source: https://context7.com/dtacled/acledr/llms.txt

The `acled_rounding` function provides consistent rounding behavior, always rounding values ending in 5 up, unlike R's default banker's rounding. It can round to whole numbers or specific decimal places and is useful for reporting ACLED statistics accurately.

```r
library(acledR)

# Basic rounding to whole numbers
acled_rounding(1.569)    # Returns 2
acled_rounding(104.530)  # Returns 105
acled_rounding(54.430)   # Returns 54
acled_rounding(205.499)  # Returns 205

# Round to specific decimal places
acled_rounding(1.569, digits = 1)   # Returns 1.6
acled_rounding(1.569, digits = 2)   # Returns 1.57

# Compare with base R rounding (banker's rounding)
round(2.5)          # Returns 2 (rounds to even)
acled_rounding(2.5) # Returns 3 (rounds up)

round(3.5)          # Returns 4 (rounds to even)
acled_rounding(3.5) # Returns 4 (rounds up)

# Use in data analysis
library(dplyr)
fatality_summary <- my_data %>%
  group_by(country) %>%
  summarise(
    avg_fatalities = acled_rounding(mean(fatalities, na.rm = TRUE), digits = 1),
    total_events = n()
  )
```

--------------------------------

### Convert ACLED Interaction Codes

Source: https://context7.com/dtacled/acledr/llms.txt

Transforms numeric interaction codes into human-readable string labels for actor types and their interactions. Use when data was retrieved with 'inter_numeric = TRUE'.

```r
library(acledR)

# Convert numeric interaction codes to descriptive strings
transformed <- acled_transform_interaction(
  df = acledR::acled_old_dummy,
  only_inters = FALSE  # Also transform the 'interaction' column
)

# View the transformed columns
head(transformed %>% select(actor1, inter1, actor2, inter2, interaction))
```

--------------------------------

### Request Deleted Event IDs with acled_deletions_api

Source: https://context7.com/dtacled/acledr/llms.txt

Retrieve deleted event IDs to maintain local dataset integrity, using either date strings or Unix timestamps.

```r
library(acledR)

# Get all events deleted since January 1, 2022
deleted_events <- acled_deletions_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  date_deleted = "2022-01-01"
)

# Using Unix timestamp instead of date string
deleted_events_unix <- acled_deletions_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  date_deleted = 1640995200  # Unix timestamp for 2022-01-01
)

# View deleted event IDs
head(deleted_events)
# Returns tibble with columns: event_id_cnty, deleted_timestamp

# Remove deleted events from your local dataset
my_dataset <- my_dataset %>%
  filter(!(event_id_cnty %in% deleted_events$event_id_cnty))
```

--------------------------------

### Transform ACLED Data: Wide to Long Format

Source: https://context7.com/dtacled/acledr/llms.txt

Converts ACLED data from dyadic (wide) to monadic (long) format, creating a row for each actor involved in an event. Useful for actor-based analyses.

```r
library(acledR)

# Transform all actor columns (actor1, actor2, assoc_actor_1, assoc_actor_2)
long_full <- acled_transform_longer(
  data = acledR::acled_old_dummy,
  type = "full_actors"
)
# Each event now has multiple rows, one for each actor involved
```

```r
# Transform only main actors (actor1 and actor2)
long_main <- acled_transform_longer(
  data = acledR::acled_old_dummy,
  type = "main_actors"
)
```

```r
# Transform only associated actors
long_assoc <- acled_transform_longer(
  data = acledR::acled_old_dummy,
  type = "assoc_actors"
)
```

```r
# Transform source column (separate multiple sources into rows)
long_source <- acled_transform_longer(
  data = acledR::acled_old_dummy,
  type = "source"
)
```

```r
# Example: Count events per actor
library(dplyr)
actor_counts <- long_full %>%
  filter(actor != "") %>%
  group_by(actor) %>%
  summarise(event_count = n()) %>%
  arrange(desc(event_count))

head(actor_counts)
```

--------------------------------

### Update ACLED Data

Source: https://context7.com/dtacled/acledr/llms.txt

Updates ACLED data using provided credentials and optional parameters like date ranges, countries, regions, or event types. Ensure 'inter_numeric' matches your existing data format.

```r
updated_data <- acled_update(
  df = acledR::acled_old_dummy,
  email = "youremail@mail.com",
  password = "yourpassword",
  inter_numeric = TRUE,  # Must match the format of your existing data
  deleted = TRUE  # Also remove deleted events (default)
)
```

```r
updated_expanded <- acled_update(
  df = acledR::acled_old_dummy,
  email = "youremail@mail.com",
  password = "yourpassword",
  additional_countries = c("Argentina", "Chile"),  # Add events from Chile
  inter_numeric = TRUE
)
```

```r
updated_custom <- acled_update(
  df = acledR::acled_old_dummy,
  email = "youremail@mail.com",
  password = "yourpassword",
  start_date = "2022-01-01",
  end_date = "2023-12-31",
  deleted = TRUE
)
```

```r
updated_regions <- acled_update(
  df = my_regional_data,
  email = "youremail@mail.com",
  password = "yourpassword",
  regions = c("South America", "Central America"),
  inter_numeric = FALSE
)
```

```r
updated_protests <- acled_update(
  df = my_protest_data,
  email = "youremail@mail.com",
  password = "yourpassword",
  event_types = c("Protests", "Riots"),
  deleted = FALSE  # Don't check for deletions
)
```

--------------------------------

### acled_api - Request Data from ACLED API

Source: https://context7.com/dtacled/acledr/llms.txt

The primary function for accessing ACLED data. It allows users to request conflict event data filtered by country, region, date range, event type, and other parameters.

```APIDOC
## GET acled_api

### Description
Requests conflict event data from the ACLED API based on specified filters.

### Parameters
#### Request Body
- **email** (string) - Required - User email for authentication
- **password** (string) - Required - User password for authentication
- **country** (string/vector) - Optional - Country or countries to filter by
- **regions** (string) - Optional - Region to filter by
- **start_date** (string) - Optional - Start date for the data range
- **end_date** (string) - Optional - End date for the data range
- **event_types** (vector) - Optional - Specific event types to include
- **inter_numeric** (boolean) - Optional - Whether to return numeric interaction codes
- **monadic** (boolean) - Optional - Whether to return monadic (actor-level) data
- **population** (string) - Optional - Population estimate level ('none', 'best', 'full')
- **timestamp** (string) - Optional - Filter for events added/modified after this date

### Response
#### Success Response (200)
- **data** (tibble) - Returns a tibble containing event details including event_id_cnty, event_date, actor information, location, and fatalities.
```

--------------------------------

### Transform ACLED Data: Long to Wide Format

Source: https://context7.com/dtacled/acledr/llms.txt

Reverses the wide-to-long transformation, converting monadic (long) data back to dyadic (wide) format. Also used to convert API monadic output to dyadic format.

```r
library(acledR)

# First create long format data
long_data <- acled_transform_longer(
  data = acledR::acled_old_dummy,
  type = "full_actors"
)

# Convert back to wide format
wide_data <- acled_transform_wider(
  data = long_data,
  type = "full_actors"
)
```

```r
# Convert main actors back to wide
long_main <- acled_transform_longer(acledR::acled_old_dummy, type = "main_actors")
wide_main <- acled_transform_wider(long_main, type = "main_actors")
```

```r
# Convert associated actors back to wide
long_assoc <- acled_transform_longer(acledR::acled_old_dummy, type = "assoc_actors")
wide_assoc <- acled_transform_wider(long_assoc, type = "assoc_actors")
```

```r
# Convert source back to wide
long_source <- acled_transform_longer(acledR::acled_old_dummy, type = "source")
wide_source <- acled_transform_wider(long_source, type = "source")
```

```r
# Convert API monadic output to dyadic format
monadic_api_data <- acled_api(
  email = "youremail@mail.com",
  password = "yourpassword",
  country = "Argentina",
  start_date = "2022-01-01",
  end_date = "2022-01-31",
  monadic = TRUE
)

dyadic_data <- acled_transform_wider(
  data = monadic_api_data,
  type = "api_monadic"
)
```

--------------------------------

### Transform Interaction Columns in ACLED Data

Source: https://context7.com/dtacled/acledr/llms.txt

Use `acled_transform_interaction` to selectively transform only interaction columns (inter1, inter2) while keeping the interaction codes as numeric. This is useful for specific analyses focusing on actor interactions.

```r
transformed_partial <- acled_transform_interaction(
  df = acledR::acled_old_dummy,
  only_inters = TRUE
)
```

--------------------------------

### acled_deletions_api - Request Deleted Event IDs

Source: https://context7.com/dtacled/acledr/llms.txt

Retrieves event IDs that have been deleted from ACLED's database since a specified date to maintain data integrity.

```APIDOC
## GET acled_deletions_api

### Description
Retrieves a list of event IDs that have been removed from the ACLED database.

### Parameters
#### Request Body
- **email** (string) - Required - User email for authentication
- **password** (string) - Required - User password for authentication
- **date_deleted** (string/numeric) - Required - Date or Unix timestamp to check for deletions since

### Response
#### Success Response (200)
- **data** (tibble) - Returns a tibble with columns: event_id_cnty, deleted_timestamp
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.