| Title: | Scale Bar, North Arrow, and Pretty Margins in R |
|---|---|
| Description: | Automates the process of creating a scale bar and north arrow in any package that uses base graphics to plot in R. Bounding box tools help find and manipulate extents. Finally, there is a function to automate the process of setting margins, plotting the map, scale bar, and north arrow, and resetting graphic parameters upon completion. |
| Authors: | Dewey Dunnington <[email protected]> |
| Maintainer: | Dewey Dunnington <[email protected]> |
| License: | GPL-2 |
| Version: | 0.2.5 |
| Built: | 2024-11-06 02:55:28 UTC |
| Source: | https://github.com/paleolimbot/prettymapr |
Plot a north arrow (pointing directly "up") positioned based on current plot extents.
addnortharrow( pos = "topright", padin = c(0.15, 0.15), scale = 1, lwd = 1, border = "black", cols = c("white", "black"), text.col = "black" )addnortharrow( pos = "topright", padin = c(0.15, 0.15), scale = 1, lwd = 1, border = "black", cols = c("white", "black"), text.col = "black" )
pos |
Where to align the north arrow. One of "bottomleft", "bottomright", "topleft", or "topright". |
padin |
A vector of length 2 determining the distance in inches between the scalebar and the edge of the plottable area. |
scale |
Scale the default north arrow to make it bigger or smaller |
lwd |
The line width outlining the north arrow |
border |
The line color outlining the north arrow |
cols |
A vector of length 2 determining the two colors to be drawn for the north arrow |
text.col |
Color of the "N" |
plot(1:5, 1:5, asp=1) addnortharrow()plot(1:5, 1:5, asp=1) addnortharrow()
Automatically determines the geographical scale of the plot and draws a labelled scalebar.
addscalebar( plotunit = NULL, plotepsg = NULL, widthhint = 0.25, unitcategory = "metric", htin = 0.1, padin = c(0.15, 0.15), style = "bar", bar.cols = c("black", "white"), lwd = 1, linecol = "black", tick.cex = 0.7, labelpadin = 0.08, label.cex = 0.8, label.col = "black", pos = "bottomleft" )addscalebar( plotunit = NULL, plotepsg = NULL, widthhint = 0.25, unitcategory = "metric", htin = 0.1, padin = c(0.15, 0.15), style = "bar", bar.cols = c("black", "white"), lwd = 1, linecol = "black", tick.cex = 0.7, labelpadin = 0.08, label.cex = 0.8, label.col = "black", pos = "bottomleft" )
plotunit |
The unit which the current plot is plotted in, one of |
plotepsg |
The projection of the current plot. If extents are valid lat/lons, the projection is assumed to be lat/lon (EPSG:4326), or Spherical Mercator otherwise (EPSG:3857). This is done to work seamlessly with OpenStreetMap packages. |
widthhint |
The fraction of the plottable width which the scale bar should (mostly) occupy. |
unitcategory |
One of "metric" or "imperial" |
htin |
Height (in inches) of the desired scale bar |
padin |
A vector of length 2 determining the distance in inches between the scalebar and the edge of the plottable area. |
style |
One of "bar" or "ticks". |
bar.cols |
If |
lwd |
The line width to use when drawing the scalebar |
linecol |
The line color to use when drawing the scalebar |
tick.cex |
If |
labelpadin |
The distance between the end of the scalebar and the label (inches) |
label.cex |
The font size of the label |
label.col |
The color of the label |
pos |
Where to align the scalebar. One of "bottomleft", "bottomright", "topleft", or "topright". |
plot(1:5, 1:5, asp=1) addscalebar(plotunit="m")plot(1:5, 1:5, asp=1) addscalebar(plotunit="m")
Clears the local cache of downloaded files (by default, an environment in the package namespace). Clearing a directory cache will result in all files with the extention ".cached" being deleted from that directory.
clear_geocode_cache(cache = NA)clear_geocode_cache(cache = NA)
cache |
An environment, a directory name, or NA to clear the default internal cache |
clear_geocode_cache()clear_geocode_cache()
Geocode locations using the Google Web API, the PickPoint.io API, or the Data Science Toolkit API. For large requests you should really use your own API key if you are using the default (pickpoint). Note that the Google Terms seem to indicate that you cannot place locations obtained from their API on non-google maps. Locations are all geocoded with erorrs kept quiet, which may result in list output containing items with a $status element describing the error message, or data frame output containing a non-OK status in the status column.
geocode( location, output = c("data.frame", "list"), source = "default", messaging = NULL, limit = 1, key = NULL, quiet = TRUE, cache = NA, progress = c("time", "text", "none"), ... )geocode( location, output = c("data.frame", "list"), source = "default", messaging = NULL, limit = 1, key = NULL, quiet = TRUE, cache = NA, progress = c("time", "text", "none"), ... )
location |
A character vector (or an object that can be coerced to one) of locations to pass to the geocoding API. |
output |
One of |
source |
One of "default", "google", "pickpoint", or "dsk". If "default", the
function calls |
messaging |
|
limit |
The number of results to return per query. This refers to individual locations, for which ambiguous queries may return multiple results (e.g. Halifax, Nova Scotia; Halifax, United Kingdom, etc.). The default is 1. Pass 0 if no limit on queries is desired. |
key |
API key if |
quiet |
By default, error messages are suppressed, and are instead included in the output as objects with a $status describing the error (list output) or the appropriate value in the 'status' column (data frame output). |
cache |
The cache to use. Use NA for the internal cache (keeps first 1000 results), or a directory name (e.g. 'geo.cache'), which keeps an unlimited number of results. Use clear_geocode_cache to clear the cache. |
progress |
A plyr status bar, one of "time", "text", or "none". Passing quiet = FALSE will also disable the progress bar. |
... |
A number of key/value pairs to append to the URL, specifying
further options specific to each API. Google users may wish to provide
|
A list or data.frame; see documentation for
output argument.
# don't test to speed up checking time geocode("wolfville, ns") geocode("wolfville, ns", output="list") geocode("halifax", limit=0) geocode("Paddy's Pub Wolfville NS", source="google") geocode(c("Houston, TX", "San Antonio TX", "Cleavland OH"), source="google") #fails quietly geocode("don't even think about geocoding this") geocode("don't even think about geocoding this", output="list")# don't test to speed up checking time geocode("wolfville, ns") geocode("wolfville, ns", output="list") geocode("halifax", limit=0) geocode("Paddy's Pub Wolfville NS", source="google") geocode(c("Houston, TX", "San Antonio TX", "Cleavland OH"), source="google") #fails quietly geocode("don't even think about geocoding this") geocode("don't even think about geocoding this", output="list")
The geocode function can use google, pickpoint, or data science toolkit to turn human-readable names into coordinates. Use these methods to get/set the default source. These will need to be called once per namespace load.
get_default_geocoder() set_default_geocoder(geocoder)get_default_geocoder() set_default_geocoder(geocoder)
geocoder |
The new source to use. One of "pickpoint", "google", or "dsk". |
get_default_geocoder() set_default_geocoder("google") (set_default_geocoder(NULL))get_default_geocoder() set_default_geocoder("google") (set_default_geocoder(NULL))
Convencience method to create a bounding box like that returned by sp::bbox().
To generate a bounding box from lists of lat/lon values use sp::bbox(cbind(lons, lats)).
makebbox(n, e, s, w)makebbox(n, e, s, w)
n |
North bounding latitude |
e |
East bounding longitude |
s |
South bounding latitude |
w |
West bounding longitude |
A 2x2 matrix describing a bounding box like that returned by sp::bbox()
sp::bbox
makebbox(45.125, -64.25, 44.875, -64.75)makebbox(45.125, -64.25, 44.875, -64.75)
Create a single bounding box that encloses all of the bounding boxes.
mergebbox(...)mergebbox(...)
... |
An arbitrary number of bounding boxes as generated by |
A single bounding box that contains all of its arguments.
box1 <- makebbox(45, -64, 44, -65) box2 <- makebbox(45.5, -64.5, 44.5, -65.6) mergebbox(box1, box2)box1 <- makebbox(45, -64, 44, -65) box2 <- makebbox(45.5, -64.5, 44.5, -65.6) mergebbox(box1, box2)
Just in case anybody is hoping to draw a custom scalebar, this is the method used to plot it. If you don't know what this is, you should probably be using addscalebar.
plotscalebar( x, y, ht, params, style = "bar", adj = c(0, 0), tick.cex = 0.7, bar.cols = c("black", "white"), lwd = 1, linecol = "black" )plotscalebar( x, y, ht, params, style = "bar", adj = c(0, 0), tick.cex = 0.7, bar.cols = c("black", "white"), lwd = 1, linecol = "black" )
x |
The position (user) to draw the scale bar |
y |
The position (user) to draw the scale bar |
ht |
The height(in user coordinates) to draw the scale bar |
params |
Scalebar parameters as generated by scalebarparams |
style |
One of |
adj |
Where to align the scale bar relative to |
tick.cex |
If |
bar.cols |
A vector of color names to be repeated for a |
lwd |
Passed when drawing lines associated with the scalebar |
linecol |
Passed when drawing lines associated with the scalebar |
This function executes everything in plotexpression, then draws
north arrow and scale bar using addnortharrow and addscalebar.
Specify that plot is in a non lat/lon projection by passing scale.plotepsg=...
or plotunit="m".
prettymap( plotexpression, oma = c(0, 0, 0, 0), mai = c(0, 0, 0, 0), drawbox = FALSE, box.lwd = 1, drawscale = TRUE, scale.pos = "bottomleft", scale.htin = 0.1, scale.widthhint = 0.25, scale.unitcategory = "metric", scale.style = "bar", scale.bar.cols = c("black", "white"), scale.lwd = 1, scale.linecol = "black", scale.padin = c(0.15, 0.15), scale.labelpadin = 0.08, scale.label.cex = 0.8, scale.label.col = "black", scale.plotunit = NULL, scale.plotepsg = NULL, scale.tick.cex = 0.8, drawarrow = FALSE, arrow.pos = "topright", arrow.scale = 1, arrow.padin = c(0.15, 0.15), arrow.lwd = 1, arrow.cols = c("white", "black"), arrow.border = "black", arrow.text.col = "black", title = NULL, ... )prettymap( plotexpression, oma = c(0, 0, 0, 0), mai = c(0, 0, 0, 0), drawbox = FALSE, box.lwd = 1, drawscale = TRUE, scale.pos = "bottomleft", scale.htin = 0.1, scale.widthhint = 0.25, scale.unitcategory = "metric", scale.style = "bar", scale.bar.cols = c("black", "white"), scale.lwd = 1, scale.linecol = "black", scale.padin = c(0.15, 0.15), scale.labelpadin = 0.08, scale.label.cex = 0.8, scale.label.col = "black", scale.plotunit = NULL, scale.plotepsg = NULL, scale.tick.cex = 0.8, drawarrow = FALSE, arrow.pos = "topright", arrow.scale = 1, arrow.padin = c(0.15, 0.15), arrow.lwd = 1, arrow.cols = c("white", "black"), arrow.border = "black", arrow.text.col = "black", title = NULL, ... )
plotexpression |
An expression to plot the map, can be in brackets. e.g.
|
oma |
A vector of length 4 describing the outer margin area. See documentation
for |
mai |
A vector of length 4 describing the margin area in inches. See documentation
for |
drawbox |
|
box.lwd |
The line width of the box |
drawscale |
|
scale.pos |
Where to align the scalebar. One of "bottomleft", "bottomright", "topleft", or "topright". |
scale.htin |
Height (in inches) of the desired scale bar |
scale.widthhint |
The fraction of the plottable width which the scale bar should (mostly) occupy. |
scale.unitcategory |
One of "metric" or "imperial" |
scale.style |
One of "bar" or "ticks". |
scale.bar.cols |
If |
scale.lwd |
The line width to use when drawing the scalebar |
scale.linecol |
The line color to use when drawing the scalebar |
scale.padin |
A vector of length 2 determining the distance in inches between the scalebar and the edge of the plottable area. |
scale.labelpadin |
The distance between the end of the scalebar and the label (inches) |
scale.label.cex |
The font size of the label |
scale.label.col |
The color of the label |
scale.plotunit |
The unit which the current plot is plotted in, one of |
scale.plotepsg |
The projection of the current plot. If extents are valid lat/lons, the projection is assumed to be lat/lon (EPSG:4326), or Spherical Mercator otherwise (EPSG:3857). This is done to work seamlessly with OpenStreetMap packages. |
scale.tick.cex |
If |
drawarrow |
|
arrow.pos |
Where to align the north arrow. One of "bottomleft", "bottomright", "topleft", or "topright". |
arrow.scale |
Scale the default north arrow to make it bigger or smaller |
arrow.padin |
A vector of length 2 determining the distance in inches between the scalebar and the edge of the plottable area. |
arrow.lwd |
The line width outlining the north arrow |
arrow.cols |
A vector of length 2 determining the two colors to be drawn for the north arrow |
arrow.border |
The line color outlining the north arrow |
arrow.text.col |
Color of the "N" |
title |
Plot title, or |
... |
Further graphical parameters to set while executing plotting code |
prettymap(plot(1:5, 1:5, asp=1), scale.plotunit="cm", drawarrow=FALSE) #add a title prettymap(plot(1:5, 1:5, asp=1), title="My Plot")prettymap(plot(1:5, 1:5, asp=1), scale.plotunit="cm", drawarrow=FALSE) #add a title prettymap(plot(1:5, 1:5, asp=1), title="My Plot")
Get default scale bar parameters based on the current plot (i.e. par("usr")).
The algorithm attempts to detect the best equally divisable distance to use for the
scale bar, and returns a list object with attributes that allow any type of
scale bar to be drawn. The only way to manipulate the values chosen by the algorithm
is to change the widthhint argument. For generic XY plots, pass plotunit.
scalebarparams( plotunit = NULL, plotepsg = NULL, widthhint = 0.25, unitcategory = "metric", extents = graphics::par("usr") )scalebarparams( plotunit = NULL, plotepsg = NULL, widthhint = 0.25, unitcategory = "metric", extents = graphics::par("usr") )
plotunit |
The unit which the current plot is plotted in, one of |
plotepsg |
The projection of the current plot. If extents are valid lat/lons, the projection is assumed to be lat/lon (EPSG:4326), or Spherical Mercator otherwise (EPSG:3857). This is done to work seamlessly with OpenStreetMap packages. |
widthhint |
The fraction of the plottable width which the scale bar should (mostly) occupy. |
unitcategory |
One of "metric" or "imperial" |
extents |
The plot extents |
a list of parameters: $widthu (width of the scalebar in human
readable units); $unit (the human readable unit); $majordivu (the size
of the divisions in human readable units); $majordivs (the number of divisions);
$widthplotunit (width of the scalebar in plotting units); $majordivplotunit
(the width of divisions in plotting units); $labeltext (label text); and extents
the user extents (par('usr')) that were used to calculate the parameters.
plot(1:5, 1:5, asp=1) scalebarparams(plotunit="m")plot(1:5, 1:5, asp=1) scalebarparams(plotunit="m")
Use the PickPoint.io API or Google API to
retreive a bounding box for the given query. Note that if
you would like to use google as a source, you must agree to the Google
API terms and conditions.
searchbbox(querystring, ...)searchbbox(querystring, ...)
querystring |
The search query. Passing a vector in will find the bounding box that contains all bounding boxes returned. |
... |
Additional paramters to be passed on to geocode. Passing |
A 2x2 matrix describing a bounding box like that returned by sp::bbox()
#don't test to speed up checking time searchbbox("kings county, NS") searchbbox("University Ave. Wolfville NS", source="google") searchbbox("Wolfville ns", source="google") searchbbox(c("Vermont", "Nova Scotia"))#don't test to speed up checking time searchbbox("kings county, NS") searchbbox("University Ave. Wolfville NS", source="google") searchbbox("Wolfville ns", source="google") searchbbox(c("Vermont", "Nova Scotia"))
For internal use only.
set_cached(cache, url, data, ...) get_cached(cache, url, ...) clear_cache(cache, ...) cache_size(cache, ...)set_cached(cache, url, data, ...) get_cached(cache, url, ...) clear_cache(cache, ...) cache_size(cache, ...)
cache, url, data, ...
|
For internal use only |
Values for internal use
Manipulate the extents of a bounding box by zooming and moving an
existing bbox. This is helpful when manipulating the extents of a
plot created by canvec.qplot()
zoombbox(bbox, factor = 1, offset = c(0, 0))zoombbox(bbox, factor = 1, offset = c(0, 0))
bbox |
An existing bbox |
factor |
A factor to zoom by. >1 will zoom in, <1 will zoom out. If a vector is passed, the first element will zoom the X extent, the second element will zoom the Y extent. |
offset |
A vector describing the X and Y offset that should be applied. |
A zoomed bounding box.
box1 <- makebbox(45, -64, 44, -65) zoombbox(box1, c(.2,.5))box1 <- makebbox(45, -64, 44, -65) zoombbox(box1, c(.2,.5))