Discrete Global Grids for R

Spatial analyses involving binning require that every bin have the same area, but this is impossible using a rectangular grid laid over the Earth or over any projection of the Earth. Discrete global grids use hexagons, triangles, and diamonds to overcome this issue, overlaying the Earth with equally-sized bins. This package provides utilities for working with discrete global grids, along with utilities to aid in plotting such data.


Spatial Analysis Done Right

You want to do spatial statistics, and it's going to involve binning.

Binning with a rectangular grid introduces messy distortions. At the macro-scale using a rectangular grid does things like making Greenland bigger than the United States and Antarctica the largest continent.

But this kind of distortion is present no matter what the resolution is; in fact, it shows up whenever you project a sphere onto a plane.

What you want are bins of equal size, regardless of where they are on the globe, regardless of their resolution.

dggridR solves this problem.

dggridR builds discrete global grids which partition the surface of the Earth into hexagonal, triangular, or diamond cells, all of which have the same size. (There are some minor caveats which are detailed in the vignettes.)

(Naturally, you can use much smaller cells than those shown in the image above.)

This package includes everything you need to make spatial binning great again.

Many details and examples are included in the vignette.

dggridR is available from CRAN via:

install.packages('dggridR')

If you want your code to be as up-to-date as possible, you can install it using:

library(devtools) #Use `install.packages('devtools')` if need be
install_github('r-barnes/dggridR', vignette=TRUE)

Okay.

Your analysis could be as easy as this:

library(dggridR)
library(dplyr)
dggs          <- dgconstruct(spacing=1000, metric=FALSE, resround='down')
 
#Load included test data set
data(dgquakes)
 
#Get the corresponding grid cells for each earthquake epicenter (lat-long pair)
dgquakes$cell <- dgtransform(dggs,dgquakes$lat,dgquakes$lon)
 
#Get the number of earthquakes in each equally-sized cell
quakecounts   <- dgquakes %>% group_by(cell) %>% summarise(count=n())

In R, typing

vignette('dggridR')

will bring up many examples.

Many different grid resolutions are available for many different grids. The following chart shows the number of cells, their area, and statistics regarding the spacing of their center nodes for the ISEA3H grid type.

ResNumber of CellsCell Area (km^2)MinMaxMeanStd
13217,002,187.390804,156.180004,649.100004,320.49000233.01400
2925,667,395.796932,324.810002,692.720002,539.69000139.33400
32721,889,131.932311,363.560001,652.270001,480.0200089.39030
4812629,710.64410756.96100914.27200855.4190052.14810
52,432209,903.54803453.74800559.23900494.9590029.81910
67,29269,967.84934248.80400310.69300285.6520017.84470
721,87223,322.61645151.22100187.55000165.058009.98178
865,6127,774.2054882.31100104.4700095.263606.00035
9196,8322,591.4018350.4060063.0097055.022603.33072
10590,492863.8006127.3323035.0197031.759602.00618
111,771,472287.9335416.8019021.0902018.341001.11045
125,314,41295.977859.0936811.7061010.587100.66942
1315,943,23231.992625.600657.044626.113670.37016
1447,829,69210.664213.028473.907423.529110.22322
15143,489,0723.554731.866882.350582.037890.12339
16430,467,2121.184911.009041.303351.176380.07442
171,291,401,6320.394970.622290.783910.679300.04113
183,874,204,8920.131660.336280.434590.392130.02481
1911,622,614,6720.043890.207430.261370.226430.01371
2034,867,844,0120.014630.112080.144890.130710.00827

The code in the 'src' directory is based off of DGGRIDv6.2b by Kevin Sahr.

However, Richard Barnes has made some significant alterations. These include:

  • Replacement of gpclib with clipper, thus making DGGRID into FLOSS software available for both commerical and non-commerical use without restriction
  • Restructuring and simplifying all of the makefiles to enable compilation in R
  • Direct inclusion of the shapelib library
  • Addition of the SEQTOPOLY option under the GENERATE_GRID faculty
  • Alterations that enable the code to be compiled under GCC6
  • Alterations that make the code ISO C conformant
  • Alterations to resolve -pedantic and -Wall warnings

