v0.1.3

DESCRIPTION

@@ -1,19 +1,20 @@
-Package: gridbr
 Type: Package
-Title: IBGE statistical grid access with R
-Version: 0.1.2
+Package: gridbr
+Title: easy access to the Brazilian statistical grid with R
+Version: 0.1.3
 Author: Luis Cunha
 Maintainer: Luis Cunha <luisfelipebc@outlook.com>
-Description: Make IBGE statistical grid and retrieve population census data.
+Description: Make Brazilian statistical grid and access 2010 population
+    census data.
 License: CC0
-Encoding: UTF-8
-LazyData: true
-LazyDataCompression: xz
+URL: http://lucunha.com/gridbr/
 Depends: 
     R (>= 2.10)
 Imports: 
     sf
 Suggests: 
     gridbr.data
+Encoding: UTF-8
+LazyData: true
+LazyDataCompression: xz
 RoxygenNote: 7.2.1
-URL: http://lucunha.com/gridbr/

NEWS.md

@@ -1,5 +1,9 @@
 # gridbr 
 
+# gridbr v0.1.3 (2022-08-10)
+
+* Updated README and documentation
+
 # gridbr v0.1.2 (2022-07-25)
 
 * Fixed 'gridbr_make' function id

R/gridbr_crs.R

@@ -1,4 +1,7 @@
-#' IBGE statistical grid CRS (with equal area projection)
+#' Brazilian statistical grid original CRS (with equal area projection).
 #'
 #' @docType data
+#' @keywords datasets
+#' @name gridbr_crs
+#' @usage data(gridbr_crs)
 "gridbr_crs"

R/gridbr_download.R

@@ -1,11 +1,11 @@
-#' Download IBGE statistical grid with population census data.
+#' Download Brazilian statistical grid with population census data.
 #'
-#' Make IBGE statistical grid covering (\code{input}) and merge with population census data.
+#' Make Brazilian statistical grid covering (\code{input}) with 2010 population census data.
 #' @param input object of class sf, sfc or sfg.
-#' @param cellsize target cell size. Must be one of: "500KM", "100KM", "50KM", "10KM", "5KM", "1KM" and "200M".
-#' @param census_data logical. Set to FALSE if you don't want to include population census data.
+#' @param cellsize character. Target cell size. Must be one of: "500KM", "100KM", "50KM", "10KM", "5KM", "1KM" and "200M".
+#' @param census_data logical. Set to FALSE if you don't want to include 2010 population census data.
 #' @param equal_area logical. Set to TRUE if you want to use the original grid CRS, with an equal area projection.
-#' @return IBGE statistical grid
+#' @return Brazilian statistical grid
 #' @export
 
 gridbr_download <- function(input, cellsize, census_data = TRUE, equal_area = FALSE) {

R/gridbr_make.R

@@ -1,10 +1,10 @@
-#' Make standardized square grid.
+#' Make Brazilian statistical grid.
 #'
-#' Make standardized square grid covering (\code{input}).
+#' Make Brazilian statistical grid covering (\code{input}).
 #' @param input object of class sf, sfc or sfg.
-#' @param cellsize integer, in meters. Target cell size must be greater than 1.
+#' @param cellsize integer. Target cell size (in meters). Must be greater than 1.
 #' @param equal_area logical. Set to TRUE if you want to use the original grid CRS, with an equal area projection.
-#' @return standardized square grid
+#' @return Brazilian statistical grid
 #' @export
 
 gridbr_make <- function(input, cellsize, equal_area = FALSE) {

R/gridbr_urban.R

@@ -1,4 +1,4 @@
-#' A character vector with the id of IBGE statistical grid urban cells ("200M" cell size).
+#' A character vector with the id of Brazilian statistical grid urban cells ("200M" cell size).
 #'
 #' @docType data
 #' @keywords datasets

README.Rmd

@@ -13,13 +13,13 @@ knitr::opts_chunk$set(
 )
 ```
 
-# gridbr: IBGE statistical grid access with R
+# gridbr: easy access to the Brazilian statistical grid with R
 
 <!-- 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 [IBGE Statistical Grid](https://mapasinterativos.ibge.gov.br/grade/default.html)** (download available [here](https://geoftp.ibge.gov.br/recortes_para_fins_estatisticos/grade_estatistica/censo_2010/)). It builds upon the development made in the project [IBGE Statistical Grid in Compact Representation](https://github.com/osm-codes/BR_IBGE) (short paper available [here](http://mtc-m16c.sid.inpe.br/ibi/8JMKD3MGPDW34P/45U7J5H)).
+**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
 
@@ -29,30 +29,34 @@ You can install the development version of *gridbr* from this GitHub repository
 devtools::install_github("luisfelipebr/gridbr")
 ```
 
-## Example
+## Usage
 
-```{r setup, message=FALSE}
+### Setup
+
+```{r}
 library(gridbr)
-library(sf)
 ```
 
-**gridbr_download** is the main function available in the package. It builds the geometry of IBGE statistical grid and merge it with 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.
-
-In the following example, the Brazilian archipelago [Fernando de Noronha](https://en.wikipedia.org/wiki/Fernando_de_Noronha) is used as aoi. It can be download in one line with the package [geobr](https://ipeagit.github.io/geobr/) just by using its IBGE municipality code.
+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}
+library(sf)
 library(geobr)
 ```
 
 ```{r message=FALSE}
 aoi <- read_municipality(2605459, showProgress = FALSE)
 ```
 
-```{r aoi}
+```{r}
 plot(st_geometry(aoi))
 ```
 
-After loading the aoi, you can use the function `gridbr_download` to download the grid. Two arguments are mandatory: `input` and `cellsize`.
+### 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, 
@@ -63,17 +67,19 @@ aoi_grid <- gridbr_download(input = aoi,
 head(aoi_grid)
 ```
 
-```{r grid}
-plot(st_geometry(aoi_grid))
-plot(st_geometry(aoi), add = TRUE, border = "red")
+```{r}
+plot(st_geometry(aoi))
+plot(st_geometry(aoi_grid), add = TRUE, border = "red")
 ```
 
-The IBGE statistical grid was made available in the following sizes: 500KM, 100KM, 50KM, 10KM, 5KM, 1KM and 200M. Using a different value will result in an error.
+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. 
 
-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 and still don't want to download the data, they can specify it by setting the `census_data` parameter to FALSE.
+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(aoi,
+aoi_grid <- gridbr_download(input = aoi,
                             cellsize = "1KM",
                             census_data = FALSE)
 ```
@@ -82,14 +88,46 @@ aoi_grid <- gridbr_download(aoi,
 head(aoi_grid)
 ```
 
-The other optional parameter is related to the projection: by default, the output will have 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.
+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(aoi,
+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}
+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)
+```