Data visualisation on maps

Description

Create simple maps; add sub-plots like pie plots to a map or any other plot; format, plot and export gridded data. The package was developed for displaying fisheries data but most functions can be used for more generic data visualisation. For a complete list of functions with individual help pages, use library(help="mapplots").

Details

The starting point is generally the function basemap which creates a blank map (although most mapplots functions could be applied to any plot, not just maps). Coastlines or other features can be added to the map with the function draw.shape. ICES rectangles can also be displayed on the map and axes by draw.rect. The main purpose of this package is to visualise data on maps. For univariate data, the main functions are draw.bubble (bubble plots) and draw.grid (heat maps). Multivariate data can be displayed with draw.barplot2D ('square pie plots'), draw.pie (pie plots) and draw.xy (xy or barplots). Some of these have a specific function for displaying a legend: legend.bubble, legend.grid and legend.pie. The following functions can help to get data in the right format for plotting: make.grid and make.multigrid (to create grd objects for draw.grid) and make.xyz (to create xyz objects for draw.barplot2D and draw.pie). Finally, there is a functions to export grd objects as csv or shapefiles: write.grid. The remaining functions are called by the main funcions listed above and were never intended to be used directly. However, they are documented and can be called directly.

Author(s)

Hans Gerritsen

Maintainer: <hans.gerritsen@marine.ie>

Add pie plot to existing plot

Description

This function is used by draw.pie to add a pie plot at a specific location to an existing plot. It can be used directly but in general it is advisable to use draw.pie instead.

Usage

add.pie(z, x = 0, y = 0, labels = names(z), radius = 1, edges = 200, clockwise = 
  TRUE, init.angle = 90, density = NULL, angle = 45, col = NULL, border = NULL, 
  lty =  NULL, label.dist = 1.1, ...)

Arguments

Details

Because this function is intended to add pie plots to a map, the radius is scaled to units on the y-scale. This is more convenient than using the x-scale as 1 degree latitude is exactly 60 nautical miles. (The conversion from degrees to distance on the x-scale is less straightforward as it depends on the latitude).

Note

The function obtaines the aspect ratio of the current plot from get.asp in order to draw circular pies. If the plot window is re-sized and asp is not defined in par then the pies will end up being oval.

Author(s)

Adapted from the function pie by Hans Gerritsen

See Also

draw.pie

Examples

plot(NA,NA, xlim=c(-1,1), ylim=c(-1,1) )
add.pie(z=rpois(6,10), x=-0.5, y=0.5, radius=0.5)
add.pie(z=rpois(4,10), x=0.5, y=-0.5, radius=0.3)

Draw 2-dimensional barplots

Description

This function is used by draw.barplot2D to add a 2-dimensional barplot at a specific location to an existing plot. It can be used directly but in general it is advisable to use draw.barplot2D instead.

Usage

barplot2D(z, x = 0, y = 0, width = 1, height = 1, colour, add = TRUE, col.frame = NULL, 
	lwd.frame = 1, threshold = 1.1, ...)

Arguments

Details

The algorithm that determines the location of each rectangle within the 2D-barplot is as follows: 1) Start with a rectangle representing the highest value of z. 2) Try to put the first rectangle on the left. 3) If it too elongated, try to put two rectangles, on top of each other, on the left. 4) When you have placed those rectangles, proceed with the remaining rectangles.

More precisely, we choose the number of rectangles to stack so as to minimize the following penalty: penalty for the first rectangle in the stack + penalty for the last where the penalty of a rectangle is: ratio - 1.1. where ratio is the ratio of the longer side by the smaller.

Author(s)

Adapted by Hans Gerritsen

References

This function was adapted from code published on http://zoonek2.free.fr/UNIX/48_R/03.html (accessed 1 Jun 2012).

See Also

draw.barplot2D

Examples

plot(NA,NA, xlim=c(-1,1), ylim=c(-1,1) )
barplot2D(z=rpois(6,10), x=-0.5, y=0.5, width=0.75, height=0.75, colour=rainbow(6))
barplot2D(z=rpois(4,10), x=0.5, y=-0.5, width=0.5, height=0.5, colour=rainbow(4))

Draw a (blank) map

Description

A blank map is created that has approximately the correct aspect ratio for its latitude.

