tmap_options {tmap}

Options for tmap

Description

Get or set global options for tmap. The behaviour of tmap_options is similar to options: all tmap options are retrieved when this function is called without arguments. When arguments are specified, the corresponding options are set, and the old values are silently returned as a list. The function tmap_options_reset is used to reset all options back to the default values (also the style is reset to "white"). Differences with the default values can be shown with tmap_options_diff. The function tmap_options_save can be used to save the current options as a new style. See details below on how to create a new style.

Usage

tmap_options(
  ...,
  unit,
  limits,
  max.categories,
  max.raster,
  basemaps,
  basemaps.alpha,
  overlays,
  overlays.alpha,
  qtm.scalebar,
  qtm.minimap,
  qtm.mouse.coordinates,
  show.messages,
  show.warnings,
  output.format,
  output.size,
  output.dpi,
  output.dpi.animation,
  design.mode = NULL,
  check.and.fix
)

tmap_options_diff()

tmap_options_reset()

tmap_options_save(style)

Arguments

...

options from tm_layout or tm_view. Note that the difference with using tm_layout or tm_view directly, is that options set with tmap_options remain for the entire session (unless changed with tmap_options or tmap_style). It can also be a single unnamed argument which is a named list of options (similar behaviour as options).

unit

this is the default value for the unit argument of tm_shape. It specifies the unit of measurement, which is used in the scale bar and the calculation of density values. By default (when loading the package), it is "metric". Other valid values are "imperial", "km", "m", "mi", and "ft".

limits

this option determines how many facets (small multiples) are allowed for per mode. It should be a vector of two numeric values named facets.view and facets.plot. By default (i.e. when loading the package), it is set to c(facets.view = 4, facets.plot = 64)

max.categories

in case col is the name of a categorical variable in the layer functions (e.g. tm_polygons), this value determines how many categories (levels) it can have maximally. If the number of levels is higher than max.categories, then levels are combined.

max.raster

the maximum size of rasters, in terms of number of raster cells. It should be a vector of two numeric values named plot and view, which determines the size in plotting and viewing mode. The default values are c(plot = 1e7, view = 1e6). Rasters that are larger will be shown at a decreased resolution.

basemaps

default basemaps. Basemaps are normally configured with tm_basemap. When this is not done, the basemaps specified by this option are shown (in view mode). Vector of one or more names of baselayer maps, or NULL if basemaps should be omitted. For options see the list leaflet::providers, which can be previewed at https://leaflet-extras.github.io/leaflet-providers/preview/. Also supports URL's for tile servers, such as "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png". If a named vector is provided, the names are used in the layer control legend (similar to the group argument of tm_basemap. See also overlays, which is the default option for overlay tiles.

basemaps.alpha

default transparency (opacity) value for the basemaps. Can be a vector of values, one for each basemap.

overlays

default overlay tilemaps. Overlays tilemaps are shown as front layer (in contrast to basemaps, which are background layers), so they are only useful when they are semi-transparent. Like basemaps, a vector of tilemaps is expected, or NULL is overlays should be omitted.

overlays.alpha

default transparency (opacity) value for the overlay maps. Can be a vector of values, one for each overlay map.

qtm.scalebar

should a scale bar be added to interactive maps created with qtm. In other words, should tm_scale_bar() be added automatically? The value NA means that the scale bar is only added when qtm is called without arguments or with a search term. The default value is TRUE.

qtm.minimap

should a minimap be added to interactive maps created with qtm. In other words, should tm_minimap() be added automatically? The default value is FALSE.

qtm.mouse.coordinates

should mouse coordinates (and zoom level) be shown in view mode with qtm? In other words, should tm_mouse_coordinates() be added automatically? TRUE by default.

show.messages

should messages be shown?

show.warnings

should warnings be shown?

output.format

The format of the static maps saved with tmap_save without specification of the filename. The default is "png".

output.size

The size of the static maps saved with tmap_save without specification of width and height. The unit is squared inch and the default is 49. This means that square maps (so with aspect ratio 1) will be saved as 7 by 7 inch images and a map with aspect ratio 2 (e.g. most world maps) will be saved as approximately 10 by 5 inch.

output.dpi

The default number of dots per inch for tmap_save.

output.dpi.animation

The default number of dots per inch for tmap_animation.

design.mode

Not used anymore; the design mode can now be set with tmap_design_mode

check.and.fix

Logical that determines whether shapes (sf objects) are checked for validity with st_is_valid and fixed with st_make_valid if needed.

style

style name

Details

The options can be divided into three parts: one part contains the arguments from tm_layout, one part contains the arguments from tm_view, and one part contains options that can only be set with tmap_options. Observe that the options from tm_layout and tm_view can also be set with those functions. It is recommended to use tmap_options when setting specific options during global session. However, options that are only relevant for a specific map can better be set with tm_layout or tm_view.

A new style can be created in two ways. The first approach is to use the function tmap_options_save, which takes a snapshot of the current tmap options. E.g., tmap_options_save("my_style") will save the current tmap options as a style called "my_style". See the examples in which a style called "red" is created. The second way to create a style is to create a list with tmap options and with a attribute called style. This approach is illustrated in the last example, in which a style called "black" is created.

The newly created style, say "my_style", will be accessible globally via tmap_style("my_style") and + tm_style("my_style") until the R session is restarted or tmap is reloaded. In order to save the style for future use or sharing, obtain the option list as follows: my_style <- tmap_options() and save the object my_style in the usual way. Next time, the style can be loaded simply by running tmap_options(my_style), which corresponds to the second way to create a style (see the paragraph above).

See Also

tm_layout, tm_view, and tmap_style

Examples

# load data
data(World)

# get current options
str(tmap_options())

# get current style
tmap_style()

# plot map (with default options)
tm_shape(World) + tm_polygons("HPI")

# change style to cobalt
tmap_style("cobalt")

# observe the changed options
tmap_options_diff()

# plot the map again
tm_shape(World) + tm_polygons("HPI")

##############################
# define red style
##############################

# change the background color
tmap_options(bg.color = "red")

# note that the current style is modified
tmap_style()

# observe the changed options
tmap_options_diff()

# save the current options as style "red"
tmap_options_save("red")

# plot the map again
tm_shape(World) + tm_polygons("HPI")

# the specified arguments of tm_layout and tm_view will override the options temporarily:
tm_shape(World) + tm_polygons("HPI") + tm_layout(bg.color="purple")

# when tm_style_ is called, it will override all options temporarily:
tm_shape(World) + tm_polygons("HPI") + tm_layout(bg.color="purple") + tm_style("classic")

# reset all options
tmap_options_reset()

# check style and options
tmap_style()
tmap_options_diff()

##############################
# define black style
##############################

# create style list with style attribute
black_style  <- structure(
    list(
		bg.color = "black",
		aes.color = c(fill = "grey40", borders = "grey40", 
					  symbols = "grey80", dots = "grey80", 
		              lines = "white", text = "white", 
					  na = "grey30", null = "grey15"),
		aes.palette = list(seq = "plasma", div = "PiYG", cat = "Dark2"),
		attr.color = "white",
		panel.label.color = "white",
		panel.label.bg.color = "grey40",
		main.title.color = "white"
	),
	style = "black"
)

# assign the style
tmap_options(black_style)

# observe that "black" is a new style
tmap_style()

# plot the world map again, this time with the newly created black style
tm_shape(World) +
	tm_polygons("HPI")

# reset all options
tmap_options_reset()