# tm_layout

From tmap v1.11
0th

Percentile

##### Layout of cartographic maps

This element specifies the map layout. The main function tm_layout controlls 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: the tm_format_ functions specify position related layout settings such as margins, and the tm_style_ functions specify 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 the global option 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 = NA, scale = 1, title.size = 1.3, bg.color = "white",
aes.color = c(fill = "grey85", borders = "grey40", symbols = "grey60", dots
= "black", lines = "red", text = "black", na = "grey75"),
aes.palette = list(seq = "YlOrBr", div = "RdYlGn", cat = "Set3"),
attr.color = "black", sepia.intensity = 0, saturation = 1,
frame = TRUE, frame.lwd = 1, frame.double.line = FALSE, asp = NA,
outer.margins = rep(0.02, 4), inner.margins = NA, between.margin = 0.5,
outer.bg.color = NULL, fontface = "plain", fontfamily = "",
compass.type = "arrow", earth.boundary = FALSE,
earth.boundary.color = attr.color, earth.boundary.lwd = 1,
earth.datum = "WGS84", space.color = NULL, legend.show = TRUE,
legend.only = FALSE, legend.outside = NA,
legend.outside.position = "right", legend.outside.size = 0.3,
legend.position = NULL, legend.stack = c("vertical", "horizontal"),
legend.just = c("left", "bottom"), legend.width = 0.4,
legend.height = 0.9, legend.hist.height = 0.3,
legend.hist.width = legend.width, legend.title.size = 1.1,
legend.text.size = 0.7, legend.hist.size = 0.7, legend.format = list(fun
= NULL, scientific = FALSE, digits = NA, text.separator = "to", text.less.than
= "Less than", text.or.more = "or more"), legend.frame = FALSE,
legend.text.color = attr.color, legend.bg.color = NA,
legend.bg.alpha = 1, legend.hist.bg.color = NA,
legend.hist.bg.alpha = 1, title.snap.to.legend = NA,
title.position = c("left", "top"), title.color = attr.color,
title.bg.color = NA, title.bg.alpha = 1, panel.show = NA,
panel.labels = NA, panel.label.size = 1, panel.label.color = "black",
panel.label.bg.color = "grey80", panel.label.height = 1.25,
panel.label.rot = c(90, 0), main.title = NA, main.title.size = 1.5,
main.title.color = "black", main.title.position = "left",
attr.outside = FALSE, attr.outside.position = "bottom",
attr.outside.size = NA, attr.position = c("right", "bottom"),
attr.just = c("left", "bottom"), design.mode = FALSE,
basemaps = c("CartoDB.Positron", "OpenStreetMap", "Esri.WorldTopoMap"),
basemaps.alpha = c(1, 1, 1), bg.overlay = NULL, bg.overlay.alpha = 0)tm_legend(...)tm_format_World(title = NA, inner.margins = c(0, 0.05, 0.025, 0.01),
legend.position = c("left", "bottom"), attr.position = c("right",
"bottom"), scale = 0.8, ...)tm_format_World_wide(title = NA, inner.margins = c(0, 0.2, 0.025, 0.01),
legend.position = c("left", "bottom"), attr.position = c("right",
"bottom"), scale = 0.8, ...)tm_format_Europe(title = NA, title.position = c("left", "top"),
legend.position = c("right", "top"), legend.just = c("right", "top"),
attr.position = c("right", "bottom"), legend.frame = TRUE,
inner.margins = c(0, 0, 0, 0), ...)tm_format_Europe2(title = NA, title.position = c("left", "top"),
legend.position = c("left", "top"), legend.outside = TRUE,
legend.outside.size = 0.2, legend.just = c("right", "top"),
attr.position = c("right", "bottom"), inner.margins = c(0, 0, 0, 0), ...)tm_format_Europe_wide(title = NA, title.position = c("left", 0.85),
title.snap.to.legend = TRUE, legend.position = c("left", 0.85),
legend.just = c("left", "top"), attr.position = c("left", "bottom"),
inner.margins = c(0, 0.25, 0, 0), ...)tm_format_NLD(title = NA, frame = FALSE, inner.margins = c(0.02, 0.2,
0.06, 0.02), legend.position = c("left", "top"), attr.position = c("left",
"bottom"), ...)tm_format_NLD_wide(title = NA, frame = FALSE, inner.margins = c(0.02, 0.3,
0.06, 0.02), legend.position = c("left", "top"), attr.position = c("left",
"bottom"), ...)tm_style_white(...)tm_style_gray(bg.color = "grey85", aes.color = c(fill = "grey70", borders =
"grey20", symbols = "grey50", dots = "black", lines = "red", text = "black",
na = "grey60"), ...)tm_style_natural(bg.color = "lightskyblue1", aes.color = c(fill =
"darkolivegreen3", borders = "black", symbols = "tomato2", dots = "firebrick",
lines = "steelblue", text = "black", na = "white"), aes.palette = list(seq =
"YlGn", div = "RdYlGn", cat = "Set3"), attr.color = "black",
space.color = "white", legend.frame = TRUE, legend.bg.color = "grey90",
earth.boundary = TRUE, basemaps = "Esri.NatGeoWorldMap",
basemaps.alpha = 1, ...)tm_style_grey(bg.color = "grey85", aes.color = c(fill = "grey70", borders =
"grey20", symbols = "grey50", dots = "black", lines = "red", text = "black",
na = "grey60"), ...)tm_style_cobalt(bg.color = "#002240", aes.color = c(fill = "#0088FF",
borders = "#002240", symbols = "#FF9D00", dots = "#FF9D00", lines = "#FFEE80",
text = "white", na = "grey60"), aes.palette = list(seq = "YlGn", div =
"RdYlGn", cat = "Set3"), attr.color = "white",
basemaps = "CartoDB.DarkMatter", basemaps.alpha = 0.5, ...)tm_style_col_blind(bg.color = "white", aes.color = c(fill = "grey85",
borders = "black", symbols = "#D55E00", dots = "#0072B2", lines = "#009E73",
text = "black", na = "white"), aes.palette = list(seq = "Blues", div =
"RdBu", cat = c("#D55E00", "#56B4E9", "#E69F00", "#009E73", "#F0E442",
"#0072B2", "#CC79A7")), attr.color = "black", ...)tm_style_albatross(bg.color = "#00007F", aes.color = c(fill = "#4C4C88",
borders = "#00004C", symbols = "#BFBFFF", dots = "#BFBFFF", lines = "#BFBFFF",
text = "#FFE700", na = "grey60"), aes.palette = list(seq = "YlOrRd", div =
"RdYlGn", cat = "Set3"), attr.color = "#BFBFFF",
basemaps = "CartoDB.DarkMatter", basemaps.alpha = 0.5, ...)tm_style_beaver(bg.color = "#FFFFFF", aes.color = c(fill = "#FFE200",
borders = "#000000", symbols = "#A30000", dots = "#A30000", lines = "#A30000",
text = "#000000", na = "#E0E0E0"), aes.palette = list(seq = "YlOrBr", div =
"RdYlGn", cat = "Dark2"), attr.color = "black", ...)tm_style_bw(saturation = 0, ...)tm_style_classic(sepia.intensity = 0.7, fontfamily = "serif",
frame.double.line = TRUE, compass.type = "rose",
basemaps = "Esri.WorldTopoMap", basemaps.alpha = 0.5, ...)
##### 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 the main.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 controled by this value. Each of these elements can be scaled independantly with the scale, lwd, or size arguments provided by the tmap-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, and cat for categorical palettes. By default, Color Brewer palettes (see (see tmaptools::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 and saturation=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 argument bbox of tm_shape), the outer.margins, and the inner.margins. If 0, 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