Usage

basemap(xlim, ylim, xlab = "Longitude", ylab = "Latitude", bg = "lightblue", ...)

Arguments

Details

The aspect ratio of the map is based on the approximation that the earth is a perfect sphere of 21600 nautical miles in circumference. The straight-line distance between two meridians that lie 1 degree apart is then 60 nautical miles ⁠*⁠ cos(latitude). The aspect ratio is therefore set at the inverse of the cosine of the latitude at the middle of the y-scale. If the plot window is re-sized the aspect ratio will remain correct but the background colour will not fill the full plot area.

Author(s)

Hans Gerritsen

Examples

data(landings)
data(coast)
xlim <- c(-11,-5.5)
ylim <- c(51.5,55.5)
basemap(xlim, ylim)
draw.shape(coast, col="cornsilk")

Define breakpoints for colour scales

Description

This function can be used to define breakpoints for use with the functions draw.grid and legend.grid

Usage

breaks.grid(grd, quantile = 0.975, ncol = 12, zero = TRUE)

Arguments

Value

a vector of breakpoints to be used by draw.grid and legend.grid

Author(s)

Hans Gerritsen

See Also

draw.grid, legend.grid

Examples

breaks.grid(100,ncol=6)
breaks.grid(100,ncol=5,zero=FALSE)

# create breaks on the log scale
exp(breaks.grid(log(10000),ncol=4,zero=FALSE))

Shapefile of the Irish and UK coastlines

Description

Shapefile list object (see: shapefiles) of the Irish and UK coastline.

Usage

data(coast)

Format

shapefile list object

Source

GSHHS A Global Self-consistent, Hierarchical, High-resolution Shoreline Database.

References

https://www.soest.hawaii.edu/pwessel/gshhg/

Draw 2-dimensional barplots in an existing plot

Description

2-Dimensional barplots are essentially rectangular pieplots. These plots can be used to display proportional data in certain locations on a map.

Usage

draw.barplot2D(x, y, z, width, height, scale = F, col = NULL, col.frame = "black", 
	lwd.frame = 1, silent = TRUE, ...)

Arguments

Details

The algorithm that determines the location of each rectangle within the 2D-barplot is as follows: 1) Start with a rectangle representing the highest value of z. 2) Try to put the first rectangle on the left. 3) If it too elongated, try to put two rectangles, on top of each other, on the left. 4) When you have placed those rectangles, proceed with the remaining rectangles.

More precisely, we choose the number of rectangles to stack so as to minimize the following penalty: penalty for the first rectangle in the stack + penalty for the last where the penalty of a rectangle is: ratio - 1.1. where ratio is the ratio of the longer side by the smaller.

Author(s)

Adapted by Hans Gerritsen

References

This function was adapted from http://zoonek2.free.fr/UNIX/48_R/03.html

Examples

data(landings)
data(coast)
xlim <- c(-15,0)
ylim <- c(50,56)
xyz <- make.xyz(landings$Lon,landings$Lat,landings$LiveWeight,landings$Species)
col <- rainbow(5)
basemap(xlim, ylim, main = "Species composition of gadoid landings")
draw.shape(coast, col="cornsilk")
draw.barplot2D(xyz$x, xyz$y, xyz$z, width = 0.8, height = 0.4, col=col)
legend("topright", legend=colnames(xyz$z), fill=col, bg="lightblue", inset=0.02)  
 
basemap(xlim, ylim, main = "Species composition of gadoid landings")
draw.shape(coast, col="cornsilk")
draw.barplot2D(xyz$x, xyz$y, xyz$z, width = 1, height = 0.5, scale=TRUE, col=col)
legend("topright", legend=colnames(xyz$z), fill=col, bg="lightblue", inset=0.02)

Draw bubble plots in an existing plot

Description

Bubble plots are plots of circles whose surfaces areas are proportional to values in z.

Usage

draw.bubble(x, y, z, maxradius = 1, ...)

Arguments

Author(s)

Hans Gerritsen

Examples