The package relies on several libraries, as noted in the Licensing section below.

This package uses the following libraries:

  • clipper: The clipper library has been released under the Boostv1 license by Angus Johnson

  • dggrid: Kevin Sahr has released dggrid as a "public domain software program"

  • proj4lib: Gerald Evenden has released this code into the public domain. More recent versions of the library, not used here, are under an MIT-style license.

  • shapelib: Frank Warmerdam has released shapelib under an MIT-style license. There is also an LGPL licensing option which I have chosen not to use.

This package, and all code and documentation not otherwise mentioned above (essentially anything outside the src/ directory of this package) are released under the MIT (Expat) license, as stated in the LICENSE file. The LICENCE file exists for use with CRAN.

This package should operate in the manner described here, in the package's main documentation, and in Kevin Sahr's dggrid documentation. Unfortunately, none of us are paid enough to make absolutely, doggone certain that that's the case. That said, if you find bugs or are seeking enhancements, we want to hear about them.

Please cite this package as:

News

dggridR v0.1.11 (Release date: 2016-09-18)

Changes:

  • Fixes a long double output formatting issue that gives bad results when
    code is compiled using MingW on certain Windows systems.

  • Adds a debugging capability to the R code to make it easier to get diagnostics from users.

dggridR v0.1.10 (Release date: 2016-08-16)

Changes:

  • Many conversions from printf and sscanf in hopes of improving oldrel-windows functionality

dggridR v0.1.9 (Release date: 2016-08-14)

Changes:

  • Fix bugs preventing the -4- grids from constructing properly (e.g. ISEA4H)

dggridR v0.1.8 (Release date: 2016-07-25)

Changes:

  • Fix bug preventing compilation in clang++-3.9

dggridR v0.1.7 (Release date: 2016-07-21)

Changes:

  • Numerous changes to C++11 in hopes of extending compatibility

dggridR v0.1.6 (Release date: 2016-07-20)

Changes:

  • Numerous changes in an attempt to extend compatibility

dggridR v0.1.5 (Release date: 2016-07-19)

Changes:

  • Another attempt at getting licensing right.

dggridR v0.1.4 (Release date: 2016-07-19)

Changes:

  • Changes to licensing and readme notes in another guess-and-check attempt to satisfy the folks at CRAN.

dggridR v0.1.3 (Release date: 2016-07-15)

Changes:

  • Clarified license info ... again

dggridR v0.1.2 (Release date: 2016-07-15)

Changes:

  • Resolved a number of pedantic warnings raised by the compiler.
  • Clarified license info

dggridR v0.1.1 (Release date: 2016-07-14)

Changes:

  • Added dgshptogrid(): Useful for making grids which cover shapefile-specified polygons

dggridR v0.1.0 (Release date: 2016-07-14)

Changes:

  • Using clipper instead of gpclib: this means everything is FLOSS now.

dggridR v0.0.2 (Release date: 2016-07-13)

Changes:

  • Added getmaxcell(): Useful for obtaining random grid cells
  • Made dgverify() public: Aids in debugging, possibly useful for users
  • Added wrapcells argmuent to grid generation functions: makes plotting easier
  • Added more examples
  • Added savegrid argument to make it easier to output grids for other purposes

dggridR v0.0.1 (Release date: 2016-07-09)

First official release

Changes:

  • Everything

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("dggridR")

1.0.1 by Richard Barnes, a month ago


https://github.com/r-barnes/dggridR/


Report a bug at https://github.com/r-barnes/dggridR/


Browse source code at https://github.com/cran/dggridR


Authors: Richard Barnes [aut, cre], Kevin Sahr [ctb], Gerald Evenden [ctb], Angus Johnson [ctb], Frank Warmerdam [ctb]


Documentation:   PDF Manual  


Task views: Analysis of Spatial Data


MIT + file LICENCE license


Depends on rgdal, ggplot2, dplyr

Suggests knitr, rmarkdown, maps, mapproj, R.rsp, testthat

System requirements: C++11


See at CRAN