Learn R Programming

dggridR: Discrete Global Grids for R

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.

Installation

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
devtools::install_github("r-barnes/dggridR", vignette=TRUE)

Show me some code

Okay.

Your analysis could be as easy as this:

library(dggridR)
library(collapse)

#Construct a global grid with cells approximately 1000 miles across
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 <- dgGEO_to_SEQNUM(dggs, dgquakes$lon, dgquakes$lat)$seqnum

#Get the number of earthquakes in each equally-sized cell
quakecounts   <- dgquakes %>% fcount(cell)

Show me more examples!

In R, typing

vignette('dggridR')

will bring up many examples.

But I want higher resolution grids than that

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

Credits

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 commercial and non-commercial 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.

Licensing

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.

Disclaimer

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.

Citing this Package

Please cite this package as:

Richard Barnes and Kevin Sahr (2017). dggridR: Discrete Global Grids for R. R package version 2.0.4. "https://github.com/r-barnes/dggridR/" doi:10.5281/zenodo.1322866

Copy Link

Version

Install

install.packages('dggridR')

Monthly Downloads

415

Version

3.1.0

License

AGPL (>= 3)

Issues

Pull Requests

Stars

Forks

Last Published

July 26th, 2024

Functions in dggridR (3.1.0)

dgQ2DD_to_SEQNUM

Convert from Q2DD to SEQNUM
dgverify

Verify that a dggs object has appropriate values
dgSEQNUM_to_PLANE

Convert from SEQNUM to PLANE
dgshptogrid

Return boundary coordinates for cells intersecting a shapefile
dgsetres

Set the resolution of a dggs object
dgSEQNUM_to_GEO

Convert from SEQNUM to GEO
dg_closest_res_to_cls

Determine an appropriate grid resolution based on a desired characteristic length scale of the cells.
dg_closest_res_to_spacing

Determine grid resolution from desired spacing.
dgQ2DI_to_Q2DD

Convert from Q2DI to Q2DD
dggetres

Get table of grid resolution information
dginfo

Print info about a dggs object to the screen
dgQ2DI_to_PROJTRI

Convert from Q2DI to PROJTRI
dg_process_polydata

Load a KML file
dg_env

Control global aspects of the dggridR package
dg_closest_res

Determine an appropriate grid resolution based on input data.
dgQ2DI_to_SEQNUM

Convert from Q2DI to SEQNUM
dgQ2DI_to_Q2DI

Convert from Q2DI to Q2DI
dg_closest_res_to_area

Determine resolution based on desired area
dgQ2DD_to_GEO

Convert from Q2DD to GEO
dg_shpfname_south_africa

National border of South Africa
dgcellstogrid

Return boundary coordinates for specified cells
dgrectgrid

Return the coordinates constituting the boundary of cells within a specified region
dgsavegrid

Saves a generated grid to a shapefile
dgQ2DD_to_PLANE

Convert from Q2DD to PLANE
dgearthgrid

Return the coordinates constituting the boundary of cells for the entire Earth
dgSEQNUM_to_Q2DI

Convert from SEQNUM to Q2DI
dgquakes

All earthquakes with magnitude >=3.0 earthquakes for 2015
dgconstruct

Construct a discrete global grid system (dggs) object
dgSEQNUM_to_SEQNUM

Convert from SEQNUM to SEQNUM
dgmaxcell

Get largest cell id for a dggs
dgPROJTRI_to_PLANE

Convert from PROJTRI to PLANE
dgGEO_to_SEQNUM

Convert from GEO to SEQNUM
dgPROJTRI_to_PROJTRI

Convert from PROJTRI to PROJTRI
dgGEO_to_PLANE

Convert from GEO to PLANE
dgPROJTRI_to_GEO

Convert from PROJTRI to GEO
dgGEO_to_GEO

Convert from GEO to GEO
dgGEO_to_Q2DI

Convert from GEO to Q2DI
dgGEO_to_Q2DD

Convert from GEO to Q2DD
dgPROJTRI_to_Q2DD

Convert from PROJTRI to Q2DD
dgGEO_to_PROJTRI

Convert from GEO to PROJTRI
dgQ2DD_to_Q2DI

Convert from Q2DD to Q2DI
dgSEQNUM_to_PROJTRI

Convert from SEQNUM to PROJTRI
dgSEQNUM_to_Q2DD

Convert from SEQNUM to Q2DD
dgPROJTRI_to_Q2DI

Convert from PROJTRI to Q2DI
dgPROJTRI_to_SEQNUM

Convert from PROJTRI to SEQNUM
dgQ2DI_to_GEO

Convert from Q2DI to GEO
dgQ2DD_to_PROJTRI

Convert from Q2DD to PROJTRI
dgQ2DI_to_PLANE

Convert from Q2DI to PLANE
dgQ2DD_to_Q2DD

Convert from Q2DD to Q2DD