data(landings)
data(coast)
xlim <- c(-12,-5)
ylim <- c(50,56)
agg <- aggregate(list(z=landings$LiveWeight),list(x=landings$Lon,y=landings$Lat),sum)
basemap(xlim, ylim, main = "Gadoid landings")
draw.shape(coast, col="cornsilk")
draw.bubble(agg$x, agg$y, agg$z, maxradius=0.5, pch=21, bg="#00FF0050")
legend.z <- round(max(agg$z)/1000,0)
legend.bubble("topright", z=legend.z, maxradius=0.5, inset=0.02, bg="lightblue", txt.cex=0.8,
 pch=21, pt.bg="#00FF0050")

Display a grd object as a heatmap

Description

Displays a grid of colored or gray-scale rectangles with colors corresponding to the values in z. This can be used to display three-dimensional or spatial data as images.

Usage

draw.grid(grd, breaks = NULL, col = NULL)

Arguments

Note

The resulting maps are often referred to as heat maps although this is not strictly correct as red would imply the lowest and white the highest value (an object glowing white is hotter than an object glowing red). However using the scale in this way is counter-intuitive.

Author(s)

Hans Gerritsen

See Also

image

Examples

data(coast)
data(landings)
byx = 1
byy = 0.5
xlim <- c(-15.5,0)
ylim <- c(50.25,56)
grd <- make.grid(landings$Lon,landings$Lat,landings$LiveWeight, byx, byy, xlim, ylim)
breaks <- breaks.grid(grd,zero=FALSE)
basemap(xlim, ylim, main = "Gadoid landings")
draw.grid(grd,breaks)
draw.shape(coast, col="darkgreen")
legend.grid("topright", breaks=breaks/1000, type=2, inset=0.02, title="tonnes")

Draw pie plots in an existing plot

Description

Draw pie plots in an existing plot

Usage

draw.pie(x, y, z, radius, scale = T, labels = NA, silent = TRUE, ...)

Arguments

Author(s)

Hans Gerritsen

See Also

add.pie

Examples

data(landings)
data(coast)
xlim <- c(-12,-5)
ylim <- c(50,56)
xyz <- make.xyz(landings$Lon,landings$Lat,landings$LiveWeight,landings$Species)
col <- rainbow(5)
basemap(xlim, ylim, main = "Species composition of gadoid landings")
draw.shape(coast, col="cornsilk")
draw.pie(xyz$x, xyz$y, xyz$z, radius = 0.3, col=col)
legend.pie(-13.25,54.8,labels=c("cod","had","hke","pok","whg"), radius=0.3, bty="n", col=col,
 cex=0.8, label.dist=1.3)
legend.z <- round(max(rowSums(xyz$z,na.rm=TRUE))/10^6,0)
legend.bubble(-13.25,55.5,z=legend.z,round=1,maxradius=0.3,bty="n",txt.cex=0.6)
text(-13.25,56,"landings (kt)",cex=0.8) 

Draw ICES rectangles in an existing plot

Description

