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

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

## Overview

PPM (Pesquisa da Pecuária Municipal - Municipal Livestock Survey) is Brazil's comprehensive annual survey of livestock activities conducted by [IBGE](https://www.ibge.gov.br/). This dataset provides:

- **Livestock inventories**: Number of animals by species (cattle, pigs, poultry, sheep, horses, etc.)
- **Animal products**: Production volumes and values of milk, eggs, honey, wool, and other animal-origin products
- **Dairy farming**: Specialized data on milked cows, geographic distribution, productivity
- **Aquaculture**: Fish farming, shrimp farming, and mollusk farming activities
- **Sheep specialization**: Detailed shearing and wool production data
- **Multi-level geographic detail**: Country, region, state, and municipality levels
- **Long historical series**: Available from 1974 onwards
- **Economic value**: Both production quantities and market values

PPM is the primary data source for understanding Brazil's livestock sector, which is economically significant and globally important for beef, poultry, and dairy exports.

### Data Source and Methodology

PPM data is compiled from:
- Direct surveys of livestock producers
- Agricultural censuses and administrative records
- Municipal agriculture secretariats
- Processed and validated by IBGE
- Annual release with data for reference year

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

***

## Available Datasets

### **1. ppm_livestock_inventory**

Total livestock herds disaggregated by animal species.

- **Coverage**: All livestock species across all Brazilian municipalities
- **Time period**: 1974 onwards
- **Geographic levels**: Country, Region, State, Municipality
- **Animal species**: Cattle, pigs, chickens, sheep, horses, goats, buffalo, others
- **Variables**: Number of animals by species, number of establishments
- **Use cases**:
  - Identify regional livestock specialization
  - Track herd size trends
  - Analyze geographic concentration of livestock
  - Understand animal agriculture structure

### **2. ppm_sheep_farming**

Specialized data on sheep production and wool/fleece harvest.

- **Coverage**: Sheep farming across Brazil
- **Time period**: 1974 onwards
- **Geographic levels**: Country, Region, State, Municipality
- **Variables**: Total sheep, sheared sheep, fleece weight, wool production
- **Use cases**:
  - Analyze wool production and sheep farming specialization
  - Track shearing practices and yields
  - Regional wool industry assessment

### **3. ppm_animal_origin_production**

Production of animal-based products (milk, eggs, honey, wool, etc.).

- **Coverage**: All animal product production activities
- **Time period**: 1974 onwards
- **Geographic levels**: Country, Region, State, Municipality
- **Products included**: Cow milk, goat milk, chicken eggs, quail eggs, honey, wool, hides, wax
- **Variables**: Quantity produced and value of production
- **Use cases**:
  - Track dairy and egg production
  - Analyze honey and other bee products
  - Economic analysis of animal product sectors

### **4. ppm_cow_farming**

Detailed dairy cow farming data with milking and productivity metrics.

- **Coverage**: Dairy cow operations
- **Time period**: 1974 onwards
- **Geographic levels**: Country, Region, State, Municipality
- **Variables**: Milked cows, milk production volume, productivity (liters per cow)
- **Use cases**:
  - Dairy sector analysis
  - Productivity assessment
  - Geographic specialization in dairy
  - Production trend analysis

### **5. ppm_aquaculture**

Aquaculture activities including fish, shrimp, and mollusk farming.

- **Coverage**: All aquaculture operations
- **Time period**: 1974 onwards (though aquaculture data more recent)
- **Geographic levels**: Country, Region, State, Municipality
- **Activities**: Fish farming, shrimp farming, mollusk/oyster farming, other aquaculture
- **Variables**: Quantity and value of aquaculture production by type
- **Use cases**:
  - Aquaculture sector analysis
  - Regional aquaculture potential
  - Fish and seafood production trends
  - Emerging aquaculture development

***

## Function Parameters

### 1. **dataset**

Selects which livestock/animal production dataset to download.

```r
dataset = "ppm_livestock_inventory"     # Animal populations by species
dataset = "ppm_sheep_farming"           # Sheep and wool production
dataset = "ppm_animal_origin_production"  # Milk, eggs, honey, wool
dataset = "ppm_cow_farming"             # Dairy cow productivity
dataset = "ppm_aquaculture"             # Fish and aquaculture production
```

### 2. **raw_data**

Controls whether to download original or processed data.

- `TRUE`: Returns raw IBGE format
- `FALSE`: Returns treated data with English variable names and standardized units

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

### 3. **geo_level**

Specifies geographic aggregation level.

- `"country"`: National aggregate
- `"region"`: Brazilian geographic regions (5 regions)
- `"state"`: State-level data (27 units)
- `"municipality"`: All 5,570+ municipalities

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

### 4. **time_period**

Specifies which year(s) to download.

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

**Note**: All datasets available from 1974 onwards, though aquaculture more complete from 2000s.

### 5. **language**

Output language for variable names.

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

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

***

## Examples

### Example 1: Livestock inventory by state

```{r eval=FALSE}
# download treated livestock inventory data at the state level for 2020
livestock <- load_ppm(
  dataset = "ppm_livestock_inventory",
  raw_data = FALSE,
  geo_level = "state",
  time_period = 2020,
  language = "eng"
)
```

### Example 2: Dairy cow farming by state

```{r eval=FALSE}
# download treated dairy cow data at the state level for 2020
dairy <- load_ppm(
  dataset = "ppm_cow_farming",
  raw_data = FALSE,
  geo_level = "state",
  time_period = 2020,
  language = "eng"
)
```

### Example 3: Animal origin production at the country level

```{r eval=FALSE}
# download treated animal origin production data at the country level for 2020
animal_products <- load_ppm(
  dataset = "ppm_animal_origin_production",
  raw_data = FALSE,
  geo_level = "country",
  time_period = 2020,
  language = "eng"
)
```

### Example 4: Sheep farming by state

```{r eval=FALSE}
# download treated sheep farming data at the state level for 2020
sheep <- load_ppm(
  dataset = "ppm_sheep_farming",
  raw_data = FALSE,
  geo_level = "state",
  time_period = 2020,
  language = "eng"
)
```

### Example 5: Aquaculture by state over time

```{r eval=FALSE}
# download treated aquaculture data at the state level for 2015 to 2020
aquaculture <- load_ppm(
  dataset = "ppm_aquaculture",
  raw_data = FALSE,
  geo_level = "state",
  time_period = 2015:2020,
  language = "eng"
)
```

## Data Notes

### Data Structure

Each record typically contains:
- Geographic identifier (state or municipality)
- Year
- Animal species or product type
- Quantity (number of animals or production volume)
- Value (if applicable)
- Number of establishments

### Units of Measurement

- **Livestock counts**: Number of animals
- **Milk**: Liters
- **Eggs**: Dozens or units (verify in data)
- **Honey**: Kilograms
- **Wool**: Kilograms
- **Aquaculture**: Kilograms or tons

### Raw vs. Treated Data

- **Raw data**: IBGE original format, Portuguese names
- **Treated data**: English variable names, standardized units

### Important Limitations

1. **Survey-based data**: Subject to sampling and reporting error
2. **Informal operations**: May undercount small or informal livestock operations
3. **Data lag**: Published with delay; recent years may not be available
4. **Aquaculture newer**: Aquaculture data less complete for very early years
5. **Methodology changes**: Survey methods may evolve; can affect comparability

***
