This element specifies the map layout. The main function tm_layout
controls title, margins, aspect ratio, colors, frame, legend, among many other things. The function tm_legend
is a shortcut to access all legend.
arguments without this prefix. The other functions are wrappers for two purposes: tm_format
specifies position related layout settings such as margins, and tm_style
specifies general styling related layout settings such as colors and font. Typically, the former functions are shape dependent, and the latter functions are shape independent. See details for predefined styles and formats. With tmap.style
, a default style can be specified. Multiple tm_layout
elements (or wrapper functions) can be stacked: called arguments will be overwritten.
Usage
tm_layout(
title,
scale,
title.size,
bg.color,
aes.color,
aes.palette,
attr.color,
sepia.intensity,
saturation,
frame,
frame.lwd,
frame.double.line,
asp,
outer.margins,
inner.margins,
between.margin,
outer.bg.color,
fontface,
fontfamily,
compass.type,
earth.boundary,
earth.boundary.color,
earth.boundary.lwd,
earth.datum,
space.color,
legend.show,
legend.only,
legend.outside,
legend.outside.position,
legend.outside.size,
legend.position,
legend.stack,
legend.just,
legend.width,
legend.height,
legend.hist.height,
legend.hist.width,
legend.title.color,
legend.title.size,
legend.title.fontface,
legend.title.fontfamily,
legend.text.color,
legend.text.size,
legend.text.fontface,
legend.text.fontfamily,
legend.hist.size,
legend.format,
legend.frame,
legend.frame.lwd,
legend.bg.color,
legend.bg.alpha,
legend.hist.bg.color,
legend.hist.bg.alpha,
title.snap.to.legend,
title.position,
title.color,
title.fontface,
title.fontfamily,
title.bg.color,
title.bg.alpha,
panel.show,
panel.labels,
panel.label.size,
panel.label.color,
panel.label.fontface,
panel.label.fontfamily,
panel.label.bg.color,
panel.label.height,
panel.label.rot,
main.title,
main.title.size,
main.title.color,
main.title.fontface,
main.title.fontfamily,
main.title.position,
attr.outside,
attr.outside.position,
attr.outside.size,
attr.position,
attr.just,
design.mode
)
tm_legend(...)
tm_style(style, ...)
tm_format(format, ...)
Arguments
- title
Global title of the map. For small multiples, multiple titles can be specified. The title is drawn inside the map. Alternatively, use
panel.labels
to print the map as a panel, with the title inside the panel header (especially useful for small multiples). Another alternative is themain.title
which prints a title above the map. Titles for the legend items are specified at the layer functions (e.g.tm_fill
).- scale
numeric value that serves as the global scale parameter. All font sizes, symbol sizes, border widths, and line widths are controlled by this value. Each of these elements can be scaled independently with the
scale
,lwd
, orsize
arguments provided by thetmap-elements
.- title.size
Relative size of the title
- bg.color
Background color. By default it is
"white"
. A recommended alternative for choropleths is light grey (e.g.,"grey85"
).- aes.color
Default color values for the aesthetics layers. Should be a named vector with the names chosen from:
fill
,borders
,symbols
,dots
,lines
,text
,na
. Use"#00000000"
for transparency.- aes.palette
Default color palettes for the aesthetics. It takes a list of three items:
seq
for sequential palettes,div
for diverging palettes, andcat
for categorical palettes. By default, Color Brewer palettes (seetmaptools::palette_explorer()
) are used. It is also possible provide a vector of colors for any of these items.- attr.color
Default color value for map attributes
- sepia.intensity
Number between 0 and 1 that defines the amount of sepia effect, which gives the map a brown/yellowish flavour. By default this effect is disabled (
sepia.intensity=0
). All colored used in the map are adjusted with this effect.- saturation
Number that determines how much saturation (also known as chroma) is used:
saturation=0
is greyscale andsaturation=1
is normal. A number larger than 1 results in very saturated maps. All colored used in the map are adjusted with this effect. Hacking tip: use a negative number.- frame
Either a boolean that determines whether a frame is drawn, or a color value that specifies the color of the frame.
- frame.lwd
width of the frame
- frame.double.line
draw a double frame line border?
- asp
Aspect ratio. The aspect ratio of the map (width/height). If
NA
, it is determined by the bounding box (see argumentbbox
oftm_shape
), theouter.margins
, and theinner.margins
. If0
, then the aspect ratio is adjusted to the aspect ratio of the device.- outer.margins
Relative margins between device and frame. Vector of four values specifying the bottom, left, top, and right margin. Values are between 0 and 1. When facets are created, the outer margins are the margins between the outer panels and the device borders (see also
between.margin
)- inner.margins
Relative margins inside the frame. Vector of four values specifying the bottom, left, top, and right margin. Values are between 0 and 1. By default, 0 for each side if master shape is a raster, otherwise 0.02.
- between.margin
Margin between facets (small multiples) in number of text line heights. The height of a text line is automatically scaled down based on the number of facets.
- outer.bg.color
Background color outside the frame.
- fontface
global font face for the text in the map. It can also be set locally per element (see e.g.
title.fontface
).- fontfamily
global font family for the text in the map. It can also be set locally per (see e.g.
title.fontfamily
).- compass.type
type of compass, one of:
"arrow"
,"4star"
,"8star"
,"radar"
,"rose"
. Of course, only applicable if a compass is shown. The compass type can also be set withintm_compass
.- earth.boundary
Logical that determines whether the boundaries of the earth are shown or a bounding box that specifies the boundaries (an
sf
bbox object, seest_bbox
, or any object that can be read bybb
). By default, the boundaries arec(-180, -90, 180, 90)
. Useful for projected world maps. Often, it is useful to crop both poles (e.g., withc(-180, -88, 180, 88)
).- earth.boundary.color
Color of the earth boundary.
- earth.boundary.lwd
Line width of the earth boundary.
- earth.datum
Geodetic datum to determine the earth boundary. By default epsg
4326
(long/lat).- space.color
Color of the space, i.e. the region inside the frame, and outside the earth boundary.
- legend.show
Logical that determines whether the legend is shown.
- legend.only
logical. Only draw the legend (without map)? Particularly useful for small multiples with a common legend.
- legend.outside
Logical that determines whether the legend is plot outside of the map/facets. Especially useful when using facets that have a common legend (i.e. with
free.scales=FALSE
).- legend.outside.position
Character that determines the outside position of the legend. Only applicable when
legend.outside=TRUE
. One of:"right"
,"left"
,"top"
, or"bottom"
.- legend.outside.size
Numeric value that determines the relative size of the legend, when
legend.outside=TRUE
. If the first value oflegend.outside.position
is"top"
or"bottom"
, then it is the width of the legend, else it is the height of the legend. Note that the actual height or width of the legend is determined by the content of the legend (and the used font sizes). This argument specifies the upperbound of the width or height.- legend.position
Position of the legend. Vector of two values, specifying the x and y coordinates. Either this vector contains
"left"
,"LEFT"
,"center"
,"right"
, or"RIGHT"
for the first value and"top"
,"TOP"
,"center"
,"bottom"
, or"BOTTOM"
for the second value, or this vector contains two numeric values between 0 and 1 that specifies the x and y coordinates of the left bottom corner of the legend. The uppercase values correspond to the position without margins (so tighter to the frame). By default, it is automatically placed in the corner with most space based on the (first) shape object. Iflegend.outside=TRUE
, this argument specifies the legend position within the outside panel.- legend.stack
Value that determines how different legends are stacked:
"vertical"
or"horizontal"
. To stack items within a same legend, look at"legend.is.portrait"
in the specific layer calls.- legend.just
Justification of the legend relative to the point coordinates. The first value specifies horizontal and the second value vertical justification. Possible values are:
"left"
,"right"
,"center"
,"bottom"
, and"top"
. Numeric values of 0 specify left/bottom alignment and 1 right/top alignment. This option is only used, iflegend.position
is specified by numeric coordinates.- legend.width
width of the legend. This number is relative to the map area (so 1 means the whole map width). If it is a negative number, it will be the exact legend width. If it is a positive number (by default), it will be the maximum legend width; the actual legend width will be decreased automatically based on the legend content and font sizes.or Default color value for map attributes
- legend.height
height of the legend. If it is a negative number, it will be the exact legend height. If it is a positive number (by default), it will be the maximum legend height; the actual legend height will be decreased automatically based on the legend content and font sizes.
- legend.hist.height
height of the histogram. This height is initial. If the total legend is downscaled to
legend.height
, the histogram is downscaled as well.- legend.hist.width
width of the histogram. By default, it is equal to the
legend.width
.- legend.title.color
color of the legend titles
- legend.title.size
Relative font size for the legend title
- legend.title.fontface
font face for the legend title. By default, set to the global parameter
fontface
.- legend.title.fontfamily
font family for the legend title. By default, set to the global parameter
fontfamily
.- legend.text.color
color of the legend text
- legend.text.size
Relative font size for the legend text elements
- legend.text.fontface
font face for the legend text labels. By default, set to the global parameter
fontface
.- legend.text.fontfamily
font family for the legend text labels. By default, set to the global parameter
fontfamily
.- legend.hist.size
Relative font size for the choropleth histogram
- legend.format
list of formatting options for the legend numbers. Only applicable for layer functions (such as
tm_fill
) wherelabels
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
,text.or.more
, andbig.num.abbr
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
.- 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
.- 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.frame
either a logical that determines whether the legend is placed inside a frame, or a color that directly specifies the frame border color.
- legend.frame.lwd
line width of the legend frame (applicable if
legend.frame
isTRUE
or a color)- legend.bg.color
Background color of the legend. Use
TRUE
to match with the overall background colorbg.color
.- legend.bg.alpha
Transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the
legend.bg.color
is used (normally 1).- legend.hist.bg.color
Background color of the histogram
- legend.hist.bg.alpha
Transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the
legend.hist.bg.color
is used (normally 1).- title.snap.to.legend
Logical that determines whether the title is part of the legend. By default
FALSE
, unless the legend is drawn outside the map (seelegend.outside
).- title.position
Position of the title. Vector of two values, specifying the x and y coordinates. Either this vector contains "left", "LEFT", "center", "right", or "RIGHT" for the first value and "top", "TOP", "center", "bottom", or "BOTTOM" for the second value, or this vector contains two numeric values between 0 and 1 that specifies the x and y coordinates of the tile. The uppercase values correspond to the position without margins (so tighter to the frame). By default the title is placed on top of the legend (determined by
legend.position
).- title.color
color of the title
- title.fontface
font face for the title. By default, set to the global parameter
fontface
.- title.fontfamily
font family for the title. By default, set to the global parameter
fontfamily
.- title.bg.color
background color of the title. Use
TRUE
to match with the overall background colorbg.color
. By default, it isTRUE
iflegend.frame
isTRUE
or a color.- title.bg.alpha
Transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the
title.bg.color
is used (normally 1).- panel.show
Logical that determines if the map(s) are shown as panels. If
TRUE
, the title will be placed in the panel header instead of inside the map. By default, it isTRUE
when small multiples are created with theby
variable. (Seetm_facets
)- panel.labels
Panel labels. Only applicable when
panel.show
isTRUE
. For cross tables facets, it should be a list containing the row names in the first, and column names in the second item.- panel.label.size
Relative font size of the panel labels
- panel.label.color
Font color of the panel labels
- panel.label.fontface
font face for the panel labels. By default, set to the global parameter
fontface
.- panel.label.fontfamily
font family for the panel labels. By default, set to the global parameter
fontfamily
.- panel.label.bg.color
Background color of the panel labels
- panel.label.height
Height of the labels in number of text line heights.
- panel.label.rot
Rotation angles of the panel labels. Vector of two values: the first is the rotation angle (in degrees) of the row panels, which are only used in cross-table facets (when
tm_facets
'sby
is specified with two variables). The second is the rotation angle of the column panels.- main.title
Title that is printed above the map (or small multiples). When multiple pages are generated (see
along
argument oftm_facets
), a vector can be provided. By default, the main title is only printed when thisalong
argument is specified.- main.title.size
Size of the main title
- main.title.color
Color of the main title
- main.title.fontface
font face for the main title. By default, set to the global parameter
fontface
.- main.title.fontfamily
font family for the main title. By default, set to the global parameter
fontfamily
.- main.title.position
Position of the main title. Either a numeric value between 0 (left) and 1 (right), or a character value:
"left"
,"center"
, or"right"
.- attr.outside
Logical that determines whether the attributes are plot outside of the map/facets.
- attr.outside.position
Character that determines the outside position of the attributes:
"top"
or"bottom"
. Only applicable whenattr.outside=TRUE
. If the legend is also drawn outside (withlegend.outside=TRUE
) and on the same side of the map (e.g. also"top"
or"bottom"
), the attributes are placed between the map and the legend. This can be changed by settingattr.outside.position
to"TOP"
or"BOTTOM"
: in this case, the attributes are placed above respectively below the legend.- attr.outside.size
Numeric value that determines the relative height of the attribute viewport, when
attr.outside=TRUE
.- attr.position
Position of the map attributes, which are
tm_credits
,tm_scale_bar
,tm_compass
, andtm_minimap
. Vector of two values, specifying the x and y coordinates. The first value is"left"
,"LEFT"
,"center"
,"right"
, or"RIGHT"
, and the second value"top"
,"TOP"
,"center"
,"bottom"
, or"BOTTOM"
. The uppercase values correspond to the position without margins (so tighter to the frame). Positions can also be set separately in the map attribute functions. Ifattr.outside=TRUE
, this argument specifies the position of the attributes within the outside panel.- attr.just
Justification of the attributes relative to the point coordinates. The first value specifies horizontal and the second value vertical justification. Possible values are:
"left"
,"right"
,"center"
,"bottom"
, and"top"
. Numeric values of 0 specify left/bottom alignment and 1 right/top alignment. This option is only used, ifattr.position
is specified by numeric coordinates. It can also be specified per attribute function.- design.mode
Not used anymore, since it is now only a tmap option: see
tmap_options
.- ...
other arguments from
tm_layout
- style
name of the style
- format
name of the format
Details
Predefined styles:
"white" | White background, commonly used colors (default) |
"gray" /"grey" | Grey background, useful to highlight sequential palettes (e.g. in choropleths) |
"natural" | Emulation of natural view: blue waters and green land |
"bw" | Greyscale, obviously useful for greyscale printing |
"classic" | Classic styled maps (recommended) |
"cobalt" | Inspired by latex beamer style cobalt |
"albatross" | Inspired by latex beamer style albatross |
"beaver" | Inspired by latex beamer style beaver |
--------------------------- | --------------------------------------------------------------------------------------------------- |
Predefined formats
"World" | Format specified for world maps |
"World_wide" | Format specified for world maps with more space for the legend |
"NLD" | Format specified for maps of the Netherlands |
"NLD_wide" | Format specified for maps of the Netherlands with more space for the legend |
--------------------------- | --------------------------------------------------------------------------------------------------- |
References
Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, doi:10.18637/jss.v084.i06
Examples
data(World, land)
tm_shape(World) +
tm_fill("pop_est_dens", style="kmeans", title="Population density") +
tm_style("albatross", frame.lwd=10) + tm_format("World", title="The World")
if (FALSE) {
tm_shape(land) +
tm_raster("elevation", breaks=c(-Inf, 250, 500, 1000, 1500, 2000, 2500, 3000, 4000, Inf),
palette = terrain.colors(9), title="Elevation", midpoint = NA) +
tm_shape(World, is.master=TRUE, projection = "+proj=eck4") +
tm_borders("grey20") +
tm_graticules(labels.size = .5) +
tm_text("name", size="AREA") +
tm_compass(position = c(.65, .15), color.light = "grey90") +
tm_credits("Eckert IV projection", position = c("right", "BOTTOM")) +
tm_style("classic") +
tm_layout(bg.color="lightblue",
inner.margins=c(.04,.03, .02, .01),
earth.boundary = TRUE,
space.color="grey90") +
tm_legend(position = c("left", "bottom"),
frame = TRUE,
bg.color="lightblue")
}
tm_shape(World, projection="+proj=robin") +
tm_polygons("HPI", palette="div", n=7,
title = "Happy Planet Index") +
tm_credits("Robinson projection", position = c("right", "BOTTOM")) +
tm_style("natural", earth.boundary = c(-180, -87, 180, 87), inner.margins = .05) +
tm_legend(position=c("left", "bottom"), bg.color="grey95", frame=TRUE)
# Example to illustrate the type of titles
tm_shape(World) +
tm_polygons(c("income_grp", "economy"), title = c("Legend Title 1", "Legend Title 2")) +
tm_layout(main.title = "Main Title",
main.title.position = "center",
main.title.color = "blue",
title = c("Title 1", "Title 2"),
title.color = "red",
panel.labels = c("Panel Label 1", "Panel Label 2"),
panel.label.color = "purple",
legend.text.color = "brown")
if (FALSE) {
# global option tmap.style demo
# get current style
current.style <- tmap_style()
qtm(World, fill = "economy", format = "World")
tmap_style("col_blind")
qtm(World, fill = "economy", format = "World")
tmap_style("cobalt")
qtm(World, fill = "economy", format = "World")
# set to current style
tmap_style(current.style)
}
# TIP: check out these examples in view mode, enabled with tmap_mode("view")