hsvab · hsvab · Oct 19, 2023 · Oct 20, 2023 · Oct 20, 2023
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,5 +1,5 @@
 Package: odbr
-Title: Download Data from Brazil's Origin Destination Surveys
+Title: Data from Brazil's Origin Destination Surveys
 Version: 0.1.0
 Authors@R: c(
     person("Haydee", "Svab", , "[email protected]", role = c("aut", "cre")),
@@ -9,24 +9,33 @@ Authors@R: c(
     person("Rafael H. M.", "Pereira", , "[email protected]", role = "aut",
            comment = c(ORCID = "0000-0003-2125-7465"))
   )
-Description: Download Data from Brazil's Origin Destination Surveys.
+Description: Provide helper functions to download Data from Brazil's Origin
+  Destination Surveys both the survey data and its maps, and also the surveys
+  data dictionaries that explains each variable. Initially only the non-harmonized
+  data will be available, but it is already planned to also have an "harmonized"
+  version of each survey contemplating a single standardized format for (almost)
+  all surveys.
+  The three main functions are:
+  - `read_dictionary`: Retrieve the data dictionary
+  - `read_od`: Retrieve the survey data
+  - `read_map`: Retrieve geolocalized survey data
 License: GPL (>=3)
-Depends: 
+Depends:
     R (>= 2.10)
-Imports: 
+Imports:
     data.table,
     fs,
     haven,
     piggyback,
     R.utils,
     sf,
     usethis
-Suggests: 
+Suggests:
     knitr,
     rmarkdown,
     spelling,
     testthat (>= 3.2.0)
-VignetteBuilder: 
+VignetteBuilder:
     knitr
 Config/testthat/edition: 3
 Encoding: UTF-8

diff --git a/R/read_dictionary.R b/R/read_dictionary.R
@@ -1,9 +1,11 @@
 #' Download data dictionary from OD surveys databases
 #'
 #' @description
-#' The "read_dictionary" function requires as parameter city, year and whether
-#' you want the harmonized database (over the years, for the same city) or not -
-#' the default is the raw base.
+#' `read_dictonary()` returns the data dictionary of a specific Origin
+#' Destination Survey, if available. This dictionary is intended to be used to
+#' understand the data downloaded using the `odbr::read_od` function. It will
+#' contain the list of variables and, for each variable, a simple description,
+#' the available categories and its class (factor, numeric, etc).
 #'
 #' @template city
 #' @template year

diff --git a/R/read_map.R b/R/read_map.R
@@ -1,10 +1,15 @@
 #' Download spatial data from OD Surveys databases
 #'
 #' @description
-#' The "read_map" function requires as parameter city, year, geometry (zones or
-#' municipalities) - the default is zone, and whether you want the harmonized
-#' database (variable names and reference/geodesic projection over the years,
-#' for the same city) or not - the default is the raw base.
+#' `read_map()` download the geo data for a specific Origin Destination survey
+#' and return it as an sf dataframe. It uses the cached data file if it was
+#' previously downloaded to avoid extra networking consumption. To understand
+#' the returned dataframe format, please reefer to the `read_dictionary()`
+#' function for the same survey cohort.
+#'
+#' You should also specify the geometry granularity you want, be it "municipal",
+#' "district" or "zone" level of details. Of course not all geometry
+#' granularities are available for all surveys.
 #'
 #' @template city
 #' @template year

diff --git a/R/read_od.R b/R/read_od.R
@@ -1,9 +1,11 @@
 #' Download microdata from OD Surveys databases
 #'
 #' @description
-#' The "read_od" function requires as parameter city, year and whether you want
-#' the harmonized database (over the years, for the same city) or not - the
-#' default is the raw base.
+#' `read_od()` download the data for a specific Origin Destination survey and
+#' return it as a dataframe. It uses the cached data file if it was previously
+#' downloaded to avoid extra networking consumption. To understand the returned
+#' dataframe format, please refeer to the `read_dictionary()` function for the
+#' same survey cohort.
 #'
 #' @template city
 #' @template year

diff --git a/README.Rmd b/README.Rmd
@@ -2,7 +2,7 @@
 output: github_document
 ---
 
-<!-- README.md is generated from README.Rmd. Please edit that file -->
+<!-- README.md is generated from README.Rmd. Please edit only the Rmd file -->
 
 ```{r, include = FALSE}
 knitr::opts_chunk$set(
@@ -16,28 +16,38 @@ knitr::opts_chunk$set(
 # odbr: Download Data from Brazil's Origin Destination Surveys <img align="right" src="man/figures/ODBRlogov4hexagonal.png" alt="logo" width="180">
 
 <!-- badges: start -->
+<!-- uncomment after the package is released at CRAN
+[![CRAN
+   status](https://www.r-pkg.org/badges/version/censobr)](https://CRAN.R-project.org/package=censobr)
+[![CRAN/METACRAN Total
+   downloads](http://cranlogs.r-pkg.org/badges/grand-total/censobr?color=blue)](https://CRAN.R-project.org/package=censobr) [![Codecov test
+-->
 [![Codecov test
 coverage](https://codecov.io/gh/hsvab/odbr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/hsvab/odbr?branch=main)
 [![R-CMD-check](https://github.com/hsvab/odbr/actions/workflows/R-CMD-check.yaml/badge.svg?branch=main)](https://github.com/hsvab/odbr/actions?query=branch%3Amain)
 [![Champions Program](https://raw.githubusercontent.com/ropensci-org/badges/main/svgs/champions-program.svg)](https://ropensci.org/champions/)
 
 <!-- badges: end -->
 
-**odbr** is an R package to download data from Brazil's Origin Destination Surveys. The package provides databases, maps, and data dictionaries in English, Portuguese, and Spanish. Furthermore, it is possible to download harmonized data across different cohorts for the same city.
+**odbr** is an R package to download data from Brazil's Origin Destination
+Surveys. The package provides databases, maps, and data dictionaries in English,
+Portuguese, and Spanish. Furthermore, it is possible to download harmonized data
+across different cohorts for the same city.
 
 
 ## Installation
 
-You can install the development version of odbr from
-[CRAN](https://CRAN.R-project.org/package=odbr) with:
+You can install the [odbr Package](https://CRAN.R-project.org/package=odbr)
+with:
 
 ``` r
 # install from CRAN
 install.packages("odbr")
 library(odbr)
 ```
 
-You can install the development version of odbr from [GitHub](https://github.com/) with:
+You can install the development version of odbr from
+[GitHub](https://github.com/hsvab/odbr) with:
 
 ``` r
 # or use the development version with latest features
@@ -48,28 +58,29 @@ library(odbr)
 
 ## Basic Usage
 
-The syntax of all `odbr` functions operate on the same logic so it becomes intuitive to download any data set using a single line of code. Like this:
+The syntax of all `odbr` functions operate on the same logic so it becomes
+intuitive to download any dataset using a single line of code. Like this:
 
 ```{r example}
-library(odbr)
-
 # Return data from OD Surveys database as data.frame
-df <- read_od(
+df <- odbr::read_od(
   city = "Sao Paulo",
   year = 2017,
   harmonize = FALSE
 )
 
-# Return zone data from OD Surveys database as sf object at a given city and year
-df <- read_map(
+# Return zone data from OD Surveys database as an sf object at a given city and
+# year
+df <- odbr::read_map(
   city = "Sao Paulo",
   year = 2017,
   harmonize = FALSE,
   geometry = "zone"
 )
 
-# Return data dictionary from OD Surveys, as data.frame, at a given city and year
-df <- read_dictionary(
+# Return data dictionary from OD Surveys, as an data.frame, at a given city and
+# year
+df <- odbr::read_dictionary(
   city = "Sao Paulo",
   year = 2017,
   harmonize = FALSE,
@@ -81,27 +92,27 @@ df <- read_dictionary(
 
 **The original geodetic reference system remained unchanged.**
 
-|City|Years available| Harmonized |Dictionary languages | Source|
-|-----|-----|-----|-----|-----|
-|São Paulo| 1977, 1987, 1997, 2007, 2017 | No | en, es, pt-br | [Metrô-SP](https://transparencia.metrosp.com.br/dataset/pesquisa-origem-e-destino)
-
+| City | Years available | Dictionary languages | Source |
+|-----|-----|-----|-----|
+| São Paulo | 1977, 1987, 1997, 2007, 2017 | en, es, pt-br | [Metrô-SP](https://transparencia.metrosp.com.br/dataset/pesquisa-origem-e-destino)
 
 
 ## Available harmonized datasets:
 
 **All harmonized datasets use geodetic reference system "SIRGAS2000", CRS(4674).**
 
-There is not harmonized data available yet.
-
+There is no harmonized data available yet.
 
 
 ## Contributing to odbr
-If you would like to contribute to **odbr**, you're welcome to open an issue to explain the proposed a contribution.
+If you would like to contribute to **odbr**, you're welcome to open an issue to
+explain the proposed a contribution.
 
 
 ## Credits
 
-Original databases and shapefiles are created by local official government institutions.
+Original databases and shapefiles are created by local official government
+institutions.
 
 The logo was designed by [Marcos Kyoto de Tani e Isoda](https://www.instagram.com/redes.urbanas/)
 
@@ -124,4 +135,7 @@ bibentry(
 
 ## Sponsors <a href="https://ropensci.org/"><img align="right" src="man/figures/ropenscilogo.png" alt="ropensci logo" width="150" /></a>
 
-The **odbr** package was initially sponsored by rOpenSci through its Champions Program (2022 edition) whose main goal is to provide support to R developers from around the world who identify themselves as members of groups that are systematically excluded from the open-source software community.
+The **odbr** package was initially sponsored by rOpenSci through its Champions
+Program (2022 edition) whose main goal is to provide support to R developers
+from around the world who identify themselves as members of groups that are
+systematically excluded from the open-source software community.
diff --git a/README.md b/README.md
@@ -102,10 +102,10 @@ Isoda](https://www.instagram.com/redes.urbanas/)
 
 If you want to cite this package, you can cite it as:
 
-- Svab, Haydee; Milz, Beatriz; Oliveira, Diego Rabatone; Pereira,
-  Rafael H. M. (2023) odbr: Download Data from Brazil’s Origin
-  Destination Surveys. R package version v0.1.0,
-  <https://CRAN.R-project.org/package=odbr>.
+-   Svab, Haydee; Milz, Beatriz; Oliveira, Diego Rabatone; Pereira,
+    Rafael H. M. (2023) odbr: Download Data from Brazil’s Origin
+    Destination Surveys. R package version v0.1.0,
+    <https://CRAN.R-project.org/package=odbr>.
 
 <!-- -->
 

diff --git a/docs/404.html b/docs/404.html
diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html