doc: better general doc and readme file

adatar-do · Dec 1, 2023 · 700bea8 · 700bea8
1 parent b47cf48
commit 700bea8
Show file tree

Hide file tree

Showing 23 changed files with 258 additions and 18 deletions.
diff --git a/R/data.R b/R/data.R
@@ -0,0 +1,9 @@
+#' Percentage distribution by provinces of remittances received by the Dominican Republic
+#'
+#' @format ## `remesas_provincias`
+#' \describe{
+#'   \item{province}{Full name of the province}
+#'   \item{percentage}{Percentage of the total remittances received in 2010}
+#' }
+#' @source <https://www.bancentral.gov.do/a/d/2532-sector-externo>
+'remesas_provincias'
diff --git a/README.Rmd b/README.Rmd
@@ -27,17 +27,69 @@ The goal of sfDR is to provide a comprehensive suite of simple feature (sf) obje
 
 You can install the development version of sfDR from r-universe with:
 
-```r
-install.packages('sfDR', repos = c('https://adatar-do.r-universe.dev', 'https://cloud.r-project.org'))
+```{r}
+if (!require('sfDR')) install.packages('sfDR', repos = c('https://adatar-do.r-universe.dev'))
+if (!require('dplyr')) install.packages('dplyr')
+if (!require('ggplot2')) install.packages('ggplot2')
 ```
 
 ## Example
 
 This is a basic example showing how to use sfDR to plot a Dominican Republic province map:
 
-```r
+```{r}
 library(sfDR)
+library(dplyr)
 
-# Plotting the map of a specific province
-plot(DR_PROV)
+DR_PROV_SF <- sf::st_as_sf(DR_PROV)
+
+plot(DR_PROV_SF)
+```
+
+Suppose you have a dataset showing the percentage distribution of remittances received in each province of the Dominican Republic for a specific year. To visualize this data using a graph with sfDR, you first need to combine the metadata with the simple features.
+
+
+```{r}
+DR_PROV_SF <- DR_PROV_SF |>
+  left_join(dr_province, by = join_by(PROV_ID))
+
+DR_PROV_SF %>% 
+  sf::st_drop_geometry()
+```
+
+The original simple features dataset only includes the PROV_ID variable. Additional variables are incorporated through the dr_province object.
+
+```{r}
+ datos <- DR_PROV_SF |>
+  left_join(remesas_provincias, by = join_by('PROV_NAME' == 'province'))
+
+datos %>% 
+  sf::st_drop_geometry()
 ```
+
+It's important to note that non-ASCII characters can become corrupted when stored in the package, which may affect the merging of the data sets.
+
+> We recommend cleaning any errors before performing the merge. We will soon release another package with functions designed to facilitate this process.
+
+```{r}
+datos |>
+  select(percentage) %>% 
+  plot()
+```
+
+To get the desired graph, just apply the plot function to your data.
+
+Next, we show how to achieve a similar result using ggplot2. This serves to demonstrate how to create maps with both libraries and to highlight the simplicity of the process by integrating everything in one step.
+
+```{r}
+library(ggplot2)
+
+DR_PROV %>%
+  sf::st_as_sf() %>% 
+  left_join(dr_province) %>% 
+  left_join(remesas_provincias, by = join_by('PROV_NAME' == 'province')) %>% 
+  ggplot() +
+  geom_sf(aes(fill = percentage)) +
+  theme_void()
+```
+
diff --git a/README.md b/README.md
@@ -22,7 +22,9 @@ Republic, facilitating geospatial analysis and mapping.
 You can install the development version of sfDR from r-universe with:
 
 ``` r
-install.packages('sfDR', repos = c('https://adatar-do.r-universe.dev', 'https://cloud.r-project.org'))
+if (!require('sfDR')) install.packages('sfDR', repos = c('https://adatar-do.r-universe.dev'))
+if (!require('dplyr')) install.packages('dplyr')
+if (!require('ggplot2')) install.packages('ggplot2')
 ```
 
 ## Example