font face of all text in the map.

fontfamily

font family of the text labels.

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 within tm_compass.

earth.boundary

Logical that determines whether the boundaries of the earth are shown or an object that specifies the boundaries. This object can be a vector of size four, a 2 by 2 matrix (bounding box), or an extent object. By default, the boundaries are c(-180, 180, -90, 90). Useful for rojected world maps. Often, it is useful to crop both poles (e.g., with c(-180, 180, -88, 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 "WGS84", other frequently used datums are "NAD83" and "NAD27". Any other PROJ.4 character string can be used.

space.color

Color of the space, i.e. the region inside the frame, and outsise 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 of legend.outside.position is "top" or "bottom", then it is the width of the legend, else it is the height of the legend.

legend.position

Position of the legend. Vector of two values, specifing 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. If legend.outside=TRUE, this argument specifies the legend position within the outside panel.

legend.stack

Value that determines how the legend items are stacked: "vertical" or "horizontal".

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, if legend.position is specified by numeric coordinates.

legend.width

width of the legend. 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.

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 hight 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.size

Relative font size for the legend title

legend.text.size

Relative font size for the legend text elements

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

either a logical that determines whether the legend is placed inside a frame, or a color that directly specifies the frame border color. The width of the frame is automatically determined, but is upper-bounded by legend.width.

legend.text.color

color of the legend text

legend.bg.color

Background color of the legend. Use TRUE to match with the overall background color bg.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 (see legend.outside).

title.position

Position of the title. Vector of two values, specifing 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.bg.color

background color of the title. Use TRUE to match with the overall background color bg.color. By default, it is TRUE if legend.frame is TRUE 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 is TRUE when small multiples are created with the by variable. (See tm_facets)

panel.labels

Panel labels. Only applicable when panel.show is TRUE. 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.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's by 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 of tm_facets), a vector can be provided. By default, the main title is only printed when this along argument is specified.

main.title.size

Size of the main title

main.title.color

Color of the main title

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 when attr.outside=TRUE. If the legend is also drawn outside (with legend.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 setting attr.outside.position to "TOP" or "BOTTOM": in this case, the attributes are placed above respecvitely 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 and tm_compass. Vector of two values, specifing 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 fuctions. If attr.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, if attr.position is specified by numeric coordinates. It can also be specified per attribute function.

design.mode

Logical that enables the design mode. If TRUE, inner and outer margins, legend position, aspect ratio are explicitely shown. Also, feedback text in the console is given.

basemaps

vector of one or more names of baselayer maps used in the interactive view mode. See tm_view.

basemaps.alpha

alpha transparancy (opacity) of the basemaps. See tm_view.

bg.overlay

Not used anymore. See tm_view.

bg.overlay.alpha

Not used anymore. See tm_view.

...

other arguments from tm_layout

##### Details

Predefined styles:

 tm_style_white White background, commonly used colors (default) tm_style_gray/_grey Grey background, useful to highlight sequential palettes (e.g. in choropleths) tm_style_natural Emulation of natural view: blue waters and green land tm_style_bw Greyscale, obviously useful for greyscale printing tm_style_classic Classic styled maps (recommended) tm_style_cobalt Inspired by latex beamer style cobalt tm_style_albatross Inspired by latex beamer style albatross tm_style_beaver Inspired by latex beamer style beaver --------------------------- ---------------------------------------------------------------------------------------------------

Predefined formats

 tm_format_World Format specified for world maps tm_format_World_wide Format specified for world maps with more space for the legend tm_format_Europe Format specified for maps of Europe tm_format_Europe_wide Format specified for maps of Europe with more space for the legend tm_format_NLD Format specified for maps of the Netherlands tm_format_NLD_wide Format specified for maps of the Netherlands with more space for the legend --------------------------- ---------------------------------------------------------------------------------------------------

vignette("tmap-nutshell")

##### Aliases
• tm_layout
• tm_legend
• tm_format_World
• tm_format_World_wide
• tm_format_Europe
• tm_format_Europe2
• tm_format_Europe_wide
• tm_format_NLD
• tm_format_NLD_wide
• tm_style_white
• tm_style_gray
• tm_style_natural
• tm_style_grey
• tm_style_cobalt
• tm_style_col_blind
• tm_style_albatross
• tm_style_beaver
• tm_style_bw
• tm_style_classic
##### Examples
# NOT RUN {
data(World, land)

tm_shape(World) +
tm_fill("pop_est_dens", style="kmeans", title="Population density") +
tm_format_World(title="The World") + tm_style_albatross(frame.lwd=10)

# }
# NOT RUN {
tm_shape(land) +
tm_raster("elevation", breaks=c(-Inf, 250, 500, 1000, 1500, 2000, 2500, 3000, 4000, Inf),
palette = terrain.colors(9), title="Elevation", auto.palette.mapping = FALSE) +
tm_shape(World, is.master=TRUE) +
tm_borders("grey20") +
tm_grid(projection="longlat", 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_layout(inner.margins=c(.04,.03, .02, .01),
earth.boundary = TRUE,
space.color="grey90") +
tm_style_classic(bg.color="lightblue") +
tm_legend(position = c("left", "bottom"),
frame = TRUE,
bg.color="lightblue")
# }
# NOT RUN {

WorldOne <- rgeos::gUnaryUnion(World)
tm_shape(World, projection="wintri") +
tm_fill("HPI", palette="div", auto.palette.mapping = FALSE, n=7,
title = "Happy Planet Index") +
tm_shape(WorldOne) +
tm_borders() +
tm_grid(projection = "longlat") +
tm_credits("Winkel Tripel projection", position = c("right", "BOTTOM")) +
tm_style_natural(earth.boundary = c(-180,180,-87,87), inner.margins = .05) +
tm_legend(position=c("left", "bottom"), bg.color="grey95", frame=TRUE)

# }
# NOT RUN {
# 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)
# }
# NOT RUN {
# TIP: check out these examples in view mode, enabled with tmap_mode("view")
# }

Documentation reproduced from package tmap, version 1.11, License: GPL-3

### Community examples

Looks like there are no examples yet.