garretrc/ggvoronoi

Easy Voronoi diagram heatmaps with ggplot2

ggvoronoi: Voronoi Diagrams and Heatmaps with 'ggplot2'

Overview

'ggvoronoi' is an R package that allows for easy creation and manipulation of Voronoi diagrams, which are tools for determining nearest neighbor regions for a given set of points. Voronoi diagram regions are calculated using the R package 'deldir' by Rolf Turner. The output from 'deldir' is converted to the spatial object format provided by the 'sp' package from Edzer Pebesma and Roger Bivand. This allows for additional functionality beyond what is provided in 'deldir': diagrams can now be extended to heatmaps and users can now specify a bounding region for the diagram. From there, visualization capabilities are implemented using the framework of 'ggplot2', a popular graphics package for R created by Hadley Wickham, or the user can analyze the diagram using any of R's spatial data analysis packages.

What is a Voronoi diagram?

A Voronoi diagram is a nearest neighbor diagram: given a set of generator points, the Voronoi diagram creates nearest neighbor cells. Each cell is formed around one generator point, and the set of points closest to that generator is fully contained in its cell. The resulting diagram can be used to find the nearest generator for an arbitrary point or to interpolate the blank space around each generator to create a heatmap.

Voronoi diagrams have a multitude of applications, but 'ggvoronoi' implements tools for data visualization and spatial data analysis in R. For data visualization, 'ggvoronoi' fits nicely within the 'ggplot2' framework, so R users experienced with the popular visualization package can create Voronoi diagrams and heatmaps around any point-level dataset within minutes. For spatial data analysis, R users can create a Voronoi diagram within the 'sp' framework as a SpatialPolygonsDataFrame object. From there, the user can find the nearest generator point to each location in a new SpatialPoints object or use tools, such as those contained in 'rgeos', to analyze the diagram.

Installation

To install 'ggvoronoi' from CRAN:

install.packages("ggvoronoi")

Or install the latest development version from this repository:

remotes::install_github("garretrc/ggvoronoi", dependencies = TRUE, build_opts = c("--no-resave-data"))

Finally, with either verison you can load the R package with the typical method:

library(ggvoronoi)

Getting Started

With the vignette, you can view some examples and create your first Voronoi diagram!

vignette("ggvoronoi")

Alternatively, the vignette is available here.

Contact info

For questions about usage/syntax or for reporting bugs, email Robert at [email protected] or raise an issue on this repository.

To contribute to the package or see past contributions, see the CONTRIBUTING.md file

Changes

v0.8.5: Fixes thanks to Duncan Murdoch, resubmitting to CRAN

v0.8.2: Added unit tests using 'testthat' and 'vdiffr'. Minor improvements to vignette and README.md

v0.8.1: Fixed bug when using a discrete value for fill mapping. Removed google maps API call in the vignette.

ggvoronoi's Issues

Oxford bikes data set documentation

The oxford_bikes data set cites four authors as a source but provides no additional information. Where did this data set come from, and how was it generated?

Part of this JOSS review.

Forthcoming release of ggplot2 and ggvoronoi

We are contacting you because you are the maintainer of ggvoronoi, which imports ggplot2 and uses vdiffr to manage visual test cases. The upcoming release of ggplot2 includes several improvements to plot rendering, including the ability to specify lineend and linejoin in geom_rect() and geom_tile(), and improved rendering of text. These improvements will result in subtle changes to your vdiffr dopplegangers when the new version is released.

Because vdiffr test cases do not run on CRAN by default, your CRAN checks will still pass. However, we suggest updating your visual test cases with the new version of ggplot2 as soon as possible to avoid confusion. You can install the development version of ggplot2 using remotes::install_github("tidyverse/ggplot2").

If you have any questions, let me know!

author contributions?

One author contributed code through Git, and another co-authored the vignette, though i don't doubt that all four credited authors contributed significantly to the package. To address one question from the review, could the documentation or the software paper include a brief note on each author's contribution?

