Package dggridr. August 29, 2016

Transcription

1 Type Package Title Discrete Global Grids for R Version Date Package dggridr August 29, 2016 Author Richard Barnes [aut, cre], Kevin Sahr [ctb], Gerald Evenden [ctb], Angus Johnson [ctb], Frank Warmerdam [ctb] Maintainer Richard Barnes <[email protected]> NeedsCompilation yes Depends R (>= 3.0.0), rgdal (>= 1.1), ggplot2 (>= 2.1), dplyr (>= 0.4) Suggests knitr, rmarkdown, maps, mapproj, R.rsp, testthat License MIT + file LICENCE 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. URL BugReports RoxygenNote VignetteBuilder knitr, R.rsp SystemRequirements C++11 Repository CRAN Date/Publication :50:26 R topics documented: dgcellstogrid dgconstruct

2 2 dgcellstogrid dgearthgrid dggetres dginfo dgmaxcell dgquakes dgrectgrid dgrun dgsetres dgshptogrid dgtransform dgverify dg_closest_res dg_closest_res_to_area dg_closest_res_to_cls dg_closest_res_to_spacing dg_exe_path dg_process_kml dg_shpfname_south_africa Index 17 dgcellstogrid Return boundary coordinates for specified cells Returns the coordinates constituting the boundary of a specified set of cells. Duplicates are eliminated to reduce processing and storage requirements. dgcellstogrid(, cells, frame = TRUE, wrapcells = TRUE, savegrid = FALSE) cells frame wrapcells savegrid A object from dgconstruct() The cells to get the boundaries of If TRUE, return a data frame suitable for ggplot plotting. If FALSE, return an OGR poly object Cells which cross -180/180 degrees can present difficulties for plotting. Setting this TRUE will result in cells with components in both hemispheres to be mapped entirely to positive degrees (the Eastern hemisphere). As a result, such cells will have components in the range [180,360). Only used when frame=true. If savegrid is true then a KML representation of the grid is produced and the filename returned. No other manipulations are done. Setting this true overrides all other commands.

3 dgconstruct 3 Returns a data frame or OGR poly object, as specified by frame. If savegrid=true, returns a filename. data(dgquakes) #Construct a grid with cells about ~1000 miles wide <- dgconstruct(spacing=1000,metric=false) dgquakes$cell <- dgtransform(,dgquakes$lat,dgquakes$lon) #Get grid cells for the earthquakes identified grid <- dgcellstogrid(, dgquakes$cell, frame=true) dgconstruct Construct a discrete global grid system () object Construct a discrete global grid system () object dgconstruct(type = "ISEA3H", res = NA, precision = 7, area = NA, spacing = NA, cls = NA, resround = "nearest", metric = TRUE, show_info = TRUE) type res Type of grid to use. Options are: ISEA3H, ISEA4H, ISEA43H, ISEA4T, ISEA4D, FULLER3H, FULLER4H, FULLER43H, FULLER4T, and FULLER4D. Default: ISEA3H Resolution. Must be in the range [0,30]. Larger values represent finer resolutions. Appropriate resolutions can be found with dg_closest_res_to_area(), dg_closest_res_to_spacing(), and dg_closest_res_to_cls(). Default is 9, which corresponds to a cell area of ~2600 sq km and a cell spacing of ~50 km. Only one of res, area, length, or cls should be used. precision Round output to this number of decimal places. Must be in the range [0,30]. Default: 7. area spacing The desired area of the grid s cells. Only one of res, area, length, or cls should be used. The desired spacing between the center of adjacent cells. Only one of res, area, length, or cls should be used.

