docs(README.md): reformat and update README for better readability an…

…d consistency docs(README.md): add section for reporting data errors to Natural Earth docs(README.md): update plot warnings and images for better clarity
ropensci · Aug 10, 2024 · 137dd19 · 137dd19
1 parent 56236ec
commit 137dd19
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -1,137 +1,120 @@
+---
+output: github_document
+---
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
-
 <!-- used devtools::build_readme() to update the md -->
 
+
+
 <!-- badges: start -->
 
-[![CRAN
-status](https://www.r-pkg.org/badges/version/rnaturalearth)](https://CRAN.R-project.org/package=rnaturalearth)
+[![CRAN status](https://www.r-pkg.org/badges/version/rnaturalearth)](https://CRAN.R-project.org/package=rnaturalearth)
 [![](https://badges.ropensci.org/22_status.svg)](https://github.com/ropensci/software-review/issues/22)
-[![Project Status: Active – The project has reached a stable, usable
-state and is being actively
-developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![R-CMD-check](https://github.com/ropensci/rnaturalearth/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/rnaturalearth/actions/workflows/R-CMD-check.yaml)
 
 <!-- badges: end -->
 
 # rnaturalearth
 
-An R package to hold and facilitate interaction with [Natural
-Earth](https://www.naturalearthdata.com/) map data.
+An R package to hold and facilitate interaction with [Natural Earth](https://www.naturalearthdata.com/) map data.
 
 This package provides :
 
-  - access to a pre-downloaded subset of Natural Earth v4.1.0 (March
-    2018) vector data commonly used in world mapping
+- access to a pre-downloaded subset of Natural Earth v4.1.0 (March 2018) vector data commonly used in world mapping
 
-  - easy subsetting by countries and regions
+- easy subsetting by countries and regions
 
-  - functions to download other Natural Earth vector and raster data
+- functions to download other Natural Earth vector and raster data
 
-  - a simple, reproducible and sustainable workflow from Natural Earth
-    data to rnaturalearth enabling updating as new versions become
-    available
+- a simple, reproducible and sustainable workflow from Natural Earth data to rnaturalearth enabling updating as new versions become available
 
-  - clarification of differences in world maps classified by countries,
-    sovereign states and map units
+- clarification of differences in world maps classified by countries, sovereign states and map units
 
-  - consistency with Natural Earth naming conventions so that
-    rnaturalearth users can use Natural Earth documentation
+- consistency with Natural Earth naming conventions so that rnaturalearth users can use Natural Earth documentation
 
-  - data in `sf` or `sv` formats
+- data in `sf` or `sv` formats
 
-The [Natural Earth](https://www.naturalearthdata.com/) website
-structures vector data by scale, category and type. These determine the
-filenames of downloads. rnaturalearth uses this structure to facilitate
-download (like an API).
+The [Natural Earth](https://www.naturalearthdata.com/) website structures vector data by scale, category and type. These determine the filenames of downloads. rnaturalearth uses this structure to facilitate download (like an API).
 
 ## Install rnaturalearth
 
 Install from CRAN :
 
-``` r
+```r
 install.packages("rnaturalearth")
 ```
 
-or install the development version from GitHub using
-[devtools](https://github.com/r-lib/devtools).
+or install the development version from GitHub using [devtools](https://github.com/r-lib/devtools).
 
-``` r
+```r
 devtools::install_github("ropensci/rnaturalearth")
 ```
 
-Data to support much of the package functionality are stored in two data
-packages that you will be prompted to install when required if you do
-not do so here.
+Data to support much of the package functionality are stored in two data packages that you will be prompted to install when required if you do not do so here.
 
-``` r
+```r
 devtools::install_github("ropensci/rnaturalearthdata")
 devtools::install_github("ropensci/rnaturalearthhires")
 ```
 
 ## First usage
 
-Here using `plot` as a simple, quick way to plot maps. Maps could also
-be made with `ggplot2`, `tmap` or other options. All retrieval functions
-accept an argument `returnclass = "sf"` to return package `sf` (Simple
-Features) or `returnclass = "sv"` (SpatVector) objects.
+Here using `plot` as a simple, quick way to plot maps. Maps could also be made with `ggplot2`, `tmap` or other options. All retrieval functions accept an argument `returnclass = "sf"` to return package `sf` (Simple Features) or `returnclass = "sv"` (SpatVector) objects.
+
 
 ``` r
 library(rnaturalearth)
 
 # world countries
 plot(ne_countries())
-Warning: plotting the first 9 out of 168 attributes; use max.plot = 168 to plot
-all
+Warning: plotting the first 10 out of 168 attributes; use max.plot = 168 to plot all
 ```
 
-![](man/figures/README-unnamed-chunk-2-1.png)<!-- -->
+![plot of chunk unnamed-chunk-2](man/figures/README-unnamed-chunk-2-1.png)
 
 ``` r
 
 # uk
 plot(ne_countries(country = "united kingdom"))
-Warning: plotting the first 10 out of 168 attributes; use max.plot = 168 to
-plot all
+Warning: plotting the first 9 out of 168 attributes; use max.plot = 168 to plot all
 ```
 
-![](man/figures/README-unnamed-chunk-2-2.png)<!-- -->
+![plot of chunk unnamed-chunk-2](man/figures/README-unnamed-chunk-2-2.png)
 
 ``` r
 
 # states, admin level1 boundaries
 plot(ne_states(country = "spain"))
-Warning: plotting the first 9 out of 121 attributes; use max.plot = 121 to plot
-all
+Warning: plotting the first 9 out of 121 attributes; use max.plot = 121 to plot all
 ```
 
-![](man/figures/README-unnamed-chunk-2-3.png)<!-- -->
+![plot of chunk unnamed-chunk-2](man/figures/README-unnamed-chunk-2-3.png)
 
 ## Introductory vignette
 
+
 ``` r
 vignette("rnaturalearth", package = "rnaturalearth")
 ```
 
 ## To download Natural Earth data not already in the package
 
-There are a wealth of other data available at the [Natural
-Earth](https://www.naturalearthdata.com/) website. `rnaturalearth` has
-functions to help with download of these data.
+There are a wealth of other data available at the [Natural Earth](https://www.naturalearthdata.com/) website. `rnaturalearth` has functions to help with download of these data.
 
-The data available are outlined in the two tables below and online
-[here](https://www.naturalearthdata.com/downloads/50m-physical-vectors/).
+The data available are outlined in the two tables below and online [here](https://www.naturalearthdata.com/downloads/50m-physical-vectors/).
 
-``` 
+
+```
 
 category   cultural 
 
 category   physical 
 ```
 
-Specify the `scale`, `category` and `type` of the vector you want as in
-the examples below.
+Specify the `scale`, `category` and `type` of the vector you want as in the examples below.
+
 
 ``` r
 # lakes
@@ -156,52 +139,42 @@ ggplot(rivers50) +
 
 ## Details of different country definitions and scales
 
+
 ``` r
 vignette("what-is-a-country", package = "rnaturalearth")
 ```
 
 ## Reproducible download of Natural Earth data into the package
 
-[Script](https://github.com/ropensci/rnaturalearthdata/blob/master/data-raw/data_download_script.r)
-used to get data into the accompanying data packages.
+[Script](https://github.com/ropensci/rnaturalearthdata/blob/master/data-raw/data_download_script.r) used to get data into the accompanying data packages.
+
+## Errors in the data?
+
+If you believe there is an issue with data provided by [Natural Earth](https://www.naturalearthdata.com/), please do not report it here. We are not responsible for the accuracy or maintenance of Natural Earth data. For any concerns regarding this data, please contact [Natural Earth](https://www.naturalearthdata.com/).
 
 ## Acknowledgements
 
-Thanks to [Lincoln Mullen](https://github.com/lmullen) for code
-structure inspiration from
-[USAboundaries](https://github.com/ropensci/USAboundaries), [Hadley
-Wickham](https://github.com/hadley) for comments and prompting, [Bob
-Rudis](https://github.com/hrbrmstr) for answers to stackoverflow
-questions about downloading Natural Earth data into R. The [Natural
-Earth team](https://www.naturalearthdata.com/about/contributors/) and
-[Nathan Kelso](https://github.com/nvkelso) for providing such a great
-resource.
+Thanks to [Lincoln Mullen](https://github.com/lmullen) for code structure inspiration from [USAboundaries](https://github.com/ropensci/USAboundaries), [Hadley Wickham](https://github.com/hadley) for comments and prompting, [Bob Rudis](https://github.com/hrbrmstr) for answers to stackoverflow questions about downloading Natural Earth data into R. The [Natural Earth team](https://www.naturalearthdata.com/about/contributors/) and [Nathan Kelso](https://github.com/nvkelso) for providing such a great resource.
 
 ## Potential future work
 
 ### Potential additional data
 
-  - Country synonyms lookup
-      - dataframe with ISO3 and country synonyms
-      - similar to
-        <https://github.com/AndySouth/rworldmap/blob/master/data/countrySynonyms.rda>
-  - Country larger regions lookup
-      - dataframe with ISO3 and membership of different regional
-        groupings, e.g. continent, least developed countries etc.
-      - similar to
-        <https://github.com/AndySouth/rworldmap/blob/master/data/countryRegions.rda>
+- Country synonyms lookup
+  - dataframe with ISO3 and country synonyms
+  - similar to https://github.com/AndySouth/rworldmap/blob/master/data/countrySynonyms.rda
+- Country larger regions lookup
+  - dataframe with ISO3 and membership of different regional groupings, e.g. continent, least developed countries etc.
+  - similar to https://github.com/AndySouth/rworldmap/blob/master/data/countryRegions.rda
 
 ### Potential additional functions
 
-  - facilitate joining of user data to country boundaries
-
-      - similar to
-        <https://github.com/AndySouth/rworldmap/blob/master/R/joinCountryData2Map.R>
-      - … but with a better name
-      - similar allowing of join by ISO codes or names, with attempted
-        synonym matching
-      - similar reporting of country joining success and failure
-
-  - facilitate subsetting by country groupings
-
-      - e.g. least developed countries etc.
+- facilitate joining of user data to country boundaries
+
+  - similar to https://github.com/AndySouth/rworldmap/blob/master/R/joinCountryData2Map.R
+  - ... but with a better name
+  - similar allowing of join by ISO codes or names, with attempted synonym matching
+  - similar reporting of country joining success and failure
+
+- facilitate subsetting by country groupings
+  - e.g. least developed countries etc.
diff --git a/man/figures/README-unnamed-chunk-2-1.png b/man/figures/README-unnamed-chunk-2-1.png
diff --git a/man/figures/README-unnamed-chunk-2-2.png b/man/figures/README-unnamed-chunk-2-2.png
diff --git a/man/figures/README-unnamed-chunk-2-3.png b/man/figures/README-unnamed-chunk-2-3.png