diff --git a/DESCRIPTION b/DESCRIPTION index bf485df..e95ee16 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -9,11 +9,11 @@ Authors@R: c( person("Rafael H. M.", "Pereira", , "rafa.pereira.br@gmail.com", 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, @@ -21,12 +21,12 @@ Imports: 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 index 037d424..1a1630c 100644 --- 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 index 7959d38..f2771e4 100644 --- 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 index 3350517..b1d3d05 100644 --- 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 index 5c796f9..4b3a78e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -23,13 +23,16 @@ coverage](https://codecov.io/gh/hsvab/odbr/branch/main/graph/badge.svg)](https:/ -**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 @@ -37,7 +40,8 @@ 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, . +- 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, . ``` bibentry( @@ -124,4 +129,7 @@ bibentry( ## Sponsors ropensci logo -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 index b1c6c64..8ca769a 100644 --- 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,7 +72,7 @@ df <- read_dictionary( ) ``` -## Available non-harmonized datasets: +## Available datasets: **The original geodetic reference system remained unchanged.** @@ -80,12 +80,10 @@ 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) | -## 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, - . + Rafael H. M. + +2023) odbr: Download Data from Brazil’s Origin Destination Surveys. R + package version v0.1.0, . diff --git a/man/read_dictionary.Rd b/man/read_dictionary.Rd index de04719..0f4bf76 100644 --- a/man/read_dictionary.Rd +++ b/man/read_dictionary.Rd @@ -28,9 +28,11 @@ Options include \code{c("pt", "en", "es")}.} A \code{"data.frame"} object. } \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 \code{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). } \examples{ \dontshow{if (identical(tolower(Sys.getenv("NOT_CRAN")), "true")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} diff --git a/man/read_map.Rd b/man/read_map.Rd index 1ef11dc..8340421 100644 --- a/man/read_map.Rd +++ b/man/read_map.Rd @@ -32,10 +32,14 @@ if it was already downloaded. Defaults to FALSE.} An \verb{"sf" "data.frame"} object } \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. +\code{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 \code{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. } \examples{ \dontshow{if (identical(tolower(Sys.getenv("NOT_CRAN")), "true")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} diff --git a/man/read_od.Rd b/man/read_od.Rd index 14098a8..972c611 100644 --- a/man/read_od.Rd +++ b/man/read_od.Rd @@ -28,9 +28,11 @@ if it was already downloaded. Defaults to FALSE.} A \code{"data.frame"} object. } \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. +\code{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 \code{read_dictionary()} function for the +same survey cohort. } \examples{ \dontshow{if (identical(tolower(Sys.getenv("NOT_CRAN")), "true")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} diff --git a/vignettes/odbr.Rmd b/vignettes/odbr.Rmd index 8eb2fdb..2198af5 100644 --- 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.