tm_lines: Draw spatial lines

Description

Creates a tmap-element that draw spatial lines.

Usage

tm_lines(col = NA, lwd = 1, lty = "solid", alpha = NA, scale = 1, lwd.legend = NULL, lwd.legend.labels = NULL, n = 5, style = ifelse(is.null(breaks), "pretty", "fixed"), breaks = NULL, palette = NULL, labels = NULL, auto.palette.mapping = TRUE, contrast = NA, max.categories = 12, colorNA = NA, textNA = "Missing", showNA = NA, title.col = NA, title.lwd = NA, legend.col.show = TRUE, legend.lwd.show = TRUE, legend.format = list(), legend.col.is.portrait = TRUE, legend.lwd.is.portrait = FALSE, legend.hist = FALSE, legend.hist.title = NA, legend.col.z = NA, legend.lwd.z = NA, legend.hist.z = NA, id = NA)

Arguments

col

color of the lines. Either a color value or a data variable name. If multiple values are specified, small multiples are drawn (see details).

lwd

line width. Either a numeric value or a data variable. In the latter case, the class of the highest values (see style) will get the line width defined by scale. If multiple values are specified, small multiples are drawn (see details).

lty

line type.

alpha

transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the col is used (normally 1).

scale

line width multiplier number.

lwd.legend

vector of line widths that are shown in the legend. By default, this is determined automatically.

lwd.legend.labels

vector of labels for that correspond to lwd.legend.

preferred number of color scale classes. Only applicable when lwd is the name of a numeric variable.

style

method to process the color scale when col is a numeric variable. Discrete options are "cat", "fixed", "sd", "equal", "pretty", "quantile", "kmeans", "hclust", "bclust", "fisher", and "jenks". A numeric variable is processed as a categorial variable when using "cat", i.e. each unique value will correspond to a distinct category. For the other discrete options, see the details in classIntervals. Continuous options are "cont" and "order". The former maps the values of col to a smooth gradient, whereas the latter maps the order of values of col to a smooth gradient. They are the continuous variants of respectively the discrete methods "equal" and quantile".

breaks

in case style=="fixed", breaks should be specified

palette

color palette (see RColorBrewer::display.brewer.all) for the lines. Only when col is set to a variable. The default palette is taken from tm_layout's argument aes.palette.

labels

labels of the classes

auto.palette.mapping

When diverging colour palettes are used (i.e. "RdBu") this method automatically maps colors to values such that the middle colors (mostly white or yellow) are assigned to values of 0, and the two sides of the color palette are assigned to negative respectively positive values. In this case of line widths, obviously only the positive side is used. When categorical color palettes are used, this method stretches the palette is there are more levels than colors.

contrast

vector of two numbers that determine the range that is used for sequential and diverging palettes (applicable when auto.palette.mapping=TRUE). Both numbers should be between 0 and 1. The first number determines where the palette begins, and the second number where it ends. For sequential palettes, 0 means the brightest color, and 1 the darkest color. For diverging palettes, 0 means the middle color, and 1 both extremes. If only one number is provided, this number is interpreted as the endpoint (with 0 taken as the start).

max.categories

in case col is the name of a categorical variable, this value determines how many categories (levels) it can have maximally. If the number of levels is higher than max.categories and auto.palette.mapping is FALSE, then levels are combined.

colorNA

color used for missing values. Use NULL for transparency.

textNA

text used for missing values.

showNA

logical that determines whether missing values are named in the legend. By default (NA), this depends on the presence of missing values.

title.col

title of the legend element regarding the line colors

title.lwd

title of the legend element regarding the line widths

legend.col.show

logical that determines whether the legend for the line colors is shown

legend.lwd.show

logical that determines whether the legend for the line widths is shown

legend.format

list of formatting options for the legend numbers. Only applicable if labels is undefined. Parameters are:

