ggOceanMaps

June 22, 2026 · View on GitHub

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

DOI R-CMD-check CRAN_Status_Badge

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")

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)
Bathymetric basemap of the North Atlantic and Arctic with a red rectangle outlining a data box, illustrating basemap() with bathymetry and transform_coord().

See the ggOceanMaps website, function reference, and the user manual for how to use and modify the maps plotted by the package.

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. Each entry below lists which map elements it provides, the source, and the licence it is distributed under:

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 (2026). _ggOceanMaps: Plot Data on Oceanographic Maps
#>   using 'ggplot2'_. R package version 3.0.0,
#>   <https://mikkovihtakari.github.io/ggOceanMaps/>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {ggOceanMaps: Plot Data on Oceanographic Maps using 'ggplot2'},
#>     author = {Mikko Vihtakari},
#>     year = {2026},
#>     note = {R package version 3.0.0},
#>     url = {https://mikkovihtakari.github.io/ggOceanMaps/},
#>   }

Getting help

ggOceanMaps is designed to be used with the help of AI assistants. Often the quickest way to get help is to ask your AI agent (Claude Code, Codex, Copilot, ChatGPT, Claude.ai, GitHub Copilot, Mistral, and the like): paste the link to the ggOceanMaps GitHub site, https://github.com/MikkoVihtakari/ggOceanMaps/, and ask the agent to familiarize itself with the site before answering your question. The website contains the full user manual, the in-depth articles, the cookbook, and the function reference, and the repository includes an AGENTS.md file written specifically to help agents use it correctly. Pointing the agent at these resources first leads to much better answers than asking from memory alone.

If you would rather ask a human, or your problem involves a bug in ggOceanMaps, post your problem to Stack Overflow or open an issue in 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.