1.2.loaMapPlot: Map plotting for lattice

In loa: Lattice Options and Add-Ins

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)

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.

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.

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.

Note

Google Maps outputs are 2D projections of curve sections of the Earth's surface. Therefore, the assignment of points within panels and the annotation of latitudes and longitudes along axis needs to be locally handled to account for this.

LatLon2MercatorXY and MercatorXY2LatLon are used to locally scale both axis and data in these plots. These apply methods and code in the "sp" package.

Important: Users wanting to add data to these plots, e.g. using update or layers in latticeExtra, should first rescale the data. Likewise, users wanting to add maps to other plots will need to rescale plotted data to use these maps. See Example 1 below.

Important: map APIs often return a map panel larger than the data (latitude, longitude) range requested. This means you may get back a map that is large than necessary. As xlim and ylim are passed to the API when they are called reseting these can produce similar effects (so you may not get exactly the map range you ask for! If you want to manually optimise an RgoogleMapsPlot map range, the best option is currently to start with:

RgoogleMapsPlot(..., size=c(640,640))

...and then change either or both size values until you generate an appropriate map size.

Author(s)

Karl Ropkins

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:
## Not run: 
loaMapPlot(zinc~latitude*longitude, col.regions=c("grey", "darkred"), 
           data=lat.lon.meuse)
## End(Not run)
#  (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
## Not run: 
loaMapPlot(zinc~latitude*longitude, col.regions=c("grey", "darkred"),
           panel=panel.binPlot, data=lat.lon.meuse)
## End(Not run)
#  using zcase panelling to handle multiple z terms 
## Not run: 
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)
## End(Not run)
#   using a specialist panel to handle multiple z terms 
#   (Please note: This will take a while...)
## Not run: 
loaMapPlot(cadmium*50+copper*10+lead*2+zinc~latitude*longitude, 
           col.regions=c("grey", "darkred"), panel=panel.zcasePiePlot,
           data=lat.lon.meuse)
## End(Not run)

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

loa documentation built on Dec. 25, 2024, 3 p.m.