loa (version 0.3.1.1)

1.2.loaMapPlot.and.geoplotting.tools: Map plotting for lattice

Description

Plotting georeferenced data on maps using lattice, RgoogleMaps and OpenStreetMap

Usage

loaMapPlot(x, data = NULL, panel = panel.loaPlot, map = NULL, 
        map.panel = panel.loaBGMapPlotRaster, recolor.map = FALSE, 
        show.axes = FALSE, ..., map.source = getOSMapArg, 
        lon.lat = FALSE)
  RgoogleMapsPlot(x, data = NULL, ...)
  OpenStreetMapPlot(x, data = NULL, ...)
  
  #map handlers
  getRGMapArg(ylim, xlim, ..., lim.borders = 0.1)
  getOSMapArg(ylim, xlim, ..., lim.borders = 0.1)
  loaMapArg(object = NULL)
  #map panels
  panel.loaBGMapPlotRaster(map)
  panel.loaBGMapPlot(map)
  
  #scaling and axis handlers
  LatLon2MercatorXY(latitude, longitude, ...)
  MercatorXY2LatLon(mx, my, ...)
  axis.components.loaMap(map, xlim = NULL, ylim = NULL, ...)
  xscale.components.loaMap(lim, ..., map = map)
  yscale.components.loaMap(lim, ..., map = map)
  
  #legacy functions
  googleMap(...)
  GoogleMap(...)
  makeMapArg(...)
  getMapArg(object = NULL)

Value

MapPlots return trellis objects, much like conventional lattice plot functions.

get...MapArgs return lists for use as maps in ...MapPlot calls.

getMapArg recovers the map from an existing

GoogleMap output.

panel.GoogleMapsRaster and panel.GoogleMaps

generate panel outputs suitable for use in standard lattice

panel functions.

yscale.components.GoogleMaps, xscale.components.GoogleMaps

generate suitable latitude, longitude scales for use with map layers.

axis.components.GoogleMaps is a wrapper for their routine use.

Arguments

x

For MapPlots only. A formula setting the plot structure, by default z ~ latitude * longitude | cond. The axis elements latitude and longitude are required, while z and conditioning cond are optional.

data

For MapPlots only. If supplied, the assumed source of the elements of formula x, typically a data.frame.

panel, map.panel

For MapPlots only. The panels to use when generating the plot data and map layers, respectively. panel is by default the standard loa scatter plot panel panel.loaPlot. map.panel can be the default panel.loaBGMapPlotRaster or the alternative panel.loaBGMapPlot.

map, map.source

For MapPlots and related functions only. If supplied, map is a modified RgoogleMaps or OpenStreetMap output, generated using either package and getRSMapArg or getOSMapArg, respectively. If NULL (default), the MapPlot using the get function assigned using map.source to get the map.

recolor.map

For MapPlots only. If supplied, a vector of elements that R can treat as colors, used as a color scale to recolor map. This uses standard RColorBrewer functions, so can handle arguments like recolor.map = c("white", "grey") for greyscale, etc. Disabled by the default, or FALSE or NULL settings.

show.axes

For MapPlots only. Logical (default FALSE) to include or exclude latitude and longitude axes and associated labelling from MapPlots.

...

Additional arguments are passed on to related functions.

For MapPlots these are getRSMapArg or getOSMapArg, colHandler, cexHandler and xyplot.

By default both data point colour and size are z-scaled for MapPlots. So, if z is supplied, these plot properties are managed by cexHandler and colHandler, respectively, unless defined in the call or panel setup. cexHandler and colHandler arguments can also be passed direct as part of a MapPlot command to fine-tune z-scaling, e.g. cex.range to change the cex range that z values are scaled across and col.region to change the color range that is applied to z. See associated Help documents for further information.

Similarly, argument passing to xyplot in both MapPlots provides access to most common plot parameters, e.g. col, pch, and cex for plot symbol color, type and size, respectively.

getMap functions pass arguments to related RgoogleMaps or OpenStreetMap functions.

lon.lat

For MapPlots only, logical. If TRUE applies z ~ lon * lat | cond? This operation is handled using the formula.type argument in formulaHandler

ylim, xlim, lim.borders, lim

The latitude and longitude plot ranges. ylim and xlim are only required by get functions, which use these to set the requested map size. The additional argument lim.borders, sets the borders to be added. The default 0.1 adds a 10% border to both axes, while two-element vectors allow provide separate control of the axes. For the axis handlers (yscale... and xscale...) the local alternative lim is used for both ylim and xlim in generic code.

object

For loaMapArg, the MatPlot plot to extract a map from. (If not supplied, this is assumed to last lattice plot.)

latitude, longitude

For LatLon2MercaptorXY, paired latitude and longitude time-series to be converted to paired Mercaptor X and Y time-series.

mx, my

For MercaptorXYLatLon, paired Mercaptor X and Y time-series to be converted to paired latitude and longitude time-series.

Author

Karl Ropkins

Details

loaMapPlot provides lattice-style conditioning/handling for RgoogleMaps and OpenStreetMap outputs. This uses loaPlot and panelPal to manage default panel and key settings.

RgoogleMapsPlot is a shortcut for using loaMapPlot with maps produced by RgoogleMaps.

OpenStreetMapPlot is a shortcut for using loaMapPlot with maps produced by OpenStreetMap.

getMap... functions accept latitude and longitude ranges and related RgoogleMaps or OpenStreetMap function arguments, and produces an output suitable for use as the map argument in subsequent (same area) MapPlots or in panel.loaBGMapPlotRaster or panel.loaBGMapPlot panel function calls.

