plot2map: plot2map
In eblondel/Rmapit: A package to facilitate the drawing of geographical maps in R

Description Usage Arguments Details Author(s) Examples

plot2map allows to append plots (graphics, maps, etc) within a map that has been previously created. For this, the function assumes that you have a spatial object (sp) that gives the locations where the plots should be drawn. This object could be of any geometry type (point, polygon, line). In addition, the function requires an object containing the data to be plotted. This object must have a common reference with the sp object, identifying the locations. Finally, the function requires the user to specify a function that will be used to draw the plot at each location.

1 2	plot2map(sp, sp.ref, stat, stat.ref, stat.handler, ratio, pos, offset, pars, box.lty, box.col)

`sp`	an object of class "spatial" defining the locations where a plot will be added to the map
`sp.ref`	name of the `sp` object column, used as reference to identify each location of the `sp` object,eg the code/name of a sampling station.
`stat`	an object of class "data.frame" or "list", giving the dataset of values that will be used to produce a plot at each location of the `sp` object.
`stat.ref`	(optional) in case the `stat` object is of class `data.frame`, `stat.ref` is the name of the `stat` column being joined to `sp.ref`, to associate each plot to generate to its location on the map.
`stat.handler`	a function defined by the user to produce the plot. This function will be then called by `plot2map` to draw an internal plot at each xy location defined by the `sp` object. This function must take as argument an object of class "data.frame" which corresponds to a subset of the data.frame object defined in `stat` argument.
`ratio`	a numeric value giving the size of each plot in proportion to the size of the plot device. Default value is set to 0.1
`pos`	location where the graph generated by `stat.handler` should be located relative to the xy coordinate. By default, pos is set to "c" (center). The values accepted are defined as follows: "tl" (topleft), "t" (top), "tr" (topright), "l" (left), "c" (center), "r" (right), "bl" (bottomleft), "b" (bottom), "br" (bottomright).
`offset`	a numeric value to increase distance of the drawn plot relative to the xy location. Default value is 0. For any "center" plot position, the `offset` parameter is not applied.
`pars`	optional list of graphical parameters to apply to the internal plot drawn at each xy location.
`box.lty`	line type used for drawing the `box("figure")` for each graph inset. Default value is "solid".
`box.col`	line color used for drawing the `box("figure")` for each graph inset. Default value is "transparent".

The sp argument could point to a SpatialPointsDataFrame object or any other Spatial object of geometry type other than point. In such case, the coordinates used as reference for positioning the plots will be the labpt slot of the spatial object.

The function plot2map brings the advantage to let the user define the graph he wants to embedd in the map. In addition, the implementation allows a close linkage with the spatial plot, which means that inset graphs are binded to the map when the graphic device is resized by the user.

However, the current function has several limitations: its capacity to attach inset graphs to spatial coordinates makes the use of multiple plots currently incompatible with plot2map. For time being, plot2map is stable only for single plot (one figure per device).

The ongoing investigations are focusing on the capacity to make plot2map working for multiplot devices. Some test code is provided.

Current limitations:

multiplot drawing order: Due to the internal use of layout and par("fig"), eventual multiplot set by the user is disabled, which forces to recall initial pars, and par(mfg). This approach is partially operational as the byrow plotting order is forced, even if the user specifies multiplots with par(mfcol = ...)

.

graph inset positions: Accurate graph inset positions were noted with multiplot with nr and nc <= 2, but resizing of device leads to unbound graph insets in relation to the map locations. Multiplots with more than 2 lines or rows do not handle well plot2map.

Note for RStudio users: RStudio has a specific graphic device (see getOption("device")), which causes rendering issues when using plot2map. To solve this, the R default graphical device should be used instead. With RStudio, it is possible to use R default graphic device by deleting existing RStudio devices and run options(options(device = "windows"))

Emmanuel Blondel, emmanuel.blondel1@gmail.com

#use meuse sample data from sp package
require(sp)
data(meuse, package = "sp")
coordinates(meuse) <- c("x","y")
meuse@data <- cbind(meuse@data, code = row.names(meuse))

#generate a random dataset (df) to illustrate graphic drawing on the map
df <- do.call("rbind",
	lapply(unique(as.character(meuse@data$code)),
		function(x){
			as.data.frame(cbind(rep(as.character(x),100),rnorm(1:100)))
		}
	)
)
colnames(df) <- c("ref_code","value")
df$ref_code <- as.character(df$ref_code)
df$value <- as.numeric(as.character(df$value))

#example 1: hist plot handler
#----------------------------
myHandler <- function(x){
	hist(as.numeric(x$value), main="",xlab = NULL, ylab=NULL,
		col="cornflowerblue", cex.axis =0.8, cex = 0.5)
}

#plot the locations
plot(meuse[1:10,])

#generate graphs within the map
plot2map(sp = meuse[1:10,], sp.ref = "code",
		stat = df, stat.ref = "ref_code", stat.handler = myHandler,
		ratio = 0.12, box.lty = "dashed", box.col = "orange")

#example 2: scatterplot handler
#------------------------------
myHandler2 <- function(x){
	testx <- rnorm(100)
	testy <- rnorm(100)
	plot(testx[1:50],testy[1:50],col="red",pch=19,cex=0.7)
	op = par(new = TRUE)
	points(testx[50:100],testy[50:100],col="blue",pch=19,cex=0.7)
	par(op)
}

#plot the locations
plot(meuse[1:10,])

#generate graphs within the map
plot2map(sp = meuse[1:10,], sp.ref = "code",
		stat = df, stat.ref = "ref_code", stat.handler = myHandler2,
		ratio = 0.12, box.lty = "dashed", box.col = "orange")	


#example 3: enabling multiplots (under investigation)
#--------------------------------------------------
par(mar=c(2,2,2,2), mfrow=c(2,2))
for(i in 1:4){
	plot(meuse[1:10,])
	plot2map(sp = meuse[1:10,], sp.ref = "code",
		stat = df, stat.ref = "ref_code", stat.handler = myHandler, ratio=0.08)
}