ggOceanMaps

Plot data on oceanographic maps using ggplot2. R package version 2.2.0

Overview

The ggOceanMaps package for R allows plotting data on bathymetric maps using ggplot2. The package is designed for ocean sciences and greatly simplifies bathymetric map plotting anywhere around the globe. ggOceanMaps uses openly available geographic data. Citing the particular data sources is advised by the CC-BY licenses whenever maps from the package are published (see the Citations and data sources section).

The ggOceanMaps package has been developed by the Institute of Marine Research. Note that the package comes with absolutely no warranty and that maps generated by the package are meant for plotting scientific data only. The maps are coarse generalizations of third-party data and therefore inaccurate. Any bug reports and code fixes are warmly welcomed. See Contributions for further details.

Installation

The package is available on CRAN and as a GitHub version, which is updated more frequently than the CRAN version.

Installation of the GitHub version:

remotes::install_github("MikkoVihtakari/ggOceanMaps")

Installation of the CRAN version:

install.packages("ggOceanMaps")

Note that >2.0 versions of ggOceanMaps do not require the ggOceanMapsData package any longer. Detailed map data are downloaded when needed from the ggOceanMapsLargeData repository.

Usage

ggOceanMaps extends on ggplot2. The package uses spatial (sf) shape- (e.g. vector) and (stars) raster files, geospatial packages for R to manipulate, and ggplot2 to plot these data. The vector and raster plotting is conducted internally in the basemap function, which uses ggplot’s sf object plotting capabilities. Maps are plotted using the basemap() or qmap() functions that work almost similarly to ggplot() as a base for adding further layers to the plot using the + operator. The maps generated this way already contain multiple ggplot layers. Consequently, the data argument needs to be explicitly specified inside geom_* functions when adding ggplot2 layers. Depending on the location of the map, the underlying coordinates may be projected. Decimal degree coordinates need to be transformed to the projected coordinates using the transform_coord, ggspatial, or geom_sf functions.

library(ggOceanMaps)

dt <- data.frame(lon = c(-30, -30, 30, 30), lat = c(50, 80, 80, 50))

basemap(data = dt, bathymetry = TRUE) + 
  geom_polygon(data = transform_coord(dt), aes(x = lon, y = lat), 
               color = "red", fill = NA)

See the ggOceanMaps website, function reference, and the user manual for how to use and modify the maps plotted by the package. You may also find these slides about the package useful.

Data path

While ggOceanMaps allows plotting any custom-made shapefiles, the package contains a shortcut to plot higher resolution maps for certain areas needed by the author without the need of generating the shapefiles manually. These high-resolution shapefiles are downloaded from the ggOceanMapsLargeData repository. As a default, the shapefiles are downloaded into a temporary directory meaning that the user would need to download the large shapefiles every time they restart R. This limitation is set by CRAN policies. You can define a custom folder for high-resolution shapefiles on your computer by modifying your .Rprofile file (e.g. usethis::edit_r_profile()). Add the following lines to the file:

.ggOceanMapsenv <- new.env()
.ggOceanMapsenv$datapath <- 'YourCustomPath'

It is smart to use a directory R has writing access to. For example "~/ggOceanMapsLargeData" would work for most operating systems.

You will need to set up the data path to your .Rprofile file only once and ggOceanMaps will find the path even though you updated your R or packages. ggOceanMaps will inform you about your data path when you load the package.

Citations and data sources

The data used by the package are not the property of the Institute of Marine Research nor the author of the package. It is, therefore, important that you cite the data sources used in a map you generate with the package. The spatial data used by this package have been acquired from the following sources:

ggOceanMapsData land polygons. Natural Earth Data 1:10m Physical Vectors with the Land and Minor Island datasets combined. Distributed under the CC Public Domain license (terms of use).
ggOceanMapsData glacier polygons. Natural Earth Data 1:10m Physical Vectors with the Glaciated Areas and Antarctic Ice Shelves datasets combined. Distributed under the CC Public Domain license (terms of use).
ggOceanMapsData bathymetry. NOAA National Centers for Environmental Information. 2022: ETOPO 2022 15 Arc-Second Global Relief Model. NOAA National Centers for Environmental Information. DOI: 10.25921/fd45-gt74. Distributed under the U.S. Government Work license.
Detailed shapefiles of Svalbard and the Norwegian coast in ggOceanMapsLargeData are from Geonorge.no. Distributed under the CC BY 4.0 license.
Detailed land polygons of Europe. European Environment Agency. The coastline is a hybrid product obtained from satellite imagery from two projects: EUHYDRO (Pan-European hydrographic and drainage database) and GSHHG (A Global Self-consistent, Hierarchical, High-resolution Geography Database), as well as some manual amendments to meet requirements from EU Nature Directives, Water Framework Directive and Marine Strategy Framework. Distributed under the CC BY 4.0 license (terms of use)

Further, please cite the package whenever maps generated by the package are published. For up-to-date citation information, please use:

citation("ggOceanMaps")
#> To cite package 'ggOceanMaps' in publications use:
#> 
#>   Vihtakari M (2024). _ggOceanMaps: Plot Data on Oceanographic Maps
#>   using 'ggplot2'_. R package version 2.2.0,
#>   <https://CRAN.R-project.org/package=ggOceanMaps>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {ggOceanMaps: Plot Data on Oceanographic Maps using 'ggplot2'},
#>     author = {Mikko Vihtakari},
#>     year = {2024},
#>     note = {R package version 2.2.0},
#>     url = {https://CRAN.R-project.org/package=ggOceanMaps},
#>   }

Getting help

If your problem does not involve bugs in ggOceanMaps, the quickest way of getting help can be posting your problem to Stack Overflow. Alternatively, you are welcome to use the issues section on GitHub. Please remember to include a reproducible example that illustrates your problem and to add links to potential cross-posts.

Contributions

Any contributions to the package are more than welcome. Please contact the package maintainer Mikko Vihtakari (mikko.vihtakari@hi.no) to discuss your ideas on improving the package. Bug reports and corrections should be submitted directly to the GitHub site. Please include a minimal reproducible example. Considerable contributions to the package development will be credited with authorship.

MikkoVihtakari / ggOceanMaps

readme