---
title: "climateBR: An R package to download meteorological data from Brazil"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{climateBR: An R package to download meteorological data from Brazil}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

**climateBR** supports research on climate shocks by providing functions for each stage of working with climate data:

-   `download_inmet()` downloads the ZIP files with INMET weather station data from the Brazilian government's website.
-   `build_inmet_dataset()` converts the raw files into a partitioned dataset.
-   `read_inmet()` reads and filters that dataset.
-   `nearest_stations()` and `kriging_inmet()` link municipalities to INMET stations, so climate data can be merged with other sources, such as IBGE or TSE, for statistical analysis.

This vignette demonstrates the core workflow of **climateBR**.

## Installation

### Stable version (CRAN)

``` r
install.packages("climateBR")
```

### Development version

``` r
# install.packages("remotes")

remotes::install_github("kaiorb52/climateBR")
```

## Download data

First, download the original files published by INMET.

```{r eval=FALSE}

raw_dir <- file.path(tempdir(), "inmet_raw")
dataset_dir <- file.path(tempdir(), "inmet_arrow")

download_inmet(
  years = 2000:2005,
  unzip_to = raw_dir
)
```

## Build the dataset

Next, convert the downloaded files into a partitioned Arrow dataset. This only needs to be done once and makes later analyses much faster.

```{r eval=FALSE}
build_inmet_dataset(
  input = raw_dir,
  output = dataset_dir
)
```

## Read the dataset

The `read_inmet()` function reads the partitioned dataset and can return either an Arrow Dataset (`collect = FALSE`) or an in-memory data frame (`collect = TRUE`).

Keep `collect = FALSE` when working with long time spans: the full INMET dataset contains millions of observations, and loading all of them into memory with `collect = TRUE` may exceed the available RAM and crash R.

```{r eval=FALSE}
rainfall <- read_inmet(
  path = dataset_dir,
  years = 2000,
  collect = FALSE
)
```

Inspect and clean the observations before analysis. In some historical INMET files, missing values are coded as `-9999` instead of `NA`; convert them to `NA` before computing summaries or fitting models.

## How to Cite

When using `climateBR` in academic publications, please cite the package as follows:

```{r}
citation("climateBR")
```