scientific: Should the labels be formatted scientically? If so, square brackets are used, and the format of the numbers is "g". Otherwise, format="f", and text.separator, text.less.than, and text.or.more are used. Also, the numbers are automatically rounded to millions or billions if applicable.
format: By default, "f", i.e. the standard notation xxx.xxx, is used. If scientific=TRUE then "g", which means that numbers are formatted scientically, i.e. n.dddE+nn if needed to save space.
digits: Number of digits after the decimal point if format="f", and the number of significant digits otherwise.
text.separator: Character string to use to separate numbers in the legend (default: "to").
text.less.than: Character string to use to translate "Less than" (which is the default).
text.or.more: Character string to use to translate "or more" (which is the default).
...: Other arguments passed on to formatC

legend.col.is.portrait

logical that determines whether the legend element regarding the line colors is in portrait mode (TRUE) or landscape (FALSE)

legend.lwd.is.portrait

logical that determines whether the legend element regarding the line widths is in portrait mode (TRUE) or landscape (FALSE)

legend.hist

logical that determines whether a histogram is shown regarding the line colors

legend.hist.title

title for the histogram. By default, one title is used for both the histogram and the normal legend for line colors.

legend.col.z

index value that determines the position of the legend element regarding the line colors with respect to other legend elements. The legend elements are stacked according to their z values. The legend element with the lowest z value is placed on top.

legend.lwd.z

index value that determines the position of the legend element regarding the line widths. (See legend.col.z)

legend.hist.z

index value that determines the position of the legend element regarding the histogram. (See legend.col.z)

name of the data variable that specifies the indices of the lines. Only used for "view" mode (see tmap_mode).

Value

tmap-element

Details

Small multiples can be drawn in two ways: either by specifying the by argument in tm_facets, or by defining multiple variables in the aesthetic arguments. The aesthetic arguments of tm_lines are col and lwd. In the latter case, the arguments, except for the ones starting with legend., can be specified for small multiples as follows. If the argument normally only takes a single value, such as n, then a vector of those values can be specified, one for each small multiple. If the argument normally can take a vector, such as palette, then a list of those vectors (or values) can be specified, one for each small multiple.

Examples

Run this code

data(World, Europe, rivers)

qtm(rivers)

## Not run: 
# tm_shape(Europe) +
#     tm_fill() +
# tm_shape(rivers) +
#     tm_lines(col="black", lwd="scalerank", scale=2, legend.lwd.show = FALSE) +
# tm_layout("Rivers of Europe") +
# tm_style_cobalt()
# ## End(Not run)
	
### Demo to visualise the route of the Amstel Gold Race, a professional cycling race
## Not run: 
# 
# tmpdir <- tempdir()
# tmpfile <- tempfile()
# download.file("http://www.gpstracks.nl/routes-fiets/f-limburg-amstel-gold-race-2014.zip", 
# 			  tmpfile, mode="wb")
# unzip(tmpfile, exdir=tmpdir)
# 
# # read GPX file
# AGR <- read_GPX(file.path(tmpdir, "f-limburg-amstel-gold-race-2014.gpx"))
# 
# # read OSM of Zuid-Limburg
# Limburg_OSM <- read_osm(AGR$tracks, ext=1.05)
# 
# # change route part names
# levels(AGR$tracks$name) <- paste(c("First", "Second", "Third", "Final"), "loop")
# AGR$tracks_offset2 <- offset_line(AGR$tracks, offset=c(.0005,0,-.0005,-.001))
# 
# tm_shape(Limburg_OSM) + 
# 	tm_raster(saturation=.25) +
# 	tm_shape(AGR$tracks_offset2) +
# 	tm_lines(col = "name", lwd = 4, title.col="Amstel Gold Race", palette="Dark2") + 
# 	tm_shape(AGR$waypoints) +
# 	tm_bubbles(size=.1, col="gold", border.col = "black") + 
# 	tm_text("name", size = .75, bg.color="white", bg.alpha=.25, auto.placement = .25) +
# 	tm_legend(position=c("right", "top"), frame=TRUE, bg.color = "gold") +
# 	tm_view(basemaps = "Esri.WorldTopoMap")
# ## End(Not run)
# TIP: check out these examples in view mode, enabled with tmap_mode("view")