---
title: "IBAMA"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{IBAMA}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
## Overview

The Brazilian Institute of Environment and Renewable Natural Resources (Instituto Brasileiro do Meio Ambiente e dos Recursos Naturais Renováveis - IBAMA) dataset documents environmental enforcement actions, including embargoes of productive assets and fines issued for environmental violations. This dataset provides individual-level records of environmental infractions from 2005 onwards, representing the enforcement activity of Brazil's primary federal environmental agency.

The data covers environmental violations across multiple sectors including deforestation, illegal mining, wildlife trafficking, illegal fishing, and other environmental crimes.

## Data Coverage

The IBAMA dataset includes:

- **Time Period**: Individual enforcement records from 2005 to present
- **Geographic Coverage**: All Brazilian states and the Legal Amazon region
- **Infraction Types**: Environmental violations across forestry, biodiversity, and natural resource management
- **Actions**: Embargoed areas, distributed fines, and collected fines
- **Individual-Level Detail**: Each record represents a specific infraction event

## Dataset Description

### Available Datasets

The function provides access to three distinct datasets tracking different stages of environmental enforcement:

1. **Embargoed Areas** (`"embargoed_areas"`)
   - Areas of land subject to federal environmental embargo
   - Productively assets frozen due to illegal activities (typically deforestation)
   - Includes area size, location, and embargo date
   - Useful for measuring enforcement scope and geographic patterns

2. **Distributed Fines** (`"distributed_fines"`)
   - Environmental fines issued by IBAMA for violations
   - Fines not yet paid by individuals or corporations
   - Include violation type, fine amount, and entity responsible
   - Track enforcement intensity and violation frequency

3. **Collected Fines** (`"collected_fines"`)
   - Environmental fines that have been paid
   - Represents actual revenue recovery from environmental violations
   - Subset of distributed fines with payment confirmation
   - Indicates compliance and enforcement effectiveness

### Key Variables

1. **Infraction Information**: Type of violation, legal basis, date of infraction
2. **Location**: State, municipality, coordinates (when available)
3. **Enforcement Action**: Type of action (embargo, fine), date of action
4. **Financial Data**: Fine amount, payment status, payment date
5. **Entity Information**: Individual or corporate identifier, sector
6. **Embargo Details**: Embargoed area size, land type, geographic descriptors

***

## Data Aggregation

The function returns either:
- **Raw Data**: Individual infraction records (original format)
- **Aggregated Data**: Summary statistics for each time-location period, including:
  - Total number of infractions
  - Infractions sent to prosecution
  - Infractions with ongoing legal proceedings
  - Embargoed area totals
  - Fine totals and collection rates

***

## Function Parameters

**Options:**

1. **dataset**: Three possible choices
   - `"embargoed_areas"`: Embargoed productive areas
   - `"distributed_fines"`: Issued fines (paid or unpaid)
   - `"collected_fines"`: Fines that have been paid

2. **raw_data**: 
   - `TRUE`: Individual-level records as originally recorded
   - `FALSE`: Treated/aggregated version of the data

3. **states**: 
   - Specifies which states to download (default: `"all"`)
   - Single state example: `"AC"` (Acre)
   - Multiple states example: `c("AC", "AM", "AP")` (Acre, Amazonas, Amapá)
   - Does not apply to embargoed_areas dataset

4. **language**: 
   - `"pt"`: Portuguese language labels and names
   - `"eng"`: English language

***

***

## Examples

```{r eval=FALSE}
# download treated embargoed areas data in english
data <- load_ibama(
  dataset = "embargoed_areas",
  raw_data = FALSE,
  language = "eng"
)

# download treated collected fines data from Bahia
data <- load_ibama(
  dataset = "collected_fines",
  raw_data = FALSE,
  states = "BA",
  language = "pt"
)
```