4 4 dgearthgrid cls resround metric show_info The desired CLS of the cells. Only one of res, area, length, or cls should be used. What direction to search in. Must be nearest, up, or down. Whether input and output should be in metric (TRUE) or imperial (FALSE) Print the area, spacing, and CLS of the chosen resolution. Returns a object which can be passed to other dggridr functions <- dgconstruct(res=20) <- dgconstruct(area=5,metric=false) dgearthgrid Return the coordinates constituting the boundary of cells for the entire Earth Note: If you have a high-resolution grid this may take a loooooong time to execute. dgearthgrid(, frame = TRUE, wrapcells = TRUE, savegrid = FALSE) frame wrapcells savegrid A object from dgconstruct() If TRUE, return a data frame suitable for ggplot plotting. If FALSE, return an OGR poly object Cells which cross -180/180 degrees can present difficulties for plotting. Setting this TRUE will result in cells with components in both hemispheres to be mapped entirely to positive degrees (the Eastern hemisphere). As a result, such cells will have components in the range [180,360). Only used when frame=true. If savegrid is true then a KML representation of the grid is produced and the filename returned. No other manipulations are done. Setting this true overrides all other arguments. Returns a data frame or OGR poly object, as specified by frame. If savegrid=true, returns a filename.

5 dggetres 5 <- dgconstruct(res=20) res <- dg_closest_res_to_spacing(,spacing=1000,round='down',metric=false) <- dgsetres(,res) gridfilename <- dgearthgrid(,savegrid=true) #Save directly to a file dggetres Get table of grid resolution information Gets a grid s resolution and cell property info as a data frame. dggetres() A object from dgconstruct() A data frame containing the resolution levels, number of cells, area of those cells, intercell spacing, and characteristic length scale of the cells. All values are in kilometres. <- dgconstruct(res=20) dggetres() dginfo Print a buncha info about a object to the screen objects have many settings. This returns all of them, along with info about the grid being specified. dginfo()

6 6 dgmaxcell A object from dgconstruct() No return. All info is printed to the screen. <- dgconstruct(res=20) dginfo() dgmaxcell Get largest cell id for a Cells are labeled 1-N. This function returns N. This is useful if you want to choose cells from the randomly. dgmaxcell(, res = NA) res A object from dgconstruct() If NA, use the resolution specified by the. Otherwise, override the resolution. The maximum cell id. #Choose a set of cells randomly distributed over the Earth <- dgconstruct(spacing=1000, metric=false, resround='down') N <- 100 #Number of cells maxcell <- dgmaxcell() #Get maximum cell id cells <- sample(1:maxcell, N, replace=false) #Choose random cells grid <- dgcellstogrid(,cells,frame=true,wrapcells=true) #Get grid