LatLon2MercatorXY converts supplied latitude and longitude time-series to Mercator X and Y time-series. MercatorXY2LatLon converts supplied Mercator X and Y time-series to latitude and longitude time-series. Both output results as lists containing newX and newY elements.

panel.loaBGMapPlotRaster and panel.loaBGMapPlotMaps are lattice panel functions that generate map layers for a lattice plot using getMap... function outputs.

yscale.components.loaMap and xscale.components.loaMap are y- and x-axis handlers for use with the above panels.

axis.components.loaMap is a wrapper that combines yscale.components.loaMap and xscale.components.loaMap and allows both axis to be set from the lattice function argument axis rather than each individually, via yscale.components and xscale.components.

NOTE: The MapPlots and related panel and axis handling functions are in development functions that have been subject to changes.

googleMap and GoogleMap are RgoogleMapsPlot wrappers, included these were names of earlier versions of this function, that have been documented in previously published code.

getMapArg was the earlier name for loaMapArg.

quickMap, a crude map plot function intended to demonstrate the use of the 'handler' functions, is no longer packaged but the code is included in the examples below.

References

This function makes extensive use of code developed by others.

lattice: Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization with R. Springer, New York. ISBN 978-0-387-75968-5

RColorBrewer: Erich Neuwirth <[e-mail]> (2011). RColorBrewer: ColorBrewer palettes. R package version 1.0-5. http://CRAN.R-project.org/package=RColorBrewer

RgoogleMaps: Markus Loecher and Sense Networks (2011). RgoogleMaps: Overlays on Google map tiles in R. R package version 1.1.9.6. http://CRAN.R-project.org/package=RgoogleMaps

OpenStreetMap: Ian Fellows and using the JMapViewer library by Jan Peter Stotz (2019). OpenStreetMap: Access to Open Street Map Raster Images. R package version 0.3.4. https://CRAN.R-project.org/package=OpenStreetMap

sp: Pebesma, E.J., R.S. Bivand, 2005. Classes and methods for spatial data in R. R News 5 (2). https://cran.r-project.org/doc/Rnews/.

Roger S. Bivand, Edzer Pebesma, Virgilio Gomez-Rubio, 2013. Applied spatial data analysis with R, Second edition. Springer, NY. http://www.asdar-book.org/

Users should also always cite map sources when using outputs from these MapPlots:

For GoogleMaps: Map layer: Map data (c) [year] Google

For OpenStreetMap Map layer (c) OpenStreetMap contributors

See Also

In other packages, see

RgoogleMaps: GetMap.

OpenStreetMap: openmap.

sp: coordinates; proj4string; and, spTransform.

lattice: xyplot; panel.xyplot; and panel.levelplot.

Examples

## Example 1
## quickMap code
## as example of third-party use of functions

quickMap <- function(lat, lon, show.data = FALSE, ...){

    #get map
    map <- getRGMapArg(lat, lon, ...)

    #scale axis for map projection
    map.axis.comps <- axis.components.loaMap(map)
    map.axis <- function(components, ...) 
                   axis.default(components = map.axis.comps, ...)

    #scale data for map projection
    temp <- LatLon2MercaptorXY(lat, lon)
    lat <- temp$newY
    lon <- temp$newX

    #plot data on map
    xyplot(lat~lon, 
           xlim = map$xlim, ylim = map$ylim,
           aspect = map$aspect, 
           axis = map.axis,
           panel = function(...){
               panel.loaGBMapPlotRaster(map)
               if(show.data)
                   panel.xyplot(...)
           }, ...)
}

## Example 2
## Off-line loaMapPlot example:

loaMapPlot(zinc~latitude*longitude, col.regions=c("grey", "darkred"), 
           data=lat.lon.meuse, map=roadmap.meuse)

#  Note 1:
#  Here, the map argument is supplied so example works off-line. 
#  If not supplied and R is on-line, the MapPlots will get map 
#  from either Google or OpenStreetMap API. Repeat any of above 
#  without map argument   when on-line. For example:
if (FALSE) {
loaMapPlot(zinc~latitude*longitude, col.regions=c("grey", "darkred"), 
           data=lat.lon.meuse)}
#  (The map will appear slightly different because non-default 
#  size and maptype settings were used to make roadmap.meuse. See 
#  ?roadmap.meuse for details.)  

#  Note 2:
#  To make a map for use with panel.loaBGMapPlotRaster or panel.loaBGMapPlotRaster  
#  without plotting use makeRGMapArg() or makeOSMapArg(). 
#  To recover a map from a previously plotted loa MapPloy use loaMapArg(). 

#  Note 3:
#  Other example loaMapPlots (also not run):   
#  using panel.binPlot to change data layer
if (FALSE) {
loaMapPlot(zinc~latitude*longitude, col.regions=c("grey", "darkred"),
           panel=panel.binPlot, data=lat.lon.meuse)}
#  using zcase panelling to handle multiple z terms 
if (FALSE) {
loaMapPlot(cadmium*50+copper*10+lead*2+zinc~latitude*longitude, 
           col.regions=c("grey", "darkred"), key.z.main="Concentrations", 
           panel.zcases = TRUE, data=lat.lon.meuse)}
#   using a specialist panel to handle multiple z terms 
#   (Please note: This will take a while...)
if (FALSE) {
loaMapPlot(cadmium*50+copper*10+lead*2+zinc~latitude*longitude, 
           col.regions=c("grey", "darkred"), panel=panel.zcasePiePlot,
           data=lat.lon.meuse)}

#  Note 4: 
#  For all maps generated in above examples, the Map layer is 
#  (c) OpenStreetMap contributors