@@ -32,7 +34,148 @@ Republic province map:
 
 ``` r
 library(sfDR)
+library(dplyr)
 
-# Plotting the map of a specific province
-plot(DR_PROV)
+DR_PROV_SF <- sf::st_as_sf(DR_PROV)
+
+plot(DR_PROV_SF)
+```
+
+<img src="man/figures/README-unnamed-chunk-3-1.png" width="100%" />
+
+Suppose you have a dataset showing the percentage distribution of
+remittances received in each province of the Dominican Republic for a
+specific year. To visualize this data using a graph with sfDR, you first
+need to combine the metadata with the simple features.
+
+``` r
+DR_PROV_SF <- DR_PROV_SF |>
+  left_join(dr_province, by = join_by(PROV_ID))
+
+DR_PROV_SF %>% 
+  sf::st_drop_geometry()
+#>    PROV_ID PROV_CODE                  PROV_NAME
+#> 1       21        SC             San CristÃ³bal
+#> 2       14       MTS   MarÃa Trinidad SÃ¡nchez
+#> 3       17       PER                    Peravia
+#> 4       20       SAM                    SamanÃ¡
+#> 5       18        PP               Puerto Plata
+#> 6       11        LA              La Altagracia
+#> 7       07        EP               ElÃas PiÃ±a
+#> 8       10       IND              Independencia
+#> 9       16       PED                 Pedernales
+#> 10      03       BAH                    Baoruco
+#> 11      03       BAH                   Bahoruco
+#> 12      04       BAR                   Barahona
+#> 13      26       SRO        Santiago RodrÃguez
+#> 14      27       VAL                   Valverde
+#> 15      19       HMI           Hermanas Mirabal
+#> 16      19       SAL                    Salcedo
+#> 17      24       SRA          SÃ¡nchez RamÃrez
+#> 18      13        LV                    La Vega
+#> 19      28        MN            MonseÃ±or Nouel
+#> 20      31       SJO          San JosÃ© de Ocoa
+#> 21      22        SJ                   San Juan
+#> 22      22        SJ     San Juan de la Maguana
+#> 23      02       AZU                       Azua
+#> 24      25       SAN                   Santiago
+#> 25      25       SAN Santiago de los Caballeros
+#> 26      06       DUA                     Duarte
+#> 27      09       ESP                  Espaillat
+#> 28      29        MP                Monte Plata
+#> 29      30       HMA                 Hato Mayor
+#> 30      12        LR                  La Romana
+#> 31      23       SPM      San Pedro de MacorÃs
+#> 32      08        ES                   El Seibo
+#> 33      08        ES                   El Seybo
+#> 34      01        DN          Distrito Nacional
+#> 35      05       DAJ                   DajabÃ³n
+#> 36      32        SD              Santo Domingo
+#> 37      15        MC               Monte Cristi
 ```