Part of this JOSS review.

Add to ggplot2 extension list

I would be very cool if ggvoronoi was added to the list of ggplot2 extensions: https://www.ggplot2-exts.org/gallery/

It would also definitely improve discoverability.

See here for the instructions on how to add your package to the list.

(un-)export ggproto objects

The 'ggproto' object StatVoronoi is exported but not documented; should it be un-exported (like GeomVoronoi)? or should both be exported (and documented)?

Part of this JOSS review.

Hyperlinks in README

It'd be nice to see some hyperinks to outside references as well as internal documents. For, example when you reference 'deldir' it'd be nice to link to CRAN for ease of reference. Secondly, when you discuss internal files like:

To contribute to the package or see past contributions, see the CONTRIBUTING.md file

linking the text to the CONTRIBUTING.md file would be pretty nice, especially for someone unfamiliar with packages/GitHub.

statement of need

The vignette provides several examples, including two real-world case studies. However, neither the DESCRIPTION nor the vignette include a few general sentences on the kinds of problems the package is intended to help users solve (as the software paper does).

Such purpose statement might be included in a central documentation page accessible via ?ggvoronoi. (See ?ggplot2 for an example.)

Part of this JOSS review.

SImplified ggvoronoi for any xy data

It would be nice to have a slimmed down version of ggvoronoi that is devoid of the map related stuff. No rgeos, sp, raster etc. Just creates voronoi plots from any xy data.

Extend bounding box when using geom_voronoi

Great ggplot2 add-on package!

What is the easiest way to expand or modify the bounding area when calling geom_voronoi?

In the example below, I would like to expand the bounding box in both x and y dimensions.

df = data.frame(1:10,rnorm(10),rnorm(10))
colnames(df) = c('label','x','y')
ggplot(df) +
geom_voronoi(aes(x,y,fill=label))

Thanks!
John

Sample diagram

Thanks for the package. I'd like to suggest you put a sample diagram in README.

add hyperlinks in documentation

The documentation is not hyperlinked. For example:

• there are references in ?geom_voronoi to stat_voronoi, but one must navigate to the index in order to find them
• other packages are not linked when referenced, e.g. when ?voronoi_polygon refers to geom_polygon
• the ncdc_locations data set documentation includes a URL but it is not clickable

Could this be remedied?

I don't know how much this matters in general; but, because this package is targeted to students, i think navigational convenience is especially important. (I recommend Wickham's book for guidance, but there are other resources.)

Part of this JOSS review.

Set outline to convex hull

Is there an option to set geom_voronoi() argument outline to show convex hull of the points?

Update github installation to reflect devtools/remotes changes.

When I installed the package from GitHub the repo was not built, likely because the build_vignettes option is no longer part of the remotes backend for devtools (>= v 2.0.1)). Also devtools is large so for the case of installing a package all of devtools is not needed, maybe opt for just the remotes version which detools is just reexporting. Something like:

remotes::install_github("garretrc/ggvoronoi", dependencies = TRUE, build_opts = c("--no-resave-data"))

Please remove dependencies on **rgdal**, **rgeos**, and/or **maptools**

This package depends on (depends, imports or suggests) raster and one or more of the retiring packages rgdal, rgeos or maptools (https://r-spatial.org/r/2022/04/12/evolution.html, https://r-spatial.org/r/2022/12/14/evolution2.html). Since raster 3.6.3, all use of external FOSS library functionality has been transferred to terra, making the retiring packages very likely redundant. It would help greatly if you could remove dependencies on the retiring packages as soon as possible.

omitted DOI for ggplot2

JOSS prefers that references include DOIs if possible. Most of the references without DOIs are R packages or blog posts (and don't have DOIs), but Wickham's book on ggplot2 is cited as a book and therefore could helpfully include the DOI of the Springer–Verlag edition.

Part of this JOSS review.