Draw ICES rectangles in an existing map and add axis labels to the top and right axes. ICES statistical rectangles (https://www.ices.dk) are rectangles of 1 degree longitude x 0.5 degrees latitude. They are used for reporting of fishing effort and landings.

Usage

draw.rect(col = "grey", lty = 2, ...)

Arguments

Author(s)

Hans Gerritsen

References

https://www.ices.dk

See Also

basemap

Examples

xlim <- c(-15,0)
ylim <- c(50,56)
basemap(xlim, ylim)
draw.rect()

Draw shapefiles in an existing plot

Description

Draw shapefiles in an existing plot

Usage

draw.shape(shape, type = "poly", col = 1, ...)

Arguments

Note

The shapefile needs to have the WGS 84 Geographic Coordinate System in order to display properly on a map of longitude and latitude.

Author(s)

Hans Gerritsen

See Also

read.shapefile

Examples

library(shapefiles)
shp.file <- file.path(system.file(package = "mapplots", "extdata"), "Ireland")
irl <- read.shapefile(shp.file)
xlim <- c(-11,-5.5)
ylim <- c(51.5,55.5)
basemap(xlim, ylim)
draw.shape(irl, col="cornsilk")

Draw xy sub-plots in an existing plot

Description

This function is intended to draw xy-plots or barplots in existing maps or other plots.

Usage

draw.xy(x, y, xx, yy, xlim = NULL, ylim = NULL, width = 1, height = 0.5, bg = NULL, 
	border = 1, type = "p", col = 1, silent = TRUE, ...)

Arguments

Details

type = "h" will result in plots that resemble barplots. These are not true barplots as the x-axis is not categorical. However if suitable xx data are provided and lwd is tweaked correctly for the current graphical device it will result in adequate plots.

Author(s)

Hans Gerritsen

Examples

data(effort)
data(coast)
xlim <- c(-12,-5)
ylim <- c(51,54)
col <- terrain.colors(12)
effort$col <- col[match(effort$Month,1:12)]
basemap(xlim, ylim, main = "Monthly trends in haddock landings and fishing effort")
draw.rect(lty=1, col=1)
draw.shape(coast, col="cornsilk")
draw.xy(effort$Lon, effort$Lat, effort$Month, effort$LiveWeight, width=1, height=0.5,
 col=effort$col, type="h",lwd=3, border=NA)
draw.xy(effort$Lon, effort$Lat, effort$Month, effort$Effort, width=1, height=0.5, col="red",
 type="l", border=NA)
draw.xy(effort$Lon, effort$Lat, effort$Month, effort$Effort, width=1, height=0.5, col="red",
 type="p",cex=0.4,pch=16, border=NA)
legend("topleft", c(month.abb,"Effort"), pch=c(rep(22,12),16), pt.bg=c(col,NA),
 pt.cex=c(rep(2,12),0.8),col=c(rep(1,12),2), lty=c(rep(NA,12),1), bg="lightblue",
 inset=0.02, title="Landings", cex=0.8)

Spatially disaggregated fishing effort and landings data

Description

Monthly fishing effort and haddock landings landings at a spatial resolution of 1 degree longitude and 0.5 degrees latitude. The data are from Irish otter trawlers in 2009.

Usage

data(effort)

Format

data frame

Source

EU Logbooks database

Get the current aspect ratio of a plot

Description

This function is used by draw.pie to draw circles (rather than ellipses) in existing plots.

Usage

get.asp()

Value

Returns the aspect ratio of the current plot.

Note

If the plot is re-sized get.asp is not automatically updated

Author(s)

Hans Gerritsen

See Also

draw.pie

Examples

plot(1:10,(1:10)/10)
get.asp()

Convert ICES rectangles from or to geographical coordinates

Description

ices.rect converts the names of ICES statistical rectangles into geographical coordinates (midpoints). ices.rect2 converts geographical coordinates into ICES statistical rectangles. ices.rect.lutx helper function to create a lookup table for rectangle codes along the x-axis ices.rect.luty helper function to create a lookup table for rectangle codes along the y-axis

Usage

ices.rect(rectangle)
ices.rect2(lon, lat)
ices.rect.lutx()
ices.rect.luty()

Arguments

Value

ices.rect will return a data frame with the midpoints of the ICES rectangles. ices.rect2 will return a vector with the names of the ICES rectangles.

Author(s)

Hans Gerritsen

References

ICES statistical rectangles https://www.ices.dk are rectangles of 1 degree longitude x 0.5 degrees latitude. They are used for reporting of fishing effort and landings.

Examples

# rectangle names to coordinates:
ices.rect(c("36E2","3600","40D8"))

# coordinates to rectangle names:
lon <- rnorm(10,-10,2)
lat <- rnorm(10,53,1)
rect <- ices.rect2(lon,lat)
basemap(xlim=range(lon), ylim=range(lat) )
draw.rect()
points(lon,lat)
text(lon,lat,rect,cex=0.7,pos=3)

Spatially disaggregated landings data

Description

Landings data of some gadoid species (cod, haddock, hake, saithe and whiting) at a spatial resolution of 1 degree longitude and 0.5 degrees latitude. The data are from Irish otter trawlers in 2009.

Usage

data(landings)

Format

data frame

Source

EU Logbooks database

Define location of a legend box.

Description

Define a location of a legend box. Used by legend.bubble and legend.pie. This is not intended as a user function.

Usage

legend.box(x, y = NULL, maxradius, mab = 1.2, inset = 0, double = F)

Arguments

Value

Returns the corner points of the legend box in user coordinates

Author(s)

Hans Gerritsen

See Also

legend.bubble, legend.pie

Examples

plot(1)
box <- legend.box("topleft", maxradius=0.2, inset=0.02)
rect(box[1],box[2],box[3],box[4], border="red", lwd=3, lty=2)
legend.bubble("topleft", z=10, maxradius=0.2, inset=0.02)

Legend for bubble plot

Description

Draw a legend for a bubble plot (draw.bubble)

Usage

legend.bubble(x, y = NULL, z, maxradius = 1, n = 3, round = 0, bty = "o", mab = 1.2, 
	bg = NULL, inset = 0, pch = 21, pt.bg = NULL, txt.cex = 1, 
	txt.col = NULL, font = NULL, ...)

Arguments

Author(s)

Hans Gerritsen

Examples

data(landings)
data(coast)
xlim <- c(-12,-5)
ylim <- c(50,56)
agg <- aggregate(list(z=landings$LiveWeight),list(x=landings$Lon,y=landings$Lat),sum)
basemap(xlim, ylim, main = "Gadoid landings")
draw.shape(coast, col="cornsilk")
draw.bubble(agg$x, agg$y, agg$z, maxradius=0.5, pch=21, bg="#00FF0050")
legend.bubble("topright", z=round(max(agg$z)/1000,0), maxradius=0.5, inset=0.02, bg="lightblue",
 txt.cex=0.8, pch=21, pt.bg="#00FF0050")

Legend for

Description

Draw a legend for a draw.grid plot

Usage

legend.grid(x, y = NULL, breaks, col ,digits = 2, suffix = "", type = 1, pch = 15,
	pt.cex = 2.5, bg = "lightblue", ...)

Arguments

Author(s)

Hans Gerritsen

See Also

draw.grid

Examples

data(coast)
data(landings)
byx = 1
byy = 0.5
xlim <- c(-15.5,0)
ylim <- c(50.25,56)
grd <- make.grid(landings$Lon,landings$Lat,landings$LiveWeight, byx, byy, xlim, ylim)
breaks <- breaks.grid(grd,zero=FALSE)
basemap(xlim, ylim, main = "Gadoid landings")
draw.grid(grd,breaks)
draw.shape(coast, col="darkgreen")
legend.grid("topright", breaks=breaks/1000, type=2, inset=0.02, title="tonnes")

Legend for pie plots

Description

Draw a legend for a draw.pie plot.

Usage

legend.pie(x, y = NULL, z, labels, radius = 1, bty = "o", mab = 1.2, bg = NULL, 
	inset = 0, ...)

Arguments

Author(s)

Hans Gerritsen

Examples

data(landings)
data(coast)
xlim <- c(-12,-5)
ylim <- c(50,56)
xyz <- make.xyz(landings$Lon,landings$Lat,landings$LiveWeight,landings$Species)
col <- rainbow(5)
basemap(xlim, ylim, main = "Species composition of gadoid landings")
draw.shape(coast, col="cornsilk")
draw.pie(xyz$x, xyz$y, xyz$z, radius = 0.3, col=col)
legend.pie(-13.25,54.8,labels=c("cod","had","hke","pok","whg"), radius=0.3, bty="n", col=col,
 cex=0.8, label.dist=1.3)
legend.z <- round(max(rowSums(xyz$z,na.rm=TRUE))/10^6,0)
legend.bubble(-13.25,55.5,z=legend.z,round=1,maxradius=0.3,bty="n",txt.cex=0.6)
text(-13.25,56,"landings (kt)",cex=0.8)

Create grd object

Description

Create a grd object from x, y and z data. For use with draw.grid and write.grid.

Usage

make.grid(x, y, z, byx , byy , xlim, ylim, fun = function(x) sum(x, na.rm = T))

Arguments

Details

Due to the way fractions are stored in binary format, rounding errors can occur, e.g.:

as.character(seq(-5,0,by=0.8))

results in:

"-5" "-4.2" "-3.4" "-2.6" "-1.8" "-1" "-0.199999999999999"

this can affect the make.grid function although this is generally not a problem.

Value

a grd object, which is simply a 2-dimensional array with row and column names that correspond to the x and y positions of the grid.

Author(s)

Hans Gerritsen

See Also

draw.grid

Examples

data(coast)
data(landings)
byx = 1
byy = 0.5
xlim <- c(-15.5,0)
ylim <- c(50.25,56)
grd <- make.grid(landings$Lon,landings$Lat,landings$LiveWeight, byx, byy, xlim, ylim)
breaks <- breaks.grid(grd,zero=FALSE)
basemap(xlim, ylim, main = "Gadoid landings")
draw.grid(grd,breaks)
draw.shape(coast, col="darkgreen")
legend.grid("topright", breaks=breaks/1000, type=2, inset=0.02, title="tonnes")

Create a grd object

Description

Create list of grd objects from x, y, z and group data, where each level of group provides a separate grd object. For use with draw.grid.

Usage

make.multigrid(x, y, z, group, ...)

Arguments

Value

a list of grd objects, see make.grid.

Author(s)

Hans Gerritsen

See Also

make.grid, draw.grid

Examples

data(coast)
data(landings)
byx = 1
byy = 0.5
xlim <- c(-12.5,-5)
ylim <- c(50.25,56)
grd <- make.multigrid(landings$Lon,landings$Lat,landings$LiveWeight, landings$Species,
 byx, byy, xlim, ylim)
breaks <- breaks.grid(grd,zero=FALSE)
par(mfrow=c(2,3),mar=c(1,1,2,1) )
for(s in names(grd) ) {
  basemap(xlim, ylim, main = s, axes=FALSE)
  draw.grid(grd[[s]],breaks)
  draw.shape(coast, col="darkgreen")
}
plot.new()
legend.grid("center",breaks=breaks/1000,type=2)

Create xyz object

Description

Create an xyz object for use with the functions draw.barplot2D and draw.pie

Usage

make.xyz(x, y, z, group, FUN = sum, ...)

Arguments

Author(s)

Hans Gerritsen

See Also

draw.barplot2D and draw.pie

Examples

data(landings)
data(coast)
xlim <- c(-12,-5)
ylim <- c(50,56)
xyz <- make.xyz(landings$Lon,landings$Lat,landings$LiveWeight,landings$Species)
col <- rainbow(5)
basemap(xlim, ylim, main = "Species composition of gadoid landings")
draw.shape(coast, col="cornsilk")
draw.pie(xyz$x, xyz$y, xyz$z, radius = 0.3, col=col)
legend.pie(-13.25,54.8,labels=c("cod","had","hke","pok","whg"), radius=0.3, bty="n",
 col=col, cex=0.8, label.dist=1.3)
legend.z <- round(max(rowSums(xyz$z,na.rm=TRUE))/10^6,0)
legend.bubble(-13.25,55.5,z=legend.z,round=1,maxradius=0.3,bty="n",txt.cex=0.6)
text(-13.25,56,"landings (kt)",cex=0.8) 

Progress message

Description

progress message in the R console.

Usage

setProgressMsg(min = 0, max = 1)
progressMsg(pm, value, round = 0)

Arguments

Details

setProgressMsg sets up a list with variables used and updated by progressMsg

Value

a list

Author(s)

Hans Gerritsen

See Also

See also txtProgressBar

Examples

## Not run: 
  pm <- setProgressMsg(0,500)
  for(i in 1:500) {
    pm<- progressMsg(pm,i)
    Sys.sleep(0.01)
  
  }
  rm(pm)
  
## End(Not run)

Export a grd object as csv or shapefile

Description

Export a grd object (created by make.grid) as csv or shapefile.

Usage

write.grid(grd, file, type="csv")

Arguments

Value

A csv file with three columns corresponding to x, y and z (lon, lat, value), or a shapefile with a polygon for each cell in the grd object. The assumed projection is EPSG:4326

Author(s)

Hans Gerritsen

See Also

make.grid, write.shapefile .

Examples

library(shapefiles)
data(landings)
data(coast)
byx = 1
byy = 0.5
xlim <- c(-15.5,0)
ylim <- c(50.25,56)
grd <- make.grid(landings$Lon, landings$Lat, landings$LiveWeight, byx, byy, xlim, ylim)
breaks <- breaks.grid(grd,zero=FALSE)
basemap(xlim, ylim, main = "Gadoid landings")
draw.grid(grd,breaks)
draw.shape(coast, col="darkgreen")
legend.grid("topright", breaks=breaks/1000, type=2)
## Not run: 
write.grid(grd,"c:/test1.csv")
write.grid(grd,"c:/test1","shape")

## End(Not run)