+
+The original simple features dataset only includes the PROV_ID variable.
+Additional variables are incorporated through the dr_province object.
+
+``` r
+ datos <- DR_PROV_SF |>
+  left_join(remesas_provincias, by = join_by('PROV_NAME' == 'province'))
+
+datos %>% 
+  sf::st_drop_geometry()
+#>    PROV_ID PROV_CODE                  PROV_NAME  percentage
+#> 1       21        SC             San CristÃ³bal          NA
+#> 2       14       MTS   MarÃa Trinidad SÃ¡nchez          NA
+#> 3       17       PER                    Peravia 0.005948295
+#> 4       20       SAM                    SamanÃ¡          NA
+#> 5       18        PP               Puerto Plata 0.018996422
+#> 6       11        LA              La Altagracia          NA
+#> 7       07        EP               ElÃas PiÃ±a          NA
+#> 8       10       IND              Independencia          NA
+#> 9       16       PED                 Pedernales          NA
+#> 10      03       BAH                    Baoruco          NA
+#> 11      03       BAH                   Bahoruco          NA
+#> 12      04       BAR                   Barahona          NA
+#> 13      26       SRO        Santiago RodrÃguez          NA
+#> 14      27       VAL                   Valverde 0.004422258
+#> 15      19       HMI           Hermanas Mirabal          NA
+#> 16      19       SAL                    Salcedo          NA
+#> 17      24       SRA          SÃ¡nchez RamÃrez          NA
+#> 18      13        LV                    La Vega 0.014144396
+#> 19      28        MN            MonseÃ±or Nouel          NA
+#> 20      31       SJO          San JosÃ© de Ocoa          NA
+#> 21      22        SJ                   San Juan          NA
+#> 22      22        SJ     San Juan de la Maguana          NA
+#> 23      02       AZU                       Azua          NA
+#> 24      25       SAN                   Santiago 0.039947667
+#> 25      25       SAN Santiago de los Caballeros          NA
+#> 26      06       DUA                     Duarte 0.008876070
+#> 27      09       ESP                  Espaillat 0.004489833
+#> 28      29        MP                Monte Plata          NA
+#> 29      30       HMA                 Hato Mayor          NA
+#> 30      12        LR                  La Romana 0.008441885
+#> 31      23       SPM      San Pedro de MacorÃs          NA
+#> 32      08        ES                   El Seibo          NA
+#> 33      08        ES                   El Seybo          NA
+#> 34      01        DN          Distrito Nacional 0.090322521
+#> 35      05       DAJ                   DajabÃ³n          NA
+#> 36      32        SD              Santo Domingo 0.098682428
+#> 37      15        MC               Monte Cristi          NA
+```
+
+It’s important to note that non-ASCII characters can become corrupted
+when stored in the package, which may affect the merging of the data
+sets.
+
+> We recommend cleaning any errors before performing the merge. We will
+> soon release another package with functions designed to facilitate
+> this process.
+
+``` r
+datos |>
+  select(percentage) %>% 
+  plot()
+```
+
+<img src="man/figures/README-unnamed-chunk-6-1.png" width="100%" />
+
+To get the desired graph, just apply the plot function to your data.
+
+Next, we show how to achieve a similar result using ggplot2. This serves
+to demonstrate how to create maps with both libraries and to highlight
+the simplicity of the process by integrating everything in one step.
+
+``` r
+library(ggplot2)
+
+DR_PROV %>%
+  sf::st_as_sf() %>% 
+  left_join(dr_province) %>% 
+  left_join(remesas_provincias, by = join_by('PROV_NAME' == 'province')) %>% 
+  ggplot() +
+  geom_sf(aes(fill = percentage)) +
+  theme_void()
+#> Joining with `by = join_by(PROV_ID)`
+```
+
+<img src="man/figures/README-unnamed-chunk-7-1.png" width="100%" />
diff --git a/data-raw/Remesas_PR.xlsx b/data-raw/Remesas_PR.xlsx
diff --git a/data-raw/remesas_provincias.R b/data-raw/remesas_provincias.R
@@ -0,0 +1,11 @@
+library(dplyr)
+library(tidyr)
+
+remesas_provincias <- readxl::read_excel('data-raw/Remesas_PR.xlsx', skip = 6) %>%
+  select(1:2) %>%
+  drop_na() %>%
+  setNames(c('province', 'percentage')) %>%
+  filter(percentage != 1)
+
+
+usethis::use_data(remesas_provincias, overwrite = TRUE)
diff --git a/data/remesas_provincias.rda b/data/remesas_provincias.rda
diff --git a/man/DR_DM.Rd b/man/DR_DM.Rd
diff --git a/man/DR_MUN.Rd b/man/DR_MUN.Rd
diff --git a/man/DR_PROV.Rd b/man/DR_PROV.Rd
diff --git a/man/DR_REG.Rd b/man/DR_REG.Rd
diff --git a/man/DR_SEC.Rd b/man/DR_SEC.Rd
diff --git a/man/dr_municipal_district.Rd b/man/dr_municipal_district.Rd
diff --git a/man/dr_municipality.Rd b/man/dr_municipality.Rd
diff --git a/man/dr_province.Rd b/man/dr_province.Rd
diff --git a/man/dr_region.Rd b/man/dr_region.Rd
diff --git a/man/dr_section.Rd b/man/dr_section.Rd
diff --git a/man/figures/README-unnamed-chunk-28-1.png b/man/figures/README-unnamed-chunk-28-1.png
diff --git a/man/figures/README-unnamed-chunk-3-1.png b/man/figures/README-unnamed-chunk-3-1.png
diff --git a/man/figures/README-unnamed-chunk-31-1.png b/man/figures/README-unnamed-chunk-31-1.png
diff --git a/man/figures/README-unnamed-chunk-32-1.png b/man/figures/README-unnamed-chunk-32-1.png
diff --git a/man/figures/README-unnamed-chunk-6-1.png b/man/figures/README-unnamed-chunk-6-1.png
diff --git a/man/figures/README-unnamed-chunk-7-1.png b/man/figures/README-unnamed-chunk-7-1.png
diff --git a/man/remesas_provincias.Rd b/man/remesas_provincias.Rd