7 dgquakes 7 dgquakes All earthquakes with magnitude >=3.0 earthquakes for 2015 A data frame with observations on the following 4 variables. time Time of the quake. Example: T23:39:28.940Z lat Latitude of the epicenter. Example: lon Longitude of the epicenter. Example: mag Magnitude of the quake. Example: 3.2 data(dgquakes) Format data frame Source The USGS Earthquake Hazards Program ( dgrectgrid Return the coordinates constituting the boundary of cells within a specified region Note: This may generate odd results for very large rectangles, because putting rectangles on spheres is weird... as you should know, if you re using this package. dgrectgrid(, minlat = -1, minlon = -1, maxlat = -1, maxlon = -1, frame = TRUE, wrapcells = TRUE, savegrid = FALSE)

8 8 dgrun minlat minlon maxlat maxlon frame wrapcells savegrid A object from dgconstruct() Minimum latitude of region of interest Minimum longitude of region of interest Maximum latitude of region of interest Maximum longitude of region of interest If TRUE, return a data frame suitable for ggplot plotting. If FALSE, return an OGR poly object Cells which cross -180/180 degrees can present difficulties for plotting. Setting this TRUE will result in cells with components in both hemispheres to be mapped entirely to positive degrees (the Eastern hemisphere). As a result, such cells will have components in the range [180,360). Only used when frame=true. If savegrid is true then a KML representation of the grid is produced and the filename returned. No other manipulations are done. Setting this true overrides all other arguments. Returns a data frame or OGR poly object, as specified by frame. If savegrid=true, returns a filename. <- dgconstruct(spacing=1000,metric=false,resround='down') #Get grid cells for the conterminous United States grid <- dgrectgrid(, minlat= , minlon= , maxlat= , maxlon= , frame=true) dgrun A generic function for running dggrid and returning values from it A discrete global grid maps lat-long points to particular cells. These cells are uniquely numbered, for a given resolution, from 1 to some maximum number. Cell numbers may be reused from one resolution to the next. dgrun(, clean = TRUE, check = TRUE, has_output_file = TRUE)

9 dgsetres 9 clean check A object from dgconstruct() If TRUE, delete the temporary files used/produced by dggrid. TODO If TRUE, raise a stop signal if dggrid doesn t run successfully. has_output_file If TRUE, look for output file. If FALSE, capture and return stdout and stderr. If has_output_file is TRUE, a data frame is returned. The calling function is responsible for understanding this frame. If has_output_file is FALSE, the stdout and stderr of dggrid are captured and returned as a character vector. dgsetres Set the resolution of a object Set the resolution of a object dgsetres(, res) res A object from dgconstruct(). Resolution. Must be in the range [0,30]. Larger values represent finer resolutions. Appropriate resolutions can be found with dg_closest_res_to_area(), dg_closest_res_to_spacing(), and dg_closest_res_to_cls(). Default is 9, which corresponds to a cell area of ~2600 sq km and a cell spacing of ~50 km. Default: 9. Returns a object which can be passed to other dggridr functions <- dgconstruct(res=20) <- dgsetres(,10)

10 10 dgshptogrid dgshptogrid Return boundary coordinates for cells intersecting a shapefile Returns the coordinates constituting the boundary of a set of cells which intersect or are contained by a polygon (or polygons) specified in a shapefile. Note that grid cells are also generated for holes in the shapefile s polygon(s). Note that coordinates in the shapefile must be rounded to check polygon intersections. Currently this round preserves eight decimal digits of precision. The eighth decimal place is worth up to 1.1 mm of precision: this is good for charting the motions of tectonic plates and the movements of volcanoes. Permanent, corrected, constantly-running GPS base stations might be able to achieve this level of accuracy. In other words: you should be just fine with this level of precision. dgshptogrid(, shpfname, frame = TRUE, wrapcells = TRUE, savegrid = FALSE) shpfname frame wrapcells savegrid A object from dgconstruct() File name of the shapefile. Filename should end with.shp If TRUE, return a data frame suitable for ggplot plotting. If FALSE, return an OGR poly object Cells which cross -180/180 degrees can present difficulties for plotting. Setting this TRUE will result in cells with components in both hemispheres to be mapped entirely to positive degrees (the Eastern hemisphere). As a result, such cells will have components in the range [180,360). Only used when frame=true. If savegrid is true then a KML representation of the grid is produced and the filename returned. No other manipulations are done. Setting this true overrides all other commands. Returns a data frame or OGR poly object, as specified by frame. If savegrid=true, returns a filename. <- dgconstruct(spacing=25, metric=false, resround='nearest') south_africa_grid <- dgshptogrid(,dg_shpfname_south_africa)

11 dgtransform 11 dgtransform Converts lat-long pairs into discrete global grid cell numbers A discrete global grid maps lat-long points to particular cells. These cells are uniquely numbered, for a given resolution, from 1 to some maximum number. Cell numbers may be reused from one resolution to the next. dgtransform(, lat, lon) lat lon A object from dgconstruct(). A vector of latitudes. Same length at the longtiudes A vector of longitudes. Same length as the latitudes. A vector of the same length as latitudes and longitudes containing the cell id numbers of the points cells in the discrete grid. data(dgquakes) #Construct a grid with cells about ~1000 miles wide <- dgconstruct(spacing=1000,metric=false) dgquakes$cell <- dgtransform(,dgquakes$lat,dgquakes$lon) dgverify Verify that a object has appropriate values Verify that a object has appropriate values dgverify()

12 12 dg_closest_res The object to be verified The function has no return value. A stop signal is raised if the object is misspecified <- dgconstruct(res=20) dgverify() dg_closest_res Determine an appropriate grid resolution based on input data. This is a generic function that is used to determine an appropriate resolution given an area, cell spacing, or correlated length scale. It does so by extracting the appropriate length/area column and searching it for a value close to the input. dg_closest_res(, col, val, round = "nearest", show_info = TRUE, metric = TRUE) col val round show_info metric A object from dgconstruct() Column in which to search for a close value. Should be: AreaKm, SpacingKm, or CLSKm. The value to search for What direction to search in. Must be nearest, up, or down. Print the area, spacing, and CLS of the chosen resolution. Whether input and output should be in metric (TRUE) or imperial (FALSE) A number representing the grid resolution

13 dg_closest_res_to_area 13 ## Not run: <- dgconstruct(res=20) res <- dg_closest_res(,'areakm',1) <- dgsetres(,res) ## End(Not run) dg_closest_res_to_area Determine resolution based on desired area Determine an appropriate grid resolution based on a desired cell area. dg_closest_res_to_area(, area, round = "nearest", show_info = TRUE, metric = TRUE) area round show_info metric A object from dgconstruct() The desired area of the grid s cells What direction to search in. Must be nearest, up, or down. Print the area, spacing, and CLS of the chosen resolution. Whether input and output should be in metric (TRUE) or imperial (FALSE) A number representing the grid resolution <- dgconstruct(res=20) res <- dg_closest_res_to_area(,1) <- dgsetres(,res)

14 14 dg_closest_res_to_spacing dg_closest_res_to_cls Determine an appropriate grid resolution based on a desired characteristic length scale of the cells. The characteristic length scale (CLS) is the diameter of a spherical cap of the same area as a cell of the specified resolution. dg_closest_res_to_cls(, cls, round = "nearest", show_info = TRUE, metric = TRUE) cls round show_info metric A object from dgconstruct() The desired CLS of the cells. What direction to search in. Must be nearest, up, or down. Print the area, spacing, and CLS of the chosen resolution. Whether input and output should be in metric (TRUE) or imperial (FALSE) A number representing the grid resolution <- dgconstruct(res=20) res <- dg_closest_res_to_cls(,1) <- dgsetres(,res) dg_closest_res_to_spacing Determine grid resolution from desired spacing. Determine an appropriate grid resolution based on a desired spacing between the center of adjacent cells.

15 dg_exe_path 15 dg_closest_res_to_spacing(, spacing, round = "nearest", show_info = TRUE, metric = TRUE) spacing round show_info metric A object from dgconstruct() The desired spacing between the center of adjacent cells What direction to search in. Must be nearest, up, or down. Print the area, spacing, and CLS of the chosen resolution. Whether input and output should be in metric (TRUE) or imperial (FALSE) A number representing the grid resolution <- dgconstruct(res=20) res <- dg_closest_res_to_spacing(,1) <- dgsetres(,res) dg_exe_path Get path to dggrid executable Returns a path to the dggrid executable. Used for running stuff. dg_exe_path() A string representing the path to the dggrid executable.

16 16 dg_shpfname_south_africa dg_process_kml Load a KML file Clean up and/or convert a KML grid cell boundary file dg_process_kml(kmlfile, frame, wrapcells) kmlfile frame wrapcells A KML file generated by dgrectgrid() or dgearthgrid() If TRUE, return a data frame suitable for ggplot plotting. If FALSE, return an OGR poly object Cells which cross -180/180 degrees can present difficulties for plotting. Setting this TRUE will result in cells with components in both hemispheres to be mapped entirely to positive degrees (the Eastern hemisphere). As a result, such cells will have components in the range [180,360). Only used when frame=true. Returns a data frame or OGR poly object, as specified by frame dg_shpfname_south_africa National border of South Africa This variable points to a shapefile containing the national border of South Africa dg_shpfname_south_africa Format An object of class character of length 1. A filename of a shapefile containing the national border of South Africa

17 Index Topic datasets dg_shpfname_south_africa, 16 dgquakes, 7 dg_closest_res, 12 dg_closest_res_to_area, 13 dg_closest_res_to_cls, 14 dg_closest_res_to_spacing, 14 dg_exe_path, 15 dg_process_kml, 16 dg_shpfname_south_africa, 16 dgcellstogrid, 2 dgconstruct, 3 dgearthgrid, 4 dggetres, 5 dginfo, 5 dgmaxcell, 6 dgquakes, 7 dgrectgrid, 7 dgrun, 8 dgsetres, 9 dgshptogrid, 10 dgtransform, 11 dgverify, 11 17