Learn R Programming

tmap (version 2.1-1)

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,
  interval.closure = "left", palette = NULL, labels = NULL,
  midpoint = NULL, stretch.palette = TRUE, contrast = NA, colorNA = NA,
  textNA = "Missing", showNA = NA, colorNULL = 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.col.reverse = FALSE,
  legend.lwd.reverse = FALSE, legend.hist = FALSE, legend.hist.title = NA,
  legend.col.z = NA, legend.lwd.z = NA, legend.hist.z = NA, id = NA,
  popup.vars = NA, popup.format = list(), group = NA,
  auto.palette.mapping = NULL, max.categories = NULL)

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.

n

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 categorical 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. The breaks argument can also be used when style="cont". In that case, the breaks are mapped evenly to the sequential or diverging color palette.

interval.closure

value that determines whether where the intervals are closed: "left" or "right". Only applicable if col is a numeric variable.

palette

a palette name or a vector of colors. See tmaptools::palette_explorer() for the named palettes. Use a "-" as prefix to reverse the palette. The default palette is taken from tm_layout's argument aes.palette, which typically depends on the style. The type of palette from aes.palette is automatically determined, but can be overwritten: use "seq" for sequential, "div" for diverging, and "cat" for categorical.

labels

labels of the classes

midpoint

The value mapped to the middle color of a diverging palette. By default it is set to 0 if negative and positive values are present. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to NA, which means that the value that corresponds to the middle color class (see style) is mapped to the middle color. Only applies when col is a numeric variable. If it is specified for sequential color palettes (e.g. "Blues"), then this color palette will be treated as a diverging color palette.

stretch.palette

Logical that determines whether the categorical color palette should be stretched if there are more categories than colors. If TRUE (default), interpolated colors are used (like a rainbow). If FALSE, the palette is repeated.

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).

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.

colorNULL

colour for polygons that are shown on the map that are out of scope

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:

fun

Function to specify the labels. It should take a numeric vector, and should return a character vector of the same size. By default it is not specified. If specified, the list items scientific, format, and digits (see below) are not used.

scientific

Should the labels be formatted scientifically? 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 scientifically, 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 value(s) to use to translate "Less than". When a character vector of length 2 is specified, one for each word, these words are aligned when text.to.columns = TRUE

text.or.more

Character value(s) to use to translate "or more". When a character vector of length 2 is specified, one for each word, these words are aligned when text.to.columns = TRUE

text.align

Value that determines how the numbers are aligned, "left", "center" or "right"

. By default "left" for legends in portrait format (legend.is.protrait = TRUE), and "center" otherwise.
text.to.columns

Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default FALSE.

...

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.col.reverse

logical that determines whether the items of the legend regarding the line colors sizes are shown in reverse order, i.e. from bottom to top when legend.col.is.portrait = TRUE and from right to left when legend.col.is.portrait = FALSE

legend.lwd.reverse

logical that determines whether the items of the legend regarding the line widths are shown in reverse order, i.e. from bottom to top when legend.lwd.is.portrait = TRUE and from right to left when legend.lwd.is.portrait = 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)

id

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

popup.vars

names of data variables that are shown in the popups in "view" mode. If NA (default), only aesthetic variables (i.e. specified by col and lwd) are shown). If they are not specified, all variables are shown. Set popup.vars to FALSE to disable popups. When a vector of variable names is provided, the names (if specified) are printed in the popups.

popup.format

list of formatting options for the popup values. See the argument legend.format for options. Only applicable for numeric data variables. If one list of formatting options is provided, it is applied to all numeric variables of popup.vars. Also, a (named) list of lists can be provided. In that case, each list of formatting options is applied to the named variable.

group

name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Groups can either be specified as base or overlay groups in tm_view (arguments base.groups and overlay.groups).

auto.palette.mapping

deprecated. It has been replaced by midpoint for numeric variables and stretch.palette for categorical variables.

max.categories

deprecated. It has moved to tmap_options.

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.

References

Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, DOI

See Also

vignette("tmap-getstarted")

Examples

Run this code
# NOT RUN {
data(World, rivers)

qtm(rivers)

# }
# NOT RUN {
tm_shape(World) +
    tm_fill() +
tm_shape(rivers) +
    tm_lines(col="black", lwd="scalerank", scale=2, legend.lwd.show = FALSE) +
tm_style("cobalt", title = "Rivers of the World") +
tm_format("World")
# }

Run the code above in your browser using DataLab