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

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

[Municipal Agricultural Production](https://www.ibge.gov.br/en/statistics/economic/agriculture-forestry-and-fishing/16773-municipal-agricultural-production-temporary-and-permanent-crops.html?=&t=o-que-e) (PAM, in Portuguese) is a nationwide annual survey conducted by IBGE (Brazilian Institute of Geography and Statistics) which provides information on agricultural products, such as quantity produced, area planted and harvested, average quantity of output and monetary value of such output. The products are divided in permanent and temporary farmed land, as well as dedicated surveys to the four products that yield multiple harvests a year (beans, potato, peanut and corn), which all sum to a total survey of 64 agricultural products (31 of temporary tillage and 33 of permanent tillage). Output, however, is only included in the dataset if the planted area occupies over 1 acre or if output exceeds one tonne. 

Permanent farming is characterized by a cycle of long duration, whose harvests may be done multiple times across the years without the need of planting seeds again. Temporary farming, on the other hand, consists of cycles of short and medium duration, which after harvesting require planting seeds again.

The data also has multiple aggregation levels, such as nationwide, by region, mesoregion and microregion, as well as state and municipality. 

The data available has a yearly frequency and is available from 1974 to the present, with the exception of the four multiple-harvest products, which are only available from 2003. More information can be found on [this link](https://www.ibge.gov.br/estatisticas/economicas/agricultura-e-pecuaria/9117-producao-agricola-municipal-culturas-temporarias-e-permanentes.html#:~:text=A%20pesquisa%20Produ%C3%A7%C3%A3o%20Agr%C3%ADcola%20Municipal,s%C3%A3o%20da%20cesta%20b%C3%A1sica%20do ) (only in Portuguese).

***
**Options:**

  1. **dataset**: See tables below

  2. **raw_data**: there are two options:
      * `TRUE`: if you want the data as it is originally.
      * `FALSE`: if you want the treated version of the data. 
      
  3. **geo_level**: `"country"`, `"region"`, `"state"`, or `"municipality"`    
  
  4. **time_period**: picks the years for which the data will be downloaded

  5. **language**: you can choose between Portuguese `("pt")` and English `("eng")`
  
***

The datasets supported are shown in the tables below, made up of both the original databases and their narrower subsets. Note that downloading only specific crops is considerably faster.

<details>
<summary> Full datasets provided by IBGE: </summary>
| dataset |
|:--------|
|all_crops|
|temporary_crops|
|permanent_crops|
|corn|
|potato|
|peanut|
|beans|
</details>

<details>
<summary> Datasets generated from Temporary Crops: </summary>

| dataset | Name (pt) | Name (eng) |
|:--------|:---------:|:----------:|
| pineapple | Abacaxi |  Pineapple |
| alfafa | Alfafa Fenada | Alfafa Fenada |
| cotton_herbaceous |Algodao Herbaceo (em Caroco)| Herbaceous Cotton (in Caroco)|
| garlic |Alho| Garlic|
| peanut_temporary |Amendoim (em Casca)| Peanuts (in Shell)|
| rice |Arroz (em Casca)| Rice (in husk)|
| oats |Aveia (em Grao)| Oats (in grain)|
| sweet_potato |Batata Doce| Sweet potato|
| potato_temporary |Batata Inglesa| English potato|
| sugar_cane |Cana de Acucar| Sugar cane|
| forage_cane |Cana para Forragem| Forage cane|
| onion |Cebola| Onion|
| rye |Centeio (em Grao)| Rye (in grain)|
| barley |Cevada (em Grao)| Barley (in Grain)|
| pea |Ervilha (em Grao)| Pea (in Grain)|
| broad_bean |Fava (em Grao)| Broad Bean (in Grain)|
| beans_temporary |Feijao (em Grao)| Beans (in Grain)|
| tobacco |Fumo (em Folha)| Smoke (in Sheet)|
| sunflower_seeds |Girassol (em Grao)| Sunflower (in Grain)|
| jute_fiber |Juta (Fibra)| Jute (Fiber)|
| linen_seeds |Linho (Semente)| Linen (Seed)|
| malva_fiber |Malva (Fibra)| Malva (Fiber)|
| castor_bean |Mamona (Baga)| Castor bean (Berry)|
| cassava |Mandioca| Cassava|
| watermelon |Melancia| watermelon|
| melon |Melao| Melon|
| corn_temporary |Milho (em Grao)| corn (in grain)|
| ramie_fiber |Rami (Fibra)| Ramie (Fiber)|
| soybean |Soja (em Grao)| Soybean (in grain)|
| sorghum |Sorgo (em Grao)| Sorghum (in Grain)|
| tomato |Tomate| Tomato|
| wheat |Trigo (em Grao)| Wheat in grain)|
| triticale |Triticale (em Grao)| Triticale (in grain)|
| temporary_total |Total| Total|
</details>

<details>
<summary> Datasets generated from Permanent Crops: </summary>

| dataset | Name (pt) | Name (eng) |
|:--------|:---------:|:----------:|
| avocado |Abacate|Avocado| 
| cotton_arboreo |Algodao Arboreo (em Caroco)| Arboreo cotton (in Caroco)| 
| acai |Acai|Acai| 
| olive |Azeitona|Olive| 
| banana |Banana (Cacho)|Banana (Bunch)| 
| rubber_coagulated_latex |Borracha (Latex Coagulado)|Rubber (Coagulated Latex)| 
| rubber_liquid_latex |Borracha (Latex Liquido)|Rubber (Liquid Latex)| 
| cocoa_beans |Cacau (em Amendoa)|Cocoa (in Almonds)| 
| coffee_total |Cafe (em Grao) Total|Coffee (in Grain) Total| 
| coffee_arabica |Cafe (em Grao) Arabica|Cafe (in Grao) Arabica| 
| coffee_canephora |Cafe (em Grao) Canephora|Cafe (in Grain) Canephora| 
| cashew |Caju|Cashew| 
| khaki |Caqui|Khaki| 
| cashew_nut |Castanha de Caju|Cashew Nuts| 
| india_tea |Cha da India (Folha Verde)|India Tea (Leaf)| 
| coconut |Coco da Baia|Coconut| 
| coconut_bunch |Dende (Cacho de Coco)|Coconut Bunch| 
| yerba_mate |Erva Mate (Folha Verde)|Mate Herb (Leaf)| 
| fig |Figo|Fig| 
| guava |Goiaba|Guava| 
| guarana_seeds |Guarana (Semente)|Guarana (Seed)| 
| orange |Laranja|Orange| 
| lemon |Limao|Lemon| 
| apple |Maca|Apple| 
| papaya |Mamao|Papaya| 
| mango |Manga|Mango| 
| passion_fruit |Maracuja|Passion fruit| 
| quince |Marmelo|Quince| 
| walnut |Noz (Fruto Seco)|Walnut (Dry Fruit)| 
| heart_of_palm |Palmito|Palm heart| 
| pear |Pera|Pear| 
| peach |Pessego|Peach| 
| black_pepper |Pimenta do Reino|Black pepper| 
| sisal_or_agave |Sisal ou Agave (Fibra)|Sisal or Agave (Fiber)| 
| tangerine |Tangerina|Tangerine| 
| tung |Tungue (Fruto Seco)|Tung (Dry Fruit)| 
| annatto_seeds |Urucum (Semente)|Annatto (Seed)| 
| grape |Uva|Grape| 
| permanent_total |Total|Total|
</details>

**Examples:**

```{r eval=FALSE}
# download treated data at the state level from 2010 to 2011 for all crops
data <- load_pam(
  dataset = "all_crops",
  raw_data = FALSE,
  geo_level = "state",
  time_period = 2010:2011,
  language = "eng"
)
```
