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

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

PEVS (Produção da Silvicultura e da Extração Vegetal - Silviculture and Forestry Extraction Production) is a comprehensive annual survey conducted by [IBGE](https://www.ibge.gov.br/) that collects data on forestry and related activities in Brazil.

This dataset provides:

- **Native forest extraction**: Data on harvesting of native plant resources from natural forests
- **Planted forest production**: Information on timber and other products from managed forest plantations
- **Silviculture activities**: Forest management, afforestation, and reforestation data
- **Production volumes and values**: Both physical quantities and economic values
- **Harvested areas**: Land area from which extraction or harvest occurred
- **Forest crop areas**: Total existing areas of forest crops (silviculture)
- **Multi-level geographic data**: Available at country, regional, state, and municipality levels
- **Long historical coverage**: Annual data from 1986 onwards

PEVS is Brazil's primary source for forestry production statistics, important for understanding the timber industry, forest management practices, and sustainable use of forest resources.

### Data Source and Coverage

PEVS data comes from:
- Direct surveys of forestry companies and producers
- Administrative records from forestry operations
- Compiled and validated by IBGE's agriculture statistics division
- Annual release with data for previous year
- Covers both industrial and subsistence-level forestry activities

For more information, visit [IBGE Agriculture Statistics](https://www.ibge.gov.br/en/statistics/economic/agriculture-forestry/).

***

## Available Datasets

### **1. pevs_forest_crops**

Production data from forest crop plantations (timber and non-timber products).

- **Coverage**: All Brazilian forest crops and related products
- **Time period**: 1986 to 2019
- **Geographic levels**: Country, Region, State, Municipality
- **Key variables**: Quantity produced, value of production, by product type
- **Products included**: Eucalyptus, pine, other timber species, charcoal, resins, turpentine, cork
- **Use cases**:
  - Analyze timber production by region and species
  - Track forest product market values
  - Identify regional forestry specialization
  - Assess economic contribution of forest crops
  - Monitor charcoal and other non-timber forest products

### **2. pevs_silviculture**

Data on silviculture activities including afforestation, reforestation, and forest management.

- **Coverage**: All silviculture operations across Brazil
- **Time period**: 1986 to 2019
- **Geographic levels**: Country, Region, State, Municipality
- **Key variables**: Quantity and value of silviculture products, area under management
- **Activities tracked**: Timber production, forest management, conservation activities
- **Use cases**:
  - Track silviculture expansion and development
  - Analyze productivity of managed forests
  - Regional specialization in forest management
  - Economic analysis of forest-based industries
  - Environmental and conservation-oriented forestry

### **3. pevs_silviculture_area**

Total existing area used for silviculture operations, disaggregated by forest species.

- **Coverage**: All silviculture land areas in Brazil
- **Time period**: 2013 to 2019 (limited historical coverage)
- **Geographic levels**: Country, Region, State, Municipality
- **Key variables**: Total area by species (hectares), area by type of forest operation
- **Species tracked**: Eucalyptus, pine, acacia, other species
- **Measurement**: Area as of December 31st of each year
- **Use cases**:
  - Monitor forest plantation expansion
  - Track species-specific area trends
  - Land use change analysis
  - Assessment of silviculture infrastructure
  - Regional forest resource assessment
  - Support for long-term forest management planning

***

## Function Parameters

### 1. **dataset**

Selects which forestry dataset to download.

```r
dataset = "pevs_forest_crops"       # Forest crop production (1986-2019)
dataset = "pevs_silviculture"       # Silviculture production (1986-2019)
dataset = "pevs_silviculture_area"  # Silviculture land area (2013-2019)
```

### 2. **raw_data**

Controls whether to download original or processed data.

- `TRUE`: Returns raw IBGE data with original Portuguese variable names
- `FALSE`: Returns treated data with English variable names, standardized units, and cleaned formatting

```r
raw_data = FALSE  # logical
```

### 3. **geo_level**

Specifies the geographic aggregation level.

- `"country"`: National aggregate
- `"region"`: Brazilian geographic regions (North, Northeast, Center-West, Southeast, South)
- `"state"`: State-level data (27 units)
- `"municipality"`: Most granular level with 5,570+ municipalities

```r
geo_level = "state"  # character string
```

### 4. **time_period**

Defines which year(s) to download.

**Important: Dataset-specific availability:**

| Dataset | Available Years |
|---------|-----------------|
| `pevs_forest_crops` | 1986-2019 |
| `pevs_silviculture` | 1986-2019 |
| `pevs_silviculture_area` | 2013-2019 |

```r
time_period = 2019              # single year
time_period = c(2010, 2015)     # specific years
time_period = 2010:2019         # range of years
```

### 5. **language**

Output language for variable names.

- `"pt"`: Portuguese
- `"eng"`: English

```r
language = "eng"  # character string
```

***

## Examples

### Example 1: Forest crop production by state

```{r eval=FALSE}
# download treated forest crops data at the state level for 2019
forest_crops <- load_pevs(
  dataset = "pevs_forest_crops",
  raw_data = FALSE,
  geo_level = "state",
  time_period = 2019,
  language = "eng"
)
```

### Example 2: Silviculture area by state over time

```{r eval=FALSE}
# download treated silviculture area data at the state level for 2013 to 2019
silvi_area <- load_pevs(
  dataset = "pevs_silviculture_area",
  raw_data = FALSE,
  geo_level = "state",
  time_period = 2013:2019,
  language = "eng"
)
```

### Example 3: Silviculture production by region

```{r eval=FALSE}
# download treated silviculture production data at the region level for 2019
silvi_prod <- load_pevs(
  dataset = "pevs_silviculture",
  raw_data = FALSE,
  geo_level = "region",
  time_period = 2019,
  language = "eng"
)
```

## Data Notes

### Data Structure

Each row typically represents:
- A geographic unit (country, region, state, or municipality)
- A specific year
- A product type or forest species
- Quantity produced (in appropriate units: cubic meters, tons, etc.)
- Value of production (in currency units)

### Product Categories

Forest crops include:
- **Timber species**: Eucalyptus, pine, other timber
- **Non-timber products**: Charcoal, resins, turpentine, cork, bark
- **Other forest products**: Tannin, rosin, pulpwood

Exact categories vary by dataset and year.

### Raw vs. Treated Data

- **Raw data** (`raw_data = TRUE`): IBGE original format, Portuguese variable names
- **Treated data** (`raw_data = FALSE`): English names, standardized units, cleaned formatting

### Important Limitations

1. **Data collection changes**: Survey methodology may evolve over time
2. **Area vs. production**: Area data only available from 2013; earlier years have production data only
3. **Municipality data sparse**: Many small municipalities may have zero or no reported data
4. **Seasonal nature**: Some products are seasonal; annual aggregates smooth out variation
5. **Informal forestry**: May undercount small-scale or informal forestry operations

### Units of Measurement

- **Area**: Hectares (ha)
- **Quantity**: Varies by product (cubic meters for timber, tons for charcoal, etc.)
- **Value**: Brazilian Real (R$) at current prices

***