README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# gridbr: easy access to the Brazilian statistical grid with R <a href='https://lucunha.com/gridbr'><img src='man/figures/gridbr.png' align="right" height="138.5" /></a>

<!-- badges: start -->
[![R-CMD-check](https://github.com/luisfelipebr/gridbr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/luisfelipebr/gridbr/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

**The goal of 'gridbr' is to provide easy access to the [Brazilian Statistical Grid](https://mapasinterativos.ibge.gov.br/grade/default.html)**, published by the Brazilian Institute of Geography and Statistics (IBGE). It builds upon the development made in the project [IBGE Statistical Grid in Compact Representation](https://github.com/osm-codes/BR_IBGE).

## Installation

You can install the development version of *gridbr* from this GitHub repository with `devtools`:

``` r
devtools::install_github("luisfelipebr/gridbr")
```

## Usage

### Setup

```{r message=FALSE}
library(gridbr)
library(sf)
```

In the following examples, the Brazilian archipelago [Fernando de Noronha](https://en.wikipedia.org/wiki/Fernando_de_Noronha) is used as aoi. It can be download with the package [geobr](https://ipeagit.github.io/geobr/) by using its municipality code.

```{r message=FALSE}
library(geobr)
```

```{r message=FALSE}
aoi <- read_municipality(2605459, showProgress = FALSE)
```

```{r figure1}
plot(st_geometry(aoi))
```

### gridbr_download(input, cellsize)

**`gridbr_download()`** is the main function available in the package. It builds the original statistical grid published by IBGE and merge it with downloaded 2010 population census data. The user must provide the area of interest (aoi) as a geospatial [sf](https://r-spatial.github.io/sf/index.html) object.

Two arguments are mandatory: `input` and `cellsize`.

```{r}
aoi_grid <- gridbr_download(input = aoi, 
                            cellsize = "1KM")
```

```{r}
head(aoi_grid)
```

```{r figure2}
plot(st_geometry(aoi))
plot(st_geometry(aoi_grid), add = TRUE, border = "red")
```

The original Brazilian statistical grid was made available at the following cell sizes: '500KM', '100KM', '50KM', '10KM', '5KM', '1KM' and '200M'. Using a different cell size value will result in an error. The '200M' cell size grid covers only urban areas and is complemented by cells with '1KM' cell size. If you want to build a grid with '200M' cell size covering the entire area of interest (and without population census data), you can use the function `gridbr_make()`.

Retrieving population census data requires either an internet connection or the support package [gridbr.data](https://github.com/luisfelipebr/gridbr.data). If the user does not meet these requirements, the output will include only the cell's id and geometry, but not population census data. 

If the user meet the requirements to retrieve population census data but don't want to include it, they can specify it by setting the optional `census_data` parameter to FALSE.

```{r}
aoi_grid <- gridbr_download(input = aoi,
                            cellsize = "1KM",
                            census_data = FALSE)
```

```{r}
head(aoi_grid)
```

There is another optional parameter related to the projection: by default, the output will use the same CRS as the input. If you want to keep the original grid CRS, with an equal area projection, you must set the `equal_area` parameter to TRUE.

```{r}
aoi_grid <- gridbr_download(input = aoi,
                            cellsize = "1KM",
                            equal_area = TRUE)
```

```{r}
head(aoi_grid)
```

### gridbr_make(input, cellsize)

**`gridbr_make()`** allows the user to make a standardized statistical grid using any cell size (without population census data). An input geospatial sf object and the cell size (in meters) must be specified.

```{r}
aoi_grid <- gridbr_make(input = aoi,
                        cellsize = 100)
```

```{r}
head(aoi_grid)
```

```{r figure3}
plot(st_geometry(aoi))
plot(st_geometry(aoi_grid), add = TRUE, border = "red")
```

An alternative unique identifier **gid** and the cell's geometry are included in the output. If the cell size is contained in the original statistical grid pool (500000, 100000, 50000, 10000, 5000, 1000, 200), the original **id** is also included in the output.

There is an optional parameter related to the projection: by default, the output will use the same CRS as the input. If you want to keep the original grid CRS, with an equal area projection, you must set the `equal_area` parameter to TRUE.

```{r}
aoi_grid <- gridbr_make(input = aoi,
                        cellsize = 100,
                        equal_area = TRUE)
```

```{r}
head(aoi_grid)
```