R: Map plotting for lattice

1.2.loaMapPlot.and.geoplotting.tools {loa}

R Documentation

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 = getRGMapArg, 
        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 = trellis.last.object())

  #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 = trellis.last.object())

Arguments

`x`	For `MapPlot`s 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 `MapPlot`s 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 `MapPlot`s 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 `MapPlot`s 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 `MapPlot`s only. Logical (default `FALSE`) to include or exclude latitude and longitude axes and associated labelling from `MapPlot`s.
`...`	Additional arguments are passed on to related functions. For `MapPlot`s these are `getRSMapArg` or `getOSMapArg`, `colHandler`, `cexHandler` and `xyplot`. By default both data point colour and size are `z`-scaled for `MapPlot`s. 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 `MapPlot`s 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 `MapPlot`s 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) MatPlots 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 <erich.neuwirth@univie.ac.at> (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

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 GoogleMap examples

#  Use a subsample of lat.lon.meuse
temp <- lat.lon.meuse[sample(1:155, 15),]

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

RgoogleMapsPlot(zinc~latitude*longitude, col.regions=c("grey", "darkred"),
          panel=panel.binPlot, 
          data=temp, map=roadmap.meuse)

RgoogleMapsPlot(cadmium*50+copper*10+lead*2+zinc~latitude*longitude, 
          col.regions=c("grey", "darkred"), 
          key.z.main="Concentrations", panel.zcases = TRUE,
          data=temp, map=roadmap.meuse)

RgoogleMapsPlot(cadmium*50+copper*10+lead*2+zinc~latitude*longitude, 
          col.regions=c("grey", "darkred"), panel=panel.zcasePiePlot,
          data=temp, 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: 
   RgoogleMapsPlot(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 makeRGMapArg(). 
#  To recover a map from a previously plotted loa MapPloy use loaMapArg().

[Package loa version 0.2.48.3 Index]