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,
lwd.legend.col = NA,
n = 5,
style = ifelse(is.null(breaks), "pretty", "fixed"),
style.args = list(),
as.count = NA,
breaks = NULL,
interval.closure = "left",
palette = NULL,
labels = NULL,
drop.levels = FALSE,
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,
interactive = TRUE,
popup.vars = NA,
popup.format = list(),
zindex = NA,
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 byscale
. 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
.- lwd.legend.col
color of lines that are shown in the legend for the lwd aesthetic. By default, the middle color of the
palette
is taken.- 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 gradient options are"cat"
,"fixed"
,"sd"
,"equal"
,"pretty"
,"quantile"
,"kmeans"
,"hclust"
,"bclust"
,"fisher"
,"jenks"
,"dpih"
,"headtails"
, and"log10_pretty"
. 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 gradient options (except"log10_pretty"
), see the details inclassIntervals
(extra arguments can be passed on viastyle.args
). Continuous gradient options are"cont"
,"order"
, and"log10"
. The first maps the values ofcol
to a smooth gradient, the second maps the order of values ofcol
to a smooth gradient, and the third uses a logarithmic transformation. The numeric variable can be either regarded as a continuous variable or a count (integer) variable. Seeas.count
.- style.args
arguments passed on to
classIntervals
, the function that determine color classes (see alsostyle
).- as.count
when
col
is a numeric variable, should it be processed as a count variable? For instance, ifstyle = "pretty"
,n = 2
, and the value range of the variable is 0 to 10, then the column classes foras.count = TRUE
are 0; 1 to 5; 6 to 10 (note that 0 is regarded as an own category) whereas foras.count = FALSE
they are 0 to 5; 5 to 10. Only applicable ifstyle
is"pretty"
,"fixed"
, or"log10_pretty"
. By default,TRUE
ifstyle
is one of these, and the variable is an integer.- breaks
in case
style=="fixed"
, breaks should be specified. Thebreaks
argument can also be used whenstyle="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 ifcol
is a numeric variable. Ifas.count = TRUE
,inverval.closure
is always set to"left"
.- 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 fromtm_layout
's argumentaes.palette
, which typically depends on the style. The type of palette fromaes.palette
is automatically determined, but can be overwritten: use"seq"
for sequential,"div"
for diverging, and"cat"
for categorical.- labels
labels of the classes
- drop.levels
should unused classes be omitted?
FALSE
by default.- 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 (seestyle
) is mapped to the middle color. Only applies whencol
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). IfFALSE
, 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
, anddigits
(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"
, andtext.separator
,text.less.than
, andtext.or.more
are used. Also, the numbers are automatically rounded to millions or billions if applicable.- format
By default,
"f"
, i.e. the standard notationxxx.xxx
, is used. Ifscientific=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.- big.num.abbr
Vector that defines whether and which abbrevations are used for large numbers. It is a named numeric vector, where the name indicated the abbreviation, and the number the magnitude (in terms on numbers of zero). Numbers are only abbrevation when they are large enough. Set it to
NA
to disable abbrevations. The default isc("mln" = 6, "bln" = 9)
. For layers wherestyle
is set tolog10
orlog10_pretty
, the default isNA
.- prefix
Prefix of each number
- suffix
Suffix of each number
- 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
.- html.escape
Logical that determins whther HTML code is escaped in the popups in view mode. By default
TRUE
. If set toFALSE
HTML code can be added, e.g. to added white space via
.- ...
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 whenlegend.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 whenlegend.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 (seetmap_mode
).- interactive
logical that determines whether this layer is interactive in view mode (e.g. hover text, popup, and click event in shiny apps)
- popup.vars
names of data variables that are shown in the popups in
"view"
mode. IfNA
(default), only aesthetic variables (i.e. specified bycol
andlwd
) are shown). If they are not specified, all variables are shown. Set popup.vars toFALSE
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 ofpopup.vars
. Also, a (named) list of lists can be provided. In that case, each list of formatting options is applied to the named variable.- zindex
zindex of the pane in view mode. By default, it is set to the layer number plus 400. By default, the tmap layers will therefore be placed in the custom panes
"tmap401"
,"tmap402"
, etc., except for the base tile layers, which are placed in the standard"tile"
. This parameter determines both the name of the pane and the z-index, which determines the pane order from bottom to top. For instance, ifzindex
is set to 500, the pane will be named"tmap500"
.- 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. Set
group = NULL
to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified intm_shape
).- auto.palette.mapping
deprecated. It has been replaced by
midpoint
for numeric variables andstretch.palette
for categorical variables.- max.categories
deprecated. It has moved to
tmap_options
.- ...
these arguments are passed on to
classIntervals
, the function that determine color classes (see alsostyle
).
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:10.18637/jss.v084.i06