descriptions / documentation ajusts regarding CRAN feedback

hsvab · Oct 21, 2023 · f666894 · f666894
1 parent b6eaf5d
commit f666894
Show file tree

Hide file tree

Showing 10 changed files with 87 additions and 67 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -9,24 +9,24 @@ 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 helpful 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.
 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.
+#' Return 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,13 @@
 #' 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 geodetic 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.
+#' It is also necessary to specify the geometry granularity wanted, be it
+#' "municipality", "district" or "zone" level of details. Of course, not all
+#' geometries 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 reefer to the `read_dictionary()` function for the
+#' same survey cohort.
 #'
 #' @template city
 #' @template year

diff --git a/README.Rmd b/README.Rmd
@@ -23,21 +23,25 @@ coverage](https://codecov.io/gh/hsvab/odbr/branch/main/graph/badge.svg)](https:/
 
 <!-- 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/) with:
 
 ``` r
 # or use the development version with latest features
@@ -48,12 +52,13 @@ 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 data set using a single line of code. Like this:
 
 ```{r example}
+# Return data from OD Surveys database as data.frame
 library(odbr)
 
-# Return data from OD Surveys database as data.frame
 df <- read_od(
   city = "Sao Paulo",
   year = 2017,
@@ -77,7 +82,7 @@ df <- read_dictionary(
 )
 ```
 
-## Available non-harmonized datasets:
+## Available datasets:
 
 **The original geodetic reference system remained unchanged.**
 
@@ -86,28 +91,28 @@ df <- read_dictionary(
 |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)
 
 
+**There is no harmonized data available yet.**
 
-## Available harmonized datasets:
-
-**All harmonized datasets use geodetic reference system "SIRGAS2000", CRS(4674).**
-
-There is not harmonized data available yet.
-
-
+*All harmonized datasets use geodetic reference system "SIRGAS2000", CRS(4674).*
 
 ## 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/)
+The logo was designed by
+[Marcos Kyoto de Tani e 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>.
 
 ```
 bibentry(
@@ -124,4 +129,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
@@ -21,8 +21,8 @@ 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
@@ -46,9 +46,9 @@ becomes intuitive to download any data set using a single line of code.
 Like this:
 
 ``` r
+# Return data from OD Surveys database as data.frame
 library(odbr)
 
-# Return data from OD Surveys database as data.frame
 df <- read_od(
   city = "Sao Paulo",
   year = 2017,
@@ -72,20 +72,18 @@ df <- read_dictionary(
 )
 ```
 
-## Available non-harmonized datasets:
+## Available datasets:
 
 **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) |
 
-## Available harmonized datasets:
+**There is no harmonized data available yet.**
 
-**All harmonized datasets use geodetic reference system “SIRGAS2000”,
-CRS(4674).**
-
-There is not harmonized data available yet.
+*All harmonized datasets use geodetic reference system “SIRGAS2000”,
+CRS(4674).*
 
 ## Contributing to odbr
 
@@ -103,9 +101,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>.
+  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/man/read_dictionary.Rd b/man/read_dictionary.Rd
diff --git a/man/read_map.Rd b/man/read_map.Rd
diff --git a/man/read_od.Rd b/man/read_od.Rd
diff --git a/vignettes/odbr.Rmd b/vignettes/odbr.Rmd
@@ -17,11 +17,11 @@ knitr::opts_chunk$set(
 )
 ```
 
-
-**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** provides helpful 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.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.
 
 
 *obs.:* The package is still under development. At the moment, odbr only
@@ -94,7 +94,7 @@ df <- read_dictionary(
 ```
 
 
-## Available non-harmonized datasets:
+## Available datasets:
 
 **The original geodetic reference system remained unchanged.**
 
@@ -103,9 +103,7 @@ df <- read_dictionary(
 |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)
 
 
+**There is no harmonized data available yet.**
 
-## Available harmonized datasets:
-
-**All harmonized datasets use geodetic reference system "SIRGAS2000", CRS(4674).**
+*All harmonized datasets use geodetic reference system "SIRGAS2000", CRS(4674).*
 
-There is not harmonized data available yet.