Help for package geohashTools (original) (raw)
| Version: | 0.3.3 |
|---|---|
| Title: | Tools for Working with Geohashes |
| Maintainer: | Michael Chirico MichaelChirico4@gmail.com |
| Depends: | R (≥ 3.0.0) |
| Description: | Tools for working with Gustavo Niemeyer's geohash coordinate system, including API for interacting with other common R GIS libraries. |
| URL: | https://github.com/MichaelChirico/geohashTools |
| License: | MPL-2.0 | file LICENSE |
| Imports: | methods |
| Suggests: | sf, sp, testthat (≥ 3.0.0), knitr, rmarkdown, ggplot2 |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.2.3 |
| NeedsCompilation: | yes |
| Packaged: | 2023-10-21 19:43:30 UTC; michael |
| Author: | Michael Chirico [aut, cre], Dmitry Shkolnik [ctb] |
| Repository: | CRAN |
| Date/Publication: | 2023-10-21 20:10:02 UTC |
Geohash decoding
Description
Convert geohash-encoded strings into latitude/longitude coordinates
Usage
gh_decode(geohashes, include_delta = FALSE, coord_loc = 'c')
Arguments
| geohashes | character or factor vector or of input geohashes. There's no need for all inputs to be of the same precision. |
|---|---|
| include_delta | logical; should the cell half-width delta be included in the output? |
| coord_loc | character specifying where in the cell points should be mapped to; cell centroid is mapped by default; case-insensitive. See Details. |
Details
coord_loc can be the cell's center ('c' or 'centroid'), or it can be any of the 8 corners (e.g. 's'/'south' for the midpoint of the southern boundary of the cell, or 'ne'/'northeast' for the upper-right corner.
For factor input, decoding will be done on the levels for efficiency.
Value
list with the following entries:
| latitude | numeric vector of latitudes (y-coordinates) corresponding to the input geohashes, with within-cell position dictated by coord_loc |
|---|---|
| longitude | numeric vector of longitudes (x-coordinates) corresponding to the input geohashes, with within-cell position dictated by coord_loc |
| delta_latitude | numeric vector of cell half-widths in the y direction (only included if include_delta is TRUE |
| delta_longitude | numeric vector of cell half-widths in the x direction (only included if include_delta is TRUE |
Author(s)
Michael Chirico
References
http://geohash.org/ ( Gustavo Niemeyer's original geohash service )
Examples
# Riddle me this
gh_decode('stq4s8c')
# Cell half-widths might be convenient to include for downstream analysis
gh_decode('tjmd79', include_delta = TRUE)
Geohash encoding
Description
Convert latitude/longitude coordinates into geohash-encoded strings
Usage
gh_encode(latitude, longitude, precision = 6L)
Arguments
| latitude | numeric vector of input latitude (y) coordinates. Must be in [-90, 90). |
|---|---|
| longitude | numeric vector of input longitude (x) coordinates. Should be in [-180, 180). |
| precision | Positive integer scalar controlling the 'zoom level' – how many characters should be used in the output. |
Details
precision is limited to at most 28. This level of precision encodes locations on the globe at a nanometer scale and is already more than enough for basically all applications.
Longitudes outside [-180, 180) will be wrapped appropriately to the standard longitude grid.
Value
character vector of geohashes corresponding to the input. NA in gives NA out.
Author(s)
Michael Chirico
References
http://geohash.org/ ( Gustavo Niemeyer's original geohash service )
Examples
# scalar input is treated as a vector
gh_encode(2.345, 6.789)
# geohashes are left-closed, right-open, so boundary coordinates are
# associated to the east and/or north
gh_encode(0, 0)
Geohash neighborhoods
Description
Return the geohashes adjacent to input geohashes
Usage
gh_neighbors(geohashes, self = TRUE)
gh_neighbours(geohashes, self = TRUE)
Arguments
| geohashes | character vector of input geohashes. There's no need for all inputs to be of the same precision. |
|---|---|
| self | Should the input also be returned as a list element? Convenient for one-line usage / piping |
Details
North/south-pole adjacent geohashes are missing three of their neighbors; these will be returned as NA_character_.
Value
list with character vector entries in the direction relative to the input geohashes indicated by their name (e.g. value$south gives all of the southern neighbors of the input geohashes).
The order is self (if self = TRUE), southwest, south, southeast, west, east, northwest, north, northeast (reflecting an easterly, then northerly traversal of the neighborhod).
Author(s)
Michael Chirico
References
http://geohash.org/ ( Gustavo Niemeyer's original geohash service )
Examples
gh_neighbors('d7q8u4')
Description
These functions smooth the gateway between working with geohashes and geospatial information built for the major geospatial packages in R, [sp](../../sp/refman/sp.html#topic+sp) and [sf](../../sf/refman/sf.html#topic+sf).
Usage
gh_to_sp(geohashes)
gh_to_spdf(...)
gh_to_sf(...)
gh_covering(SP, precision = 6L, minimal = FALSE)
## Default S3 method:
gh_to_spdf(geohashes, ...)
## S3 method for class 'data.frame'
gh_to_spdf(gh_df, gh_col = 'gh', ...)
Arguments
| geohashes | character vector of geohashes to be converted to polygons. |
|---|---|
| ... | Arguments for subsequent methods. |
| SP | A Spatial object (requires bbox and proj4string methods, and over if minimal is TRUE) |
| precision | integer specifying the precision of geohashes to use, same as gh_encode |
| minimal | logical; if FALSE, the output will have all geohashes in the bounding box of SP; if TRUE, any geohashes not intersecting SP will be removed. |
| gh_df | data.frame which 1) contains a column of geohashes to be converted to polygons and 2) will serve as the data slot of the resultant SpatialPolygonsDataFrame object. |
| gh_col | character column name saying where the geohashes are stored in gh_df. |
Details
gh_to_sp relies on the [gh_decode](#topic+gh%5Fdecode) function. Note in particular that this function accepts any length of geohash (geohash-6, geohash-4, etc.) and is agnostic to potential overlap, though duplicates will be caught and excluded.
gh_to_spdf.data.frame will use match.ID = FALSE in the call to SpatialPolygonsDataFrame. Please file an issue if you'd like this to be more flexible.
gh_to_sf is just a wrapper of [st_as_sf](../../sf/refman/sf.html#topic+st%5Fas%5Fsf) around gh_to_spdf; as such it requires both sp and sf packages to work.
Value
For gh_to_sp, a [SpatialPolygons](../../sp/refman/sp.html#topic+SpatialPolygons) object.
For gh_to_spdf, a [SpatialPolygonsDataFrame](../../sp/refman/sp.html#topic+SpatialPolygonsDataFrame) object.
For gh_to_sf, a [sf](../../sf/refman/sf.html#topic+sf) object.
Examples
# get the neighborhood of this geohash in downtown Apia as an sp object
downtown = '2jtc5x'
apia_nbhd = unlist(gh_neighbors(downtown))
apia_sp = gh_to_sp(apia_nbhd)
# all geohashes covering a random sampling within Apia:
apia_covering = gh_covering(smp <- sp::spsample(apia_sp, 10L, 'random'))
apia_sf = gh_to_sf(apia_nbhd)
Geohash utilities
Description
Various common functions that arise when working often with geohashes
Usage
gh_delta(precision)
Arguments
| precision | integer precision level desired. |
|---|
Value
Length-2 numeric vector; the first element is the latitude (y-coordinate) half-width at the input precision, the second element is the longitude (x-coordinate).
Note
Caveat coder: not much is done in the way of consistency checking since this is a convenience function. So e.g. real-valued "precision"s will give results.
Author(s)
Michael Chirico
References
http://geohash.org/ ( Gustavo Niemeyer's original geohash service )
Examples
gh_delta(6)