diff --git a/R/data.R b/R/data.R index e291ddb5..3da77ea0 100644 --- a/R/data.R +++ b/R/data.R @@ -1,14 +1,20 @@ #' World and Netherlands map #' -#' Maps of the world and the Netherlands (province and municipality level), class [`sf`][`sf::sf`] +#' Maps of the world and the Netherlands (province and municipality level), +#' class [`sf`][`sf::sf`] #' -#' The default projections for these maps are Eckhart IV (World) and Rijksdriehoekstelsel (Netherlands). See below. The projection can be changed temporarily for plotting purposes by using the projection argument of [tm_shape()]. +#' The default projections for these maps are Eckhart IV (World) and +#' Rijksdriehoekstelsel (Netherlands). See below. The projection can be changed +#' temporarily for plotting purposes by using the projection argument of [tm_shape()]. #' -#' `World` World map. The default projection for this world map is Eckhart IV since area sizes are preserved, which is a very important property for choropleths. +#' `World` World map. The default projection for this world map is Eckhart IV +#' since area sizes are preserved, which is a very important property for choropleths. #' -#' `NLD_prov` and `NLD_muni`, maps of the Netherlands at province and municipality level of 2013. The used projection is the Rijksdriehoekstelsel projection. +#' `NLD_prov` and `NLD_muni`, maps of the Netherlands at province and municipality +#' level of 2013. The used projection is the Rijksdriehoekstelsel projection. #' -#' **Important:** publication of these maps is only allowed when citing Statistics Netherlands (CBS) and Kadaster Nederland as source. +#' **Important:** publication of these maps is only allowed when citing +#' Statistics Netherlands (CBS) and Kadaster Nederland as source. #' #' @rdname Shapes #' @format NULL diff --git a/R/pkg.R b/R/pkg.R index d2c90223..71c5edc5 100644 --- a/R/pkg.R +++ b/R/pkg.R @@ -1,8 +1,12 @@ #' Thematic Map Visualization #' -#' Thematic maps are geographical maps in which spatial data distributions are visualized. This package offers a flexible, layer-based, and easy to use approach to create thematic maps, such as choropleths and bubble maps. It is based on the grammar of graphics, and resembles the syntax of ggplot2. +#' Thematic maps are geographical maps in which spatial data distributions are visualized. +#' This package offers a flexible, layer-based, and easy to use approach to create +#' thematic maps, such as choropleths and bubble maps. It is based on the grammar +#' of graphics, and resembles the syntax of ggplot2. #' -#' This page provides a brief overview of all package functions. See `vignette("tmap_sneak_peek")` for a short introduction with examples. +#' This page provides a brief overview of all package functions. +#' See `vignette("tmap_sneak_peek")` for a short introduction with examples. #' #' @section Quick plotting method: #' \tabular{ll}{ diff --git a/R/qtm.R b/R/qtm.R index 45e11dba..2d6aa601 100644 --- a/R/qtm.R +++ b/R/qtm.R @@ -1,35 +1,69 @@ #' Quick thematic map plot #' -#' Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking [`tmap-element`]s. Without arguments or with a search term, this functions draws an interactive map. +#' Draw a thematic map quickly. This function is a convenient wrapper of the main +#' plotting method of stacking [`tmap-element`]s. Without arguments or with a +#' search term, this functions draws an interactive map. #' -#' The first argument is a shape object (normally specified by [tm_shape()]). The next arguments, from `fill` to `raster`, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as [tm_polygons()], can be specified (see `...`). It is also possible to stack [`tmap-element`]s on a `qtm` plot. See examples. +#' The first argument is a shape object (normally specified by [tm_shape()]). +#' The next arguments, from `fill` to `raster`, are the aesthetics from the main +#' layers. The remaining arguments are related to the map layout. Any argument +#' from any main layer function, such as [tm_polygons()], can be specified (see `...`). +#' It is also possible to stack [`tmap-element`]s on a `qtm` plot. See examples. #' -#' By default, a scale bar is shown. This option can be set with [tmap_options()] (argument `qtm.scalebar`). A minimap is shown by default when `qtm` is called without arguments of with a search term. This option can be set with [tmap_options()] (argument `qtm.minimap`). +#' By default, a scale bar is shown. This option can be set with [tmap_options()] +#' (argument `qtm.scalebar`). A minimap is shown by default when `qtm` is called +#' without arguments of with a search term. This option can be set with [tmap_options()] +#' (argument `qtm.minimap`). #' -#' @param shp One of -#' \itemize{ -#' \item shape object, which is an object from a class defined by the [`sf`][`sf::sf`] or [`stars`][stars::st_as_stars()] package. Objects from the packages `sp` and `raster` are also supported, but discouraged. -#' \item Not specified, i.e. `qtm()` is executed. In this case a plain interactive map is shown. -#' \item An OpenStreetMap search string, e.g. `qtm("Amsterdam")`. In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim) -#' } +#' @param shp One of: +#' * shape object, which is an object from a class defined by the [`sf`][`sf::sf`] +#' or [`stars`][stars::st_as_stars()] package. Objects from the packages `sp` +#' and `raster` are also supported, but discouraged. +#' * Not specified, i.e. `qtm()` is executed. In this case a plain interactive +#' map is shown. +#' * An OpenStreetMap search string, e.g. `qtm("Amsterdam")`. In this case a +#' plain interactive map is shown positioned according to the results of the +#' search query (from OpenStreetMap nominatim) #' @param fill,col,size,shape,lwd,lty,fill_alpha,col_alpha Visual variables. -#' @param by data variable name by which the data is split, or a vector of two variable names to split the data by two variables (where the first is used for the rows and the second for the columns). See also [tm_facets()] -#' @param 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. The parameters `symbols.size`, `text.size`, and `lines.lwd` can be scaled separately with respectively `symbols.scale`, `text.scale`, and `lines.scale`. See also `...`. -#' @param title main title. For legend titles, use `X.style`, where X is the layer name (see `...`). -#' @param crs Either a [`crs`][sf::st_crs()] object or a character value (`PROJ.4` character string). By default, the projection is used that is defined in the `shp` object itself. +#' @param by data variable name by which the data is split, or a vector of two +#' variable names to split the data by two variables (where the first is used +#' for the rows and the second for the columns). See also [tm_facets()]. +#' @param 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. +#' The parameters `symbols.size`, `text.size`, and `lines.lwd` can be scaled +#' separately with respectively `symbols.scale`, `text.scale`, and +#' `lines.scale`. See also `...`. +#' @param title main title. For legend titles, use `X.style`, where X is the +#' layer name (see `...`). +#' @param crs Either a [`crs`][sf::st_crs()] object or a character value +#' (`PROJ.4` character string). By default, the projection is used that is +#' defined in the `shp` object itself. #' @param bbox bounding box. Argument passed on to [tm_shape()] -#' @param basemaps name(s) of the provider or an URL of a tiled basemap. It is a shortcut to [tm_basemap()]. Set to `NULL` to disable basemaps. By default, it is set to the tmap option `basemaps`. -#' @param overlays name(s) of the provider or an URL of a tiled overlay map. It is a shortcut to [tm_tiles()]. +#' @param basemaps name(s) of the provider or an URL of a tiled basemap. +#' It is a shortcut to [tm_basemap()]. Set to `NULL` to disable basemaps. +#' By default, it is set to the tmap option `basemaps`. +#' @param overlays name(s) of the provider or an URL of a tiled overlay map. +#' It is a shortcut to [tm_tiles()]. #' @param zindex zindex #' @param group group #' @param group.control group.control -#' @param style Layout options (see [tm_layout()]) that define the style. See [tmap_style()] for details. -#' @param format Layout options (see [tm_layout()]) that define the format. See [tmap_format()] for details. -#' @param ... arguments passed on to the `tm_*` functions. The prefix of these arguments should be with the layer function name without `"tm_"` and a period. For instance, the palette for polygon fill color is called `fill.palette`. The following prefixes are supported: `shape.`, `fill.`, `borders.`, `polygons.`, `symbols.`, `dots.`, `lines.`, `raster.`, `text.`, `layout.`, `grid.`, `facets.`, and `view.`. Arguments that have a unique name, i.e. that does not exist in any other layer function, e.g. `convert2density`, can also be called without prefix. +#' @param style Layout options (see [tm_layout()]) that define the style. +#' See [tmap_style()] for details. +#' @param format Layout options (see [tm_layout()]) that define the format. +#' See [tmap_format()] for details. +#' @param ... arguments passed on to the `tm_*` functions. The prefix of these +#' arguments should be with the layer function name without `"tm_"` and a period. +#' For instance, the palette for polygon fill color is called `fill.palette`. +#' The following prefixes are supported: `shape.`, `fill.`, `borders.`, `polygons.`, +#' `symbols.`, `dots.`, `lines.`, `raster.`, `text.`, `layout.`, `grid.`, +#' `facets.`, and `view.`. Arguments that have a unique name, i.e. that does +#' not exist in any other layer function, e.g. `convert2density`, can also be +#' called without prefix. #' @return A [`tmap-element`] #' @example ./examples/qtm.R #' @seealso `vignette("tmap_sneak_peek")` -#' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} +#' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, +#' Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} #' @export qtm <- function(shp, fill = tm_const(), diff --git a/R/theme_ps.R b/R/theme_ps.R index 9a99c310..1eddafa7 100644 --- a/R/theme_ps.R +++ b/R/theme_ps.R @@ -1,6 +1,7 @@ #' ggplot2 theme for proportional symbols #' -#' ggplot2 theme for proportional symbols. By default, this theme only shows the plotting area, so without titles, axes, and legend +#' ggplot2 theme for proportional symbols. By default, this theme only shows the +#' plotting area, so without titles, axes, and legend. #' #' @param base_size base size #' @param base_family base family diff --git a/R/tm_add_legend.R b/R/tm_add_legend.R index 335f08e5..8e56b2c7 100644 --- a/R/tm_add_legend.R +++ b/R/tm_add_legend.R @@ -2,14 +2,23 @@ #' #' Map component that adds a manual legend #' -#' @param ... visual variables and arguments passed on to `tm_legend`. By default, the argument `type` is set to `"Symbols"`, which means that the supported visual variables are: `"fill"`, `"col"`, `"shape"`, `"size"`, `"fill_alpha"`, `"col_alpha"`, `"lty"`, `"lwd"`, `"linejoin"`, and `"lineend"`. +#' @param ... visual variables and arguments passed on to `tm_legend()`. +#' By default, the argument `type` is set to `"Symbols"`, which means that the +#' supported visual variables are: `"fill"`, `"col"`, `"shape"`, `"size"`, +#' `"fill_alpha"`, `"col_alpha"`, `"lty"`, `"lwd"`, `"linejoin"`, and `"lineend"`. #' @param labels labels -#' @param type the layer type from which the visual variables (see ...) are taken. Options: `"Symbols"` (default), `"Lines"`, `"Polygons"`, and `"Text"`. +#' @param type the layer type from which the visual variables (see `...`) are taken. +#' Options: `"Symbols"` (default), `"Lines"`, `"Polygons"`, and `"Text"`. #' @param title text of the title #' @param design legend design #' @param orientation legend orientation -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). +#' @param group Name of the group to which this layer belongs. This is only +#' relevant in view mode, where layer groups can be switched (see `group.control`) +#' @param group.control In view mode, the group control determines how +#' layer groups can be switched on and off. Options: `"radio"` for radio +#' buttons (meaning only one group can be shown), `"check"` for check boxes +#' (so multiple groups can be shown), and `"none"` for no control +#' (the group cannot be (de)selected). #' @param resize.as.group resize.as.group #' @param z z #' @export @@ -35,7 +44,9 @@ tmapAddedLegend = function(comp, o) { l = update_l(o = o, l = comp, v = "", mfun = comp$type) fun = paste0("tm_", tolower(comp$type)) - if (!exists(fun)) stop(paste0("type \"", comp$type, "\" not supported because tm_", comp$type, " not found"), call. = FALSE) + if (!exists(fun)) { + stop(paste0("type \"", comp$type, "\" not supported because tm_", comp$type, " not found"), call. = FALSE) + } res = do.call(fun, args = list()) gp = res[[1]]$gpar diff --git a/R/tm_components.R b/R/tm_components.R index df4d3a16..50dfc497 100644 --- a/R/tm_components.R +++ b/R/tm_components.R @@ -142,7 +142,9 @@ tm_compass <- function(north, #' Map component: scale bar #' -#' Map component that adds a scale bar. As of version 4.0, `tm_scalebar()` is used instead of `tm_scale_bar` (now deprecated), because of the potential confusion with the `tm_scale_x` scaling functions (like [tm_scale_continuous()]). +#' Map component that adds a scale bar. As of version 4.0, `tm_scalebar()` is +#' used instead of `tm_scale_bar()` (now deprecated), because of the potential +#' confusion with the `tm_scale_*()` scaling functions (like [tm_scale_continuous()]). #' #' @param breaks breaks #' @param width width diff --git a/R/tm_element.R b/R/tm_element.R index 8aadeab9..6c35494c 100644 --- a/R/tm_element.R +++ b/R/tm_element.R @@ -39,14 +39,18 @@ tm_element_list_sel = function(tml, subclass) { #' Retrieve the last map to be modified or created #' -#' Retrieve the last map to be modified or created. Works in the same way as [ggplot2::last_plot()], although there is a difference: `tmap_last()` returns the last call instead of the stacked [`tmap-element`]s. +#' Retrieve the last map to be modified or created. Works in the same way +#' as [ggplot2::last_plot()], although there is a difference: +#' `tmap_last()` returns the last call instead of the stacked [`tmap-element`]s. #' #' @return call #' @export #' @seealso [tmap_save()] tmap_last = function() { .x = get("last_map", envir = .TMAP) - if (is.null(.x) && get("tmapOptions", envir = .TMAP)$show.warnings) warning("A map has not been created yet") + if (is.null(.x) && get("tmapOptions", envir = .TMAP)$show.warnings) { + warning("A map has not been created yet") + } eval(.x) } diff --git a/R/tm_facets.R b/R/tm_facets.R index 60de1c11..4e027408 100644 --- a/R/tm_facets.R +++ b/R/tm_facets.R @@ -1,6 +1,11 @@ #' Facets #' -#' Specify facets. `tm_facets()` is the core function, but recommended is to use `tm_facets_wrap()`, `tm_facets_stack()` or `tm_facets_grid()`. The former two specify facets for one grouping variable (so one faceting dimension). The difference is that wrap may place facets in multiple rows and columns whereas `tm_facets_stack()` stacks the facets either horizontally or vertically. `tm_facets_grid()` supports up to three faceting dimensions. +#' Specify facets. `tm_facets()` is the core function, but recommended is to use +#' `tm_facets_wrap()`, `tm_facets_stack()` or `tm_facets_grid()`. +#' The former two specify facets for one grouping variable (so one faceting dimension). +#' The difference is that wrap may place facets in multiple rows and columns whereas +#' `tm_facets_stack()` stacks the facets either horizontally or vertically. +#' `tm_facets_grid()` supports up to three faceting dimensions. #' #' @param by Group by variable (only for a facet wrap or facet stack) #' @param rows Variable that specifies the rows (only for a facet grid) @@ -11,14 +16,38 @@ #' @param ncols Number of columns #' @param byrow Should facets be wrapped by row? #' @param orientation For facet stack: horizontal or vertical? -#' @param free.coords Logical. If the `by` argument is specified, should each map has its own coordinate ranges? By default `TRUE`, unless facets are shown in as different layers (`as.layers = TRUE`) -#' @param drop.units Logical. If the `by` argument is specified, should non-selected spatial units be dropped? If `FALSE`, they are plotted where mapped aesthetics are regarded as missing values. Not applicable for raster shapes. By default `TRUE`. -#' @param drop.empty.facets Logical. If the `by` argument is specified, should empty facets be dropped? Empty facets occur when the `by`-variable contains unused levels. When `TRUE` and two `by`-variables are specified, empty rows and columns are dropped. -#' @param drop.NA.facets Logical. If the `by` argument is specified, and all data values for specific facets are missing, should these facets be dropped? `FALSE` by default. -#' @param sync Logical. Should the navigation in view mode (zooming and panning) be synchronized? By default `TRUE` if the facets have the same bounding box. This is generally the case when rasters are plotted, or when free.coords is `FALSE`. -#' @param showNA If the `by` argument is specified, should missing values of the `by`-variable be shown in a facet? If two `by`-variables are specified, should missing values be shown in an additional row and column? If `NA`, missing values only are shown if they exist. Similar to the `useNA` argument of [table()][base::table()], where `TRUE`, `FALSE`, and `NA` correspond to `"always"`, `"no"`, and `"ifany"` respectively. +#' @param free.coords Logical. If the `by` argument is specified, should each +#' map has its own coordinate ranges? By default `TRUE`, unless facets are shown +#' in as different layers (`as.layers = TRUE`) +#' @param drop.units Logical. If the `by` argument is specified, should +#' non-selected spatial units be dropped? If `FALSE`, they are plotted where +#' mapped aesthetics are regarded as missing values. Not applicable for +#' raster shapes. By default `TRUE`. +#' @param drop.empty.facets Logical. If the `by` argument is specified, should +#' empty facets be dropped? Empty facets occur when the `by`-variable contains +#' unused levels. When `TRUE` and two `by`-variables are specified, empty rows +#' and columns are dropped. +#' @param drop.NA.facets Logical. If the `by` argument is specified, and all +#' data values for specific facets are missing, should these facets be dropped? +#' `FALSE` by default. +#' @param sync Logical. Should the navigation in view mode (zooming and panning) +#' be synchronized? By default `TRUE` if the facets have the same bounding box. +#' This is generally the case when rasters are plotted, or when `free.coords` is +#' `FALSE`. +#' @param showNA If the `by` argument is specified, should missing values of the +#' `by`-variable be shown in a facet? If two `by`-variables are specified, +#' should missing values be shown in an additional row and column? +#' If `NA`, missing values only are shown if they exist. Similar to the +#' `useNA` argument of [table()][base::table()], where `TRUE`, `FALSE`, +#' and `NA` correspond to `"always"`, `"no"`, and `"ifany"` respectively. #' @param textNA Text used for facets of missing values. -#' @param scale.factor Number that determines how the elements (e.g. font sizes, symbol sizes, line widths) of the small multiples are scaled in relation to the scaling factor of the shapes. The elements are scaled to the `scale.factor`th root of the scaling factor of the shapes. So, for `scale.factor=1`, they are scaled proportional to the scaling of the shapes. Since elements, especially text, are often too small to read, a higher value is recommended. By default, `scale.factor=2`. +#' @param scale.factor Number that determines how the elements (e.g. font sizes, +#' symbol sizes, line widths) of the small multiples are scaled in relation to +#' the scaling factor of the shapes. The elements are scaled to the `scale.factor`th +#' root of the scaling factor of the shapes. So, for `scale.factor=1`, +#' they are scaled proportional to the scaling of the shapes. Since elements, +#' especially text, are often too small to read, a higher value is recommended. +#' By default, `scale.factor=2`. #' @param type `"grid"`, `"wrap"` or `"stack"` #' @param along deprecated Please use `tm_facets_page()` #' @export diff --git a/R/tm_layers_aux.R b/R/tm_layers_aux.R index 0874fa49..5888167a 100644 --- a/R/tm_layers_aux.R +++ b/R/tm_layers_aux.R @@ -1,13 +1,32 @@ #' Map layer: basemap / overlay tiles #' -#' Map layer that draws tiles from a tile server. `tm_basemap()` draws the tile layer as basemap, i.e. as bottom layer. In contrast, `tm_tiles()` draws the tile layer as overlay layer, where the stacking order corresponds with the order in which this layer is called, just like other map layers. +#' Map layer that draws tiles from a tile server. `tm_basemap()` draws the tile +#' layer as basemap, i.e. as bottom layer. In contrast, `tm_tiles()` draws the +#' tile layer as overlay layer, where the stacking order corresponds with the +#' order in which this layer is called, just like other map layers. #' -#' @param server Name of the provider or an URL. The list of available providers can be obtained with `providers` (tip: in RStudio, type `providers$` to see the options). See for a preview of those. When a URL is provided, it should be in template format, e.g. \code{"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"}. Use `NULL` in `tm_basemap()` to disable basemaps. +#' @param server Name of the provider or an URL. The list of available providers +#' can be obtained with `providers` (tip: in RStudio, type `providers$` to see +#' the options). See +#' for a preview of those. When a URL is provided, it should be in template format, +#' e.g. \code{"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"}. +#' Use `NULL` in `tm_basemap()` to disable basemaps. #' @param alpha Transparency level #' @param zoom Zoom level (only used in plot mode) -#' @param 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, if `zindex` is set to 500, the pane will be named `"tmap500"`. -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). +#' @param 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, if `zindex` is set to 500, the pane will +#' be named `"tmap500"`. +#' @param group Name of the group to which this layer belongs. This is only +#' relevant in view mode, where layer groups can be switched (see `group.control`) +#' @param group.control In view mode, the group control determines how layer +#' groups can be switched on and off. Options: `"radio"` for radio buttons +#' (meaning only one group can be shown), `"check"` for check boxes +#' (so multiple groups can be shown), and `"none"` for no control +#' (the group cannot be (de)selected). #' @export #' @rdname tm_basemap #' @name tm_basemap @@ -50,46 +69,98 @@ tm_graticules = function(x = NA, labels.format = list(suffix = intToUtf8(176)), labels.cardinal = TRUE, ...) { - do.call(tm_grid, c(list(x = x, y = y, n.x = n.x, n.y = n.y, crs = crs, labels.format = labels.format, labels.cardinal = labels.cardinal), list(...))) + do.call( + tm_grid, + c(list(x = x, y = y, n.x = n.x, n.y = n.y, crs = crs, labels.format = labels.format, labels.cardinal = labels.cardinal), list(...)) + ) } #' Coordinate grid / graticule lines #' -#' Creates a [`tmap-element`] that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. By default, `tm_grid()` draws horizontal and vertical lines according to the coordinate system of the (master) shape object. Latitude and longitude graticules are drawn with `tm_graticules()`. +#' Creates a [`tmap-element`] that draws coordinate grid lines. It serves as a +#' layer that can be drawn anywhere between other layers. +#' By default, `tm_grid()` draws horizontal and vertical lines according to the +#' coordinate system of the (master) shape object. Latitude and longitude +#' graticules are drawn with `tm_graticules()`. #' -#' @param x X coordinates for vertical grid lines. If `NA`, it is specified with a pretty scale and `n.x`. -#' @param y Y coordinates for horizontal grid lines. If `NA`, it is specified with a pretty scale and `n.y`. -#' @param n.x Preferred number of grid lines for the x axis. For the labels, a [pretty()] sequence is used, so the number of actual labels may be different than `n.x`. -#' @param n.y Preferred number of grid lines for the y axis. For the labels, a [pretty()] sequence is used, so the number of actual labels may be different than `n.y`. -#' @param crs Projection character. If specified, the grid lines are projected accordingly. Many world maps are projected, but still have latitude longitude (EPSG 4326) grid lines. +#' @param x X coordinates for vertical grid lines. If `NA`, it is specified +#' with a pretty scale and `n.x`. +#' @param y Y coordinates for horizontal grid lines. If `NA`, it is specified +#' with a pretty scale and `n.y`. +#' @param n.x Preferred number of grid lines for the x axis. For the labels, +#' a [pretty()] sequence is used, so the number of actual labels may be different than `n.x`. +#' @param n.y Preferred number of grid lines for the y axis. For the labels, a +#' [pretty()] sequence is used, so the number of actual labels may be different than `n.y`. +#' @param crs Projection character. If specified, the grid lines are projected +#' accordingly. Many world maps are projected, but still have latitude longitude +#' (EPSG 4326) grid lines. #' @param col Color of the grid lines. #' @param lwd Line width of the grid lines -#' @param alpha Alpha transparency of the grid lines. Number between 0 and 1. By default, the alpha transparency of `col` is taken. -#' @param labels.show Show tick labels. Either one value for both `x` and `y` axis, or a vector two: the first for `x` and latter for `y`. -#' @param labels.pos position of the labels. Vector of two: the horizontal ("left" or "right") and the vertical ("top" or "bottom") position. +#' @param alpha Alpha transparency of the grid lines. Number between 0 and 1. +#' By default, the alpha transparency of `col` is taken. +#' @param labels.show Show tick labels. Either one value for both `x` and `y` axis, +#' or a vector two: the first for `x` and latter for `y`. +#' @param labels.pos position of the labels. Vector of two: the horizontal +#' ("left" or "right") and the vertical ("top" or "bottom") position. #' @param labels.size Font size of the tick labels #' @param labels.col Font color of the tick labels -#' @param labels.rot Rotation angles of the labels. Vector of two values: the first is the rotation angle (in degrees) of the tick labels on the x axis and the second is the rotation angle of the tick labels on the y axis. Only `0`, `90`, `180`, and `270` are valid values. +#' @param labels.rot Rotation angles of the labels. Vector of two values: the +#' first is the rotation angle (in degrees) of the tick labels on the x axis +#' and the second is the rotation angle of the tick labels on the y axis. +#' Only `0`, `90`, `180`, and `270` are valid values. #' @param labels.format List of formatting options for the grid labels. Parameters are: #' \describe{ -#' \item{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.} -#' \item{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.} -#' \item{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.} -#' \item{digits}{Number of digits after the decimal point if `format="f"`, and the number of significant digits otherwise.} +#' \item{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.} +#' \item{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.} +#' \item{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.} +#' \item{digits}{Number of digits after the decimal point if `format="f"`, and +#' the number of significant digits otherwise.} #' \item{...}{Other arguments passed on to [formatC()]} #' } -#' @param labels.cardinal Add the four cardinal directions (N, E, S, W) to the labels, instead of using negative coordinates for west and south (so it assumes that the coordinates are positive in the north-east direction). -#' @param labels.margin.x Margin between tick labels of x axis and the frame. Note that when `labels.inside.frame == FALSE` and `ticks == TRUE`, the ticks will be adjusted accordingly. -#' @param labels.margin.y Margin between tick labels of y axis and the frame. Note that when `labels.inside.frame == FALSE` and `ticks == TRUE`, the ticks will be adjusted accordingly. -#' @param labels.space.x Space that is used for the labels and ticks for the x-axis when `labels.inside.frame == FALSE`. By default, it is determined automatically using the widths and heights of the tick labels. The unit of this parameter is text line height. -#' @param labels.space.y Space that is used for the labels and ticks for the y-axis when `labels.inside.frame == FALSE`. By default, it is determined automatically using the widths and heights of the tick labels. The unit of this parameter is text line height. -#' @param labels.inside.frame Show labels inside the frame? By default `FALSE` -#' @param ticks If `labels.inside.frame = FALSE`, should ticks can be drawn between the labels and the frame? Either one value for both `x` and `y` axis, or a vector two: the first for `x` and latter for `y`. +#' @param labels.cardinal Add the four cardinal directions (N, E, S, W) to the labels, +#' instead of using negative coordinates for west and south (so it assumes that +#' the coordinates are positive in the north-east direction). +#' @param labels.margin.x Margin between tick labels of x axis and the frame. +#' Note that when `labels.inside.frame == FALSE` and `ticks == TRUE`, +#' the ticks will be adjusted accordingly. +#' @param labels.margin.y Margin between tick labels of y axis and the frame. +#' Note that when `labels.inside.frame == FALSE` and `ticks == TRUE`, +#' the ticks will be adjusted accordingly. +#' @param labels.space.x Space that is used for the labels and ticks for the x-axis +#' when `labels.inside.frame == FALSE`. By default, it is determined automatically +#' using the widths and heights of the tick labels. The unit of this parameter is text line height. +#' @param labels.space.y Space that is used for the labels and ticks for the y-axis +#' when `labels.inside.frame == FALSE`. By default, it is determined automatically +#' using the widths and heights of the tick labels. The unit of this parameter is text line height. +#' @param labels.inside.frame Show labels inside the frame? By default `FALSE`. +#' @param ticks If `labels.inside.frame = FALSE`, should ticks can be drawn between the labels and the frame? +#' Either one value for both `x` and `y` axis, or a vector two: the first for `x` and latter for `y`. #' @param lines If `labels.inside.frame = FALSE`, should grid lines can be drawn? -#' @param ndiscr Number of points to discretize a parallel or meridian (only applicable for curved grid lines) -#' @param 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, if `zindex` is set to 500, the pane will be named `"tmap500"`. -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). +#' @param ndiscr Number of points to discretize a parallel or meridian +#' (only applicable for curved grid lines) +#' @param 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, if `zindex` is set to 500, +#' the pane will be named `"tmap500"`. +#' @param group Name of the group to which this layer belongs. +#' This is only relevant in view mode, where layer groups can be +#' switched (see `group.control`) +#' @param group.control In view mode, the group control determines how layer groups +#' can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), +#' `"check"` for check boxes (so multiple groups can be shown), and `"none"` +#' for no control (the group cannot be (de)selected). #' @param ... Arguments passed on to [tm_grid()] #' @export #' @example ./examples/tm_grid.R diff --git a/R/tm_layers_cartogram.R b/R/tm_layers_cartogram.R index 75fadf41..f003dae9 100644 --- a/R/tm_layers_cartogram.R +++ b/R/tm_layers_cartogram.R @@ -2,8 +2,10 @@ #' #' Map layer that draws a cartogram #' -#' @param size,size.scale,size.legend,size.free Transformation variable that determines the size of the polygons. -#' @param plot.order Specification in which order the spatial features are drawn. See [tm_plot_order()] for details. +#' @param size,size.scale,size.legend,size.free Transformation variable that +#' determines the size of the polygons. +#' @param plot.order Specification in which order the spatial features are drawn. +#' See [tm_plot_order()] for details. #' @param trans.args lists that are passed on to internal transformation function #' @inheritDotParams tm_polygons #' @export diff --git a/R/tm_layers_polygons.R b/R/tm_layers_polygons.R index e8d9a09c..08cd9673 100644 --- a/R/tm_layers_polygons.R +++ b/R/tm_layers_polygons.R @@ -1,32 +1,71 @@ #' Map layer: polygons #' -#' Map layer that draws polygons. Supported visual variables are: `fill` (the fill color), `col` (the border color), `lwd` (line width), `lty` (line type), `fill_alpha` (fill color alpha transparency) and `col_alpha` (border color alpha transparency). +#' Map layer that draws polygons. Supported visual variables are: `fill` (the fill color), +#' `col` (the border color), `lwd` (line width), `lty` (line type), +#' `fill_alpha` (fill color alpha transparency) and `col_alpha` (border color alpha transparency). #' -#' The visual variable arguments (e.g. `col`) can be specified with either a data variable name (e.g., a spatial vector attribute or a raster layer of the object specified in [tm_shape()]), or with a visual value (for `col`, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with [tm_facets()]. +#' The visual variable arguments (e.g. `col`) can be specified with either a data +#' variable name (e.g., a spatial vector attribute or a raster layer of the object +#' specified in [tm_shape()]), or with a visual value (for `col`, a color is expected). +#' Multiple values can be specified: in that case facets are created. +#' These facets can be combined with other faceting data variables, specified with [tm_facets()]. #' -#' The `.scale` arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available `tm_scale_` functions. The default is specified by the tmap option ([tm_options()]) `scales.var`. +#' The `*.scale` arguments determine the used scale to map the data values to +#' visual variable values. These can be specified with one of the available +#' `tm_scale_*()` functions. The default is specified by the tmap option ([tm_options()]) `scales.var`. #' -#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. The default legend and its settings are determined by the tmap options ([tm_options()]) `legend.` . +#' The `*.legend` arguments determine the used legend, specified with [tm_legend()]. +#' The default legend and its settings are determined by the tmap options ([tm_options()]) `legend.` . #' -#' The `.free` arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see [tm_facets()]). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid ([tm_facets_grid()]). For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual variable `col`, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]) there is only one facet dimension, so the `.free` argument requires only one logical value. +#' The `*.free` arguments determine whether scales are applied freely across facets, or shared. +#' A logical value is required. They can also be specified with a vector of three +#' logical values; these determine whether scales are applied freely per facet dimension. +#' This is only useful when facets are applied (see [tm_facets()]). +#' There are maximally three facet dimensions: rows, columns, and pages. This only +#' applies for a facet grid ([tm_facets_grid()]). For instance, `col.free = c(TRUE, FALSE, FALSE)` +#' means that for the visual variable `col`, each row of facets will have its own +#' scale, and therefore its own legend. For facet wraps and stacks +#' ([tm_facets_wrap()] and [tm_facets_stack()]) there is only one facet dimension, +#' so the `*.free` argument requires only one logical value. #' #' @param fill,fill.scale,fill.legend,fill.free Visual variable that determines the fill color. See details. #' @param col,col.scale,col.legend,col.free Visual variable that determines the border color. See details. #' @param lwd,lwd.scale,lwd.legend,lwd.free Visual variable that determines the line width. See details. #' @param lty,lty.scale,lty.legend,lty.free Visual variable that determines the line type. See details. -#' @param fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free Visual variable that determines the fill color alpha transparency See details. -#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable that determines the border color alpha transparency. See details. +#' @param fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free Visual +#' variable that determines the fill color alpha transparency See details. +#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable +#' that determines the border color alpha transparency. See details. #' @param linejoin,lineend Line join and line end. See [gpar()][grid::gpar()] for details. -#' @param plot.order Specification in which order the spatial features are drawn. See [tm_plot_order()] for details. -#' @param trans.args,mapping.args lists that are passed on to internal transformation and mapping functions respectively -#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called. -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). -#' @param popup.vars names of data variables that are shown in the popups in `"view"` mode. Set popup.vars to `TRUE` to show all variables in the shape object. Set popup.vars to `FALSE` to disable popups. Set popup.vars to a character vector of variable names to those those variables in the popups. The default (`NA`) depends on whether visual variables (e.g.`col`) are used. If so, only those are shown. If not all variables in the shape object are shown. -#' @param 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. +#' @param plot.order Specification in which order the spatial features are drawn. +#' See [tm_plot_order()] for details. +#' @param trans.args,mapping.args lists that are passed on to internal transformation +#' and mapping functions respectively. +#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers +#' (one for each map layer) determines the stacking order. +#' By default the map layers are drawn in the order they are called. +#' @param group Name of the group to which this layer belongs. This is only +#' relevant in view mode, where layer groups can be switched (see `group.control`) +#' @param group.control In view mode, the group control determines how layer groups +#' can be switched on and off. Options: `"radio"` for radio buttons +#' (meaning only one group can be shown), `"check"` for check boxes +#' (so multiple groups can be shown), and `"none"` for no control +#' (the group cannot be (de)selected). +#' @param popup.vars names of data variables that are shown in the popups +#' in `"view"` mode. Set popup.vars to `TRUE` to show all variables in the +#' shape object. Set popup.vars to `FALSE` to disable popups. Set `popup.vars` +#' to a character vector of variable names to those those variables in the popups. +#' The default (`NA`) depends on whether visual variables (e.g.`fill`) are used. +#' If so, only those are shown. If not all variables in the shape object are shown. +#' @param 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. #' @param hover name of the data variable that specifies the hover labels -#' -#' @param id name of the data variable that specifies the indices of the spatial features. Only used for `"view"` mode. +#' @param id name of the data variable that specifies the indices of the spatial +#' features. Only used for `"view"` mode. #' @param ... to catch deprecated arguments from version < 4.0 #' @example ./examples/tm_polygons.R #' @name tm_polygons diff --git a/R/tm_layers_raster.R b/R/tm_layers_raster.R index 767d0d15..9dbf3c9e 100644 --- a/R/tm_layers_raster.R +++ b/R/tm_layers_raster.R @@ -2,20 +2,46 @@ #' #' Map layer that draws rasters. Supported visual variable is: `col` (the color). #' -#' The visual variable arguments (e.g. `col`) can be specified with either a data variable name (of the object specified in [tm_shape()]), or with a visual value (for `col`, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with [tm_facets()]. +#' The visual variable arguments (e.g. `col`) can be specified with either a data +#' variable name (of the object specified in [tm_shape()]), or with a visual value +#' (for `col`, a color is expected). Multiple values can be specified: in that +#' case facets are created. These facets can be combined with other faceting data +#' variables, specified with [tm_facets()]. #' -#' The `.scale` arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available `tm_scale_` functions. The default scale that is used is specified by the tmap option `scales.var`. +#' * The `.scale` arguments determine the used scale to map the data values to +#' visual variable values. These can be specified with one of the available +#' `tm_scale_()` functions. The default scale that is used is specified by the +#' tmap option `scales.var`. #' -#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. The default legend and its settings are determined by the tmap options `legend.`. +#' * The `.legend` arguments determine the used legend, specified with [tm_legend()]. +#' The default legend and its settings are determined by the tmap options `legend.`. #' -#' The `.free` arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see [tm_facets()]). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid ([tm_facets_grid()]). For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual variable `col`, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]) there is only one facet dimension, so the `.free` argument requires only one logical value. +#' * The `.free` arguments determine whether scales are applied freely across +#' facets, or shared. A logical value is required. They can also be specified +#' with a vector of three logical values; these determine whether scales are applied +#' freely per facet dimension. This is only useful when facets are applied (see [tm_facets()]). +#' There are maximally three facet dimensions: rows, columns, and pages. +#' This only applies for a facet grid ([tm_facets_grid()]). +#' For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual +#' variable `col`, each row of facets will have its own scale, and therefore its +#' own legend. For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]), +#' there is only one facet dimension, so the `.free` argument requires only one logical value. #' -#' @param col,col.scale,col.legend,col.free Visual variable that determines the color. See details. -#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable that determines the alpha transparency. See details. -#' @param trans.args,mapping.args lists that are passed on to internal transformation and mapping functions respectively -#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called. -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). +#' @param col,col.scale,col.legend,col.free Visual variable that determines the color. +#' See details. +#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable +#' that determines the alpha transparency. See details. +#' @param trans.args,mapping.args lists that are passed on to internal transformation +#' and mapping functions respectively. +#' @param zindex Map layers are drawn on top of each other. +#' The `zindex` numbers (one for each map layer) determines the stacking order. +#' By default the map layers are drawn in the order they are called. +#' @param group Name of the group to which this layer belongs. This is only +#' relevant in view mode, where layer groups can be switched (see `group.control`) +#' @param group.control In view mode, the group control determines how layer groups +#' can be switched on and off. Options: `"radio"` for radio buttons (meaning only +#' one group can be shown), `"check"` for check boxes (so multiple groups can be +#' shown), and `"none"` for no control (the group cannot be (de)selected). #' @example ./examples/tm_raster.R #' @export tm_raster = function(col = tm_shape_vars(), diff --git a/R/tm_layers_rgb.R b/R/tm_layers_rgb.R index 96b0ff15..8128e9a9 100644 --- a/R/tm_layers_rgb.R +++ b/R/tm_layers_rgb.R @@ -1,6 +1,7 @@ #' Map layer: RGB #' -#' @param col,col.scale,col.legend,col.free Visual variable that determines the col color. +#' @param col,col.scale,col.legend,col.free Visual variable that determines +#' the col color. #' @export tm_rgb = function(col = tm_mv(1:3), col.scale = tm_scale_rgb(), diff --git a/R/tm_layers_sf.R b/R/tm_layers_sf.R index 034542f7..fe0b952c 100644 --- a/R/tm_layers_sf.R +++ b/R/tm_layers_sf.R @@ -1,90 +1,172 @@ #' Map layer: simple features #' -#' Map layer that draws simple features as they are. Supported visual variables are: `fill` (the fill color), `col` (the border color), `size` the point size, `shape` the symbol shape, `lwd` (line width), `lty` (line type), `fill_alpha` (fill color alpha transparency) and `col_alpha` (border color alpha transparency). +#' Map layer that draws simple features as they are. Supported visual variables +#' are: `fill` (the fill color), `col` (the border color), `size` the point size, +#' `shape` the symbol shape, `lwd` (line width), `lty` (line type), `fill_alpha` (fill color alpha transparency) +#' and `col_alpha` (border color alpha transparency). #' -#' The visual variable arguments (e.g. `col`) can be specified with either a data variable name (of the object specified in [tm_shape()]), or with a visual value (for `col`, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with [tm_facets()]. +#' The visual variable arguments (e.g. `col`) can be specified with either a data +#' variable name (of the object specified in [tm_shape()]), or with a visual value +#' (for `col`, a color is expected). Multiple values can be specified: in that case +#' facets are created. These facets can be combined with other faceting data variables, +#' specified with [tm_facets()]. #' -#' The `.scale` arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available `tm_scale_` functions. The default scale that is used is specified by the tmap option `scales.var`. +#' The `.scale` arguments determine the used scale to map the data values to visual +#' variable values. These can be specified with one of the available `tm_scale_()` functions. +#' The default scale that is used is specified by the tmap option `scales.var`. #' -#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. The default legend and its settings are determined by the tmap options `legend.`. +#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. +#' The default legend and its settings are determined by the tmap options `legend.`. #' -#' The `.free` arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see [tm_facets()]). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid ([tm_facets_grid()]). For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual variable `col`, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]) there is only one facet dimension, so the `.free` argument requires only one logical value. +#' The `.free` arguments determine whether scales are applied freely across facets, +#' or shared. A logical value is required. They can also be specified with a +#' vector of three logical values; these determine whether scales are applied freely +#' per facet dimension. This is only useful when facets are applied (see [tm_facets()]). +#' There are maximally three facet dimensions: rows, columns, and pages. This only applies +#' for a facet grid ([tm_facets_grid()]). For instance, `col.free = c(TRUE, FALSE, FALSE)` means +#' that for the visual variable `col`, each row of facets will have its own scale, +#' and therefore its own legend. For facet wraps and stacks ([tm_facets_wrap()] and +#' [tm_facets_stack()]) there is only one facet dimension, so the `.free` argument requires +#' only one logical value. #' -#' @param fill,fill.scale,fill.legend,fill.free Visual variable that determines the fill color. See details. -#' @param col,col.scale,col.legend,col.free Visual variable that determines the col color. See details. -#' @param size,size.scale,size.legend,size.free Visual variable that determines the size. See details. -#' @param shape,shape.scale,shape.legend,shape.free Visual variable that determines the shape. See details. -#' @param lwd,lwd.scale,lwd.legend,lwd.free Visual variable that determines the line width. See details. -#' @param lty,lty.scale,lty.legend,lty.free Visual variable that determines the line type. See details. -#' @param fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free Visual variable that determines the fill color alpha transparency See details. -#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable that determines the border color alpha transparency. See details. +#' @param fill,fill.scale,fill.legend,fill.free Visual variable that determines +#' the fill color. See details. +#' @param col,col.scale,col.legend,col.free Visual variable that determines +#' the col color. See details. +#' @param size,size.scale,size.legend,size.free Visual variable that determines +#' the size. See details. +#' @param shape,shape.scale,shape.legend,shape.free Visual variable that determines +#' the shape. See details. +#' @param lwd,lwd.scale,lwd.legend,lwd.free Visual variable that determines +#' the line width. See details. +#' @param lty,lty.scale,lty.legend,lty.free Visual variable that determines +#' the line type. See details. +#' @param fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free Visual +#' variable that determines the fill color alpha transparency See details. +#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable +#' that determines the border color alpha transparency. See details. #' @param linejoin,lineend line join and line end. See [gpar()][grid::gpar()] for details. -#' @param plot.order.list Specification in which order the spatial features are drawn. This consists of a list of three elementary geometry types: for polygons, lines and, points. For each of these types, which are drawn in that order, a [tm_plot_order()] is required. -#' @param trans.args.list,mapping.args.list lists that are passed on to internal transformation and mapping functions respectively. Each is a list of three items, named `polygons`, `lines`, and `points`. See [tm_polygons()], [tm_lines()], and [tm_dots()]. -#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called. -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). +#' @param plot.order.list Specification in which order the spatial features are drawn. +#' This consists of a list of three elementary geometry types: for polygons, lines and, points. +#' For each of these types, which are drawn in that order, a [tm_plot_order()] is required. +#' @param trans.args.list,mapping.args.list lists that are passed on to internal +#' transformation and mapping functions respectively. Each is a list of three +#' items, named `polygons`, `lines`, and `points`. See [tm_polygons()], [tm_lines()], and [tm_dots()]. +#' @param zindex Map layers are drawn on top of each other. +#' The `zindex` numbers (one for each map layer) determines the stacking order. +#' By default the map layers are drawn in the order they are called. +#' @param group Name of the group to which this layer belongs. +#' This is only relevant in view mode, where layer groups can be switched (see `group.control`). +#' @param group.control In view mode, the group control determines how layer +#' groups can be switched on and off. Options: `"radio"` for radio buttons +#' (meaning only one group can be shown), `"check"` for check boxes +#' (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). #' @param ... passed on to [tm_polygons()], [tm_lines()], and [tm_dots()] #' @example ./examples/tm_sf.R #' @export #' @name tm_sf #' @rdname tm_sf -tm_sf = function( fill = tm_const(), - fill.scale = tm_scale(), - fill.legend = tm_legend(), - fill.free = NA, - col = tm_const(), - col.scale = tm_scale(), - col.legend = tm_legend(), - col.free = NA, - size = tm_const(), - size.scale = tm_scale(), - size.legend = tm_legend(), - size.free = NA, - shape = tm_const(), - shape.scale = tm_scale(), - shape.legend = tm_legend(), - shape.free = NA, - lwd = tm_const(), - lwd.scale = tm_scale(), - lwd.legend = tm_legend(), - lwd.free = NA, - lty = tm_const(), - lty.scale = tm_scale(), - lty.legend = tm_legend(), - lty.free = NA, - fill_alpha = tm_const(), - fill_alpha.scale = tm_scale(), - fill_alpha.legend = tm_legend(), - fill_alpha.free = NA, - col_alpha = tm_const(), - col_alpha.scale = tm_scale(), - col_alpha.legend = tm_legend(), - col_alpha.free = NA, - linejoin = "round", - lineend = "round", - plot.order.list = list(polygons = tm_plot_order("AREA"), lines = tm_plot_order("LENGTH"), points = tm_plot_order("size")), - trans.args.list = list(polygons = list(polygons.only = "yes"), lines = list(lines.only = "yes"), points = list(points.only = "yes")), - mapping.args.list = list(polygons = list(), lines = list(), points = list(icon.scale = 3, just = NA, grob.dim = c(width=48, height=48, render.width=256, render.height=256))), - zindex = NA, - group = NA, - group.control = "check", - ...) { - +tm_sf = function(fill = tm_const(), + fill.scale = tm_scale(), + fill.legend = tm_legend(), + fill.free = NA, + col = tm_const(), + col.scale = tm_scale(), + col.legend = tm_legend(), + col.free = NA, + size = tm_const(), + size.scale = tm_scale(), + size.legend = tm_legend(), + size.free = NA, + shape = tm_const(), + shape.scale = tm_scale(), + shape.legend = tm_legend(), + shape.free = NA, + lwd = tm_const(), + lwd.scale = tm_scale(), + lwd.legend = tm_legend(), + lwd.free = NA, + lty = tm_const(), + lty.scale = tm_scale(), + lty.legend = tm_legend(), + lty.free = NA, + fill_alpha = tm_const(), + fill_alpha.scale = tm_scale(), + fill_alpha.legend = tm_legend(), + fill_alpha.free = NA, + col_alpha = tm_const(), + col_alpha.scale = tm_scale(), + col_alpha.legend = tm_legend(), + col_alpha.free = NA, + linejoin = "round", + lineend = "round", + plot.order.list = list( + polygons = tm_plot_order("AREA"), lines = tm_plot_order("LENGTH"), points = tm_plot_order("size") + ), + trans.args.list = list( + polygons = list(polygons.only = "yes"), lines = list(lines.only = "yes"), points = list(points.only = "yes") + ), + mapping.args.list = list( + polygons = list(), + lines = list(), + points = list(icon.scale = 3, just = NA, grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)) + ), + zindex = NA, + group = NA, + group.control = "check", + ...) { args = list(...) calls = names(match.call(expand.dots = TRUE)[-1]) #paste(paste(names(formals(tm_polygons)), names(formals(tm_polygons)), sep = " = "), collapse = ", ") - tm = tm_polygons(fill = fill, fill.scale = fill.scale, fill.legend = fill.legend, fill.free = fill.free, col = col, col.scale = col.scale, col.legend = col.legend, col.free = col.free, lwd = lwd, lwd.scale = lwd.scale, lwd.legend = lwd.legend, lwd.free = lwd.free, lty = lty, lty.scale = lty.scale, lty.legend = lty.legend, lty.free = lty.free, fill_alpha = fill_alpha, fill_alpha.scale = fill_alpha.scale, fill_alpha.legend = fill_alpha.legend, fill_alpha.free = fill_alpha.free, col_alpha = col_alpha, col_alpha.scale = col_alpha.scale, col_alpha.legend = col_alpha.legend, col_alpha.free = col_alpha.free, linejoin = linejoin, lineend = lineend, plot.order = plot.order.list$polygons, trans.args = trans.args.list$polygons, mapping.args = mapping.args.list$polygons) + - tm_lines(col = col, col.scale = col.scale, col.legend = col.legend, col.free = col.free, lwd = lwd, lwd.scale = lwd.scale, lwd.legend = lwd.legend, lwd.free = lwd.free, lty = lty, lty.scale = lty.scale, lty.legend = lty.legend, lty.free = lty.free, col_alpha = col_alpha, col_alpha.scale = col_alpha.scale, col_alpha.legend = col_alpha.legend, col_alpha.free = col_alpha.free, linejoin = linejoin, lineend = lineend, plot.order = plot.order.list$lines, trans.args = trans.args.list$lines, mapping.args = mapping.args.list$lines) + tm = tm_polygons( + fill = fill, fill.scale = fill.scale, fill.legend = fill.legend, + fill.free = fill.free, col = col, col.scale = col.scale, col.legend = col.legend, + col.free = col.free, lwd = lwd, lwd.scale = lwd.scale, lwd.legend = lwd.legend, + lwd.free = lwd.free, lty = lty, lty.scale = lty.scale, lty.legend = lty.legend, + lty.free = lty.free, fill_alpha = fill_alpha, fill_alpha.scale = fill_alpha.scale, + fill_alpha.legend = fill_alpha.legend, fill_alpha.free = fill_alpha.free, + col_alpha = col_alpha, col_alpha.scale = col_alpha.scale, + col_alpha.legend = col_alpha.legend, col_alpha.free = col_alpha.free, + linejoin = linejoin, lineend = lineend, plot.order = plot.order.list$polygons, + trans.args = trans.args.list$polygons, mapping.args = mapping.args.list$polygons) + + tm_lines( + col = col, col.scale = col.scale, col.legend = col.legend, + col.free = col.free, lwd = lwd, lwd.scale = lwd.scale, + lwd.legend = lwd.legend, lwd.free = lwd.free, lty = lty, lty.scale = lty.scale, + lty.legend = lty.legend, lty.free = lty.free, col_alpha = col_alpha, + col_alpha.scale = col_alpha.scale, col_alpha.legend = col_alpha.legend, + col_alpha.free = col_alpha.free, linejoin = linejoin, lineend = lineend, + plot.order = plot.order.list$lines, trans.args = trans.args.list$lines, + mapping.args = mapping.args.list$lines) if ("shape" %in% calls) { - tm + tm_symbols(size = size, size.scale = size.scale, size.legend = size.legend, size.free = size.free, fill = fill, fill.scale = fill.scale, fill.legend = fill.legend, fill.free = fill.free, col = col, col.scale = col.scale, col.legend = col.legend, col.free = col.free, shape = shape, shape.scale = shape.scale, shape.legend = shape.legend, shape.free = shape.free, lwd = lwd, lwd.scale = lwd.scale, lwd.legend = lwd.legend, lwd.free = lwd.free, lty = lty, lty.scale = lty.scale, lty.legend = lty.legend, lty.free = lty.free, fill_alpha = fill_alpha, fill_alpha.scale = fill_alpha.scale, fill_alpha.legend = fill_alpha.legend, fill_alpha.free = fill_alpha.free, col_alpha = col_alpha, col_alpha.scale = col_alpha.scale, col_alpha.legend = col_alpha.legend, col_alpha.free = col_alpha.free, plot.order = plot.order.list$points, trans.args = trans.args.list$points, mapping.args = mapping.args.list$points) + tm + tm_symbols(size = size, size.scale = size.scale, size.legend = size.legend, + size.free = size.free, fill = fill, fill.scale = fill.scale, + fill.legend = fill.legend, fill.free = fill.free, col = col, + col.scale = col.scale, col.legend = col.legend, col.free = col.free, + shape = shape, shape.scale = shape.scale, shape.legend = shape.legend, + shape.free = shape.free, lwd = lwd, lwd.scale = lwd.scale, lwd.legend = lwd.legend, + lwd.free = lwd.free, lty = lty, lty.scale = lty.scale, lty.legend = lty.legend, + lty.free = lty.free, fill_alpha = fill_alpha, fill_alpha.scale = fill_alpha.scale, + fill_alpha.legend = fill_alpha.legend, fill_alpha.free = fill_alpha.free, + col_alpha = col_alpha, col_alpha.scale = col_alpha.scale, + col_alpha.legend = col_alpha.legend, col_alpha.free = col_alpha.free, + plot.order = plot.order.list$points, trans.args = trans.args.list$points, + mapping.args = mapping.args.list$points) } else { - tm + tm_dots(fill = fill, fill.scale = fill.scale, fill.legend = fill.legend, fill.free = fill.free, size = size, size.scale = size.scale, size.legend = size.legend, size.free = size.free, lwd = lwd, lwd.scale = lwd.scale, lwd.legend = lwd.legend, lwd.free = lwd.free, lty = lty, lty.scale = lty.scale, lty.legend = lty.legend, lty.free = lty.free, fill_alpha = fill_alpha, fill_alpha.scale = fill_alpha.scale, fill_alpha.legend = fill_alpha.legend, fill_alpha.free = fill_alpha.free, plot.order = plot.order.list$points, trans.args = trans.args.list$points, mapping.args = mapping.args.list$points) + tm + tm_dots(fill = fill, fill.scale = fill.scale, fill.legend = fill.legend, + fill.free = fill.free, size = size, size.scale = size.scale, + size.legend = size.legend, size.free = size.free, lwd = lwd, + lwd.scale = lwd.scale, lwd.legend = lwd.legend, lwd.free = lwd.free, + lty = lty, lty.scale = lty.scale, lty.legend = lty.legend, lty.free = lty.free, + fill_alpha = fill_alpha, fill_alpha.scale = fill_alpha.scale, + fill_alpha.legend = fill_alpha.legend, fill_alpha.free = fill_alpha.free, + plot.order = plot.order.list$points, trans.args = trans.args.list$points, + mapping.args = mapping.args.list$points) } } diff --git a/R/tm_layers_symbols.R b/R/tm_layers_symbols.R index e86f18b5..783cbb93 100644 --- a/R/tm_layers_symbols.R +++ b/R/tm_layers_symbols.R @@ -1,14 +1,33 @@ #' Map layer: symbols #' -#' Map layer that draws symbols Supported visual variables are: `fill` (the fill color), `col` (the border color), `size` the symbol size, `shape` the symbol shape, `lwd` (line width), `lty` (line type), `fill_alpha` (fill color alpha transparency) and `col_alpha` (border color alpha transparency). +#' Map layer that draws symbols Supported visual variables are: +#' `fill` (the fill color), `col` (the border color), `size` the symbol size, +#' `shape` the symbol shape, `lwd` (line width), `lty` (line type), `fill_alpha` +#' (fill color alpha transparency) and `col_alpha` (border color alpha transparency). #' -#' The visual variable arguments (e.g. `col`) can be specified with either a data variable name (of the object specified in [tm_shape()]), or with a visual value (for `col`, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with [tm_facets()]. +#' The visual variable arguments (e.g. `col`) can be specified with either a data +#' variable name (of the object specified in [tm_shape()]), or with a visual value +#' (for `col`, a color is expected). Multiple values can be specified: in that case +#' facets are created. These facets can be combined with other faceting data variables, +#' specified with [tm_facets()]. #' -#' The `.scale` arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available `tm_scale_` functions. The default scale that is used is specified by the tmap option `scales.var`. +#' The `.scale` arguments determine the used scale to map the data values to visual +#' variable values. These can be specified with one of the available `tm_scale_` functions. +#' The default scale that is used is specified by the tmap option `scales.var`. #' -#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. The default legend and its settings are determined by the tmap options `legend.`. +#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. +#' The default legend and its settings are determined by the tmap options `legend.`. #' -#' The `.free` arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see [tm_facets()]). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid ([tm_facets_grid()]). For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual variable `col`, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]) there is only one facet dimension, so the `.free` argument requires only one logical value. +#' The `.free` arguments determine whether scales are applied freely across facets, +#' or shared. A logical value is required. They can also be specified with a vector +#' of three logical values; these determine whether scales are applied freely per +#' facet dimension. This is only useful when facets are applied (see [tm_facets()]). +#' There are maximally three facet dimensions: rows, columns, and pages. +#' This only applies for a facet grid ([tm_facets_grid()]). +#' For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual variable +#' `col`, each row of facets will have its own scale, and therefore its own legend. +#' For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]), +#' there is only one facet dimension, so the `.free` argument requires only one logical value. #' #' @param fill,fill.scale,fill.legend,fill.free Visual variable that determines the fill color. See details. #' @param col,col.scale,col.legend,col.free Visual variable that determines the col color. See details. @@ -16,18 +35,39 @@ #' @param shape,shape.scale,shape.legend,shape.free Visual variable that determines the shape. See details. #' @param lwd,lwd.scale,lwd.legend,lwd.free Visual variable that determines the line width. See details. #' @param lty,lty.scale,lty.legend,lty.free Visual variable that determines the line type. See details. -#' @param fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free Visual variable that determines the fill color alpha transparency See details. -#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable that determines the border color alpha transparency. See details. -#' @param plot.order Specification in which order the spatial features are drawn. See [tm_plot_order()] for details. -#' @param trans.args,mapping.args lists that are passed on to internal transformation and mapping functions respectively -#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called. -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). -#' @param popup.vars names of data variables that are shown in the popups in `"view"` mode. Set popup.vars to `TRUE` to show all variables in the shape object. Set popup.vars to `FALSE` to disable popups. Set popup.vars to a character vector of variable names to those those variables in the popups. The default (`NA`) depends on whether visual variables (e.g.`col`) are used. If so, only those are shown. If not all variables in the shape object are shown. -#' @param 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. +#' @param fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free Visual variable that determines +#' the fill color alpha transparency See details. +#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable that determines +#' the border color alpha transparency. See details. +#' @param plot.order Specification in which order the spatial features are drawn. +#' See [tm_plot_order()] for details. +#' @param trans.args,mapping.args lists that are passed on to internal +#' transformation and mapping functions respectively +#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers +#' (one for each map layer) determines the stacking order. By default the map +#' layers are drawn in the order they are called. +#' @param group Name of the group to which this layer belongs. +#' This is only relevant in view mode, where layer groups can be switched +#' (see `group.control`) +#' @param group.control In view mode, the group control determines how layer +#' groups can be switched on and off. Options: `"radio"` for radio buttons +#' (meaning only one group can be shown), `"check"` for check boxes +#' (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). +#' @param popup.vars names of data variables that are shown in the popups in +#' `"view"` mode. Set popup.vars to `TRUE` to show all variables in the shape object. +#' Set popup.vars to `FALSE` to disable popups. Set popup.vars to a character vector +#' of variable names to those those variables in the popups. The default (`NA`) +#' depends on whether visual variables (e.g.`col`) are used. If so, only those are shown. +#' If not all variables in the shape object are shown. +#' @param 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. #' @param hover name of the data variable that specifies the hover labels #' -#' @param id name of the data variable that specifies the indices of the spatial features. Only used for `"view"` mode. +#' @param id name of the data variable that specifies the indices of the spatial features. +#' Only used for `"view"` mode. #' @param ... to catch deprecated arguments from version < 4.0 #' @example ./examples/tm_symbols.R #' @export diff --git a/R/tm_layers_text.R b/R/tm_layers_text.R index 8c3381a0..4a3c0fb9 100644 --- a/R/tm_layers_text.R +++ b/R/tm_layers_text.R @@ -1,27 +1,58 @@ #' Map layer: text #' -#' Map layer that draws symbols Supported visual variables are: `text` (the text itself) `col` (color), `size` (font size), and `fontface` (font face). +#' Map layer that draws symbols Supported visual variables are: `text` +#' (the text itself) `col` (color), `size` (font size), and `fontface` (font face). #' -#' The visual variable arguments (e.g. `col`) can be specified with either a data variable name (of the object specified in [tm_shape()]), or with a visual value (for `col`, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with [tm_facets()]. +#' The visual variable arguments (e.g. `col`) can be specified with either a +#' data variable name (of the object specified in [tm_shape()]), or with a visual +#' value (for `col`, a color is expected). Multiple values can be specified: +#' in that case facets are created. These facets can be combined with other +#' faceting data variables, specified with [tm_facets()]. #' -#' The `.scale` arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available `tm_scale_` functions. The default scale that is used is specified by the tmap option `scales.var`. +#' The `.scale` arguments determine the used scale to map the data values to +#' visual variable values. These can be specified with one of the available +#' `tm_scale_()` functions. The default scale that is used is specified by the +#' tmap option `scales.var`. #' -#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. The default legend and its settings are determined by the tmap options `legend.`. +#' The `.legend` arguments determine the used legend, specified with [tm_legend()]. +#' The default legend and its settings are determined by the tmap options `legend.`. #' -#' The `.free` arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see [tm_facets()]). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid ([tm_facets_grid()]). For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual variable `col`, each row of facets will has its own scale, and therefore its own legend. For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]) there is only one facet dimension, so the `.free` argument requires only one logical value. +#' The `.free` arguments determine whether scales are applied freely across facets, +#' or shared. A logical value is required. They can also be specified with a +#' vector of three logical values; these determine whether scales are applied +#' freely per facet dimension. This is only useful when facets are applied +#' (see [tm_facets()]). There are maximally three facet dimensions: rows, columns, +#' and pages. This only applies for a facet grid ([tm_facets_grid()]). +#' For instance, `col.free = c(TRUE, FALSE, FALSE)` means that for the visual +#' variable `col`, each row of facets will has its own scale, and therefore its +#' own legend. For facet wraps and stacks ([tm_facets_wrap()] and [tm_facets_stack()]) +#' there is only one facet dimension, so the `.free` argument requires only one logical value. #' -#' @param text,text.scale,text.legend,text.free Visual variable that determines the text. See details. -#' @param size,size.scale,size.legend,size.free Visual variable that determines the font size. See details. -#' @param col,col.scale,col.legend,col.free Visual variable that determines the col color. See details. -#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable that determines the border color alpha transparency. See Details. -#' @param fontface,fontface.scale,fontface.legend,fontface.free Visual variable that determines the font face. See Details. +#' @param text,text.scale,text.legend,text.free Visual variable that determines +#' the text. See details. +#' @param size,size.scale,size.legend,size.free Visual variable that determines +#' the font size. See details. +#' @param col,col.scale,col.legend,col.free Visual variable that determines +#' the col color. See details. +#' @param col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free Visual variable that determines +#' the border color alpha transparency. See Details. +#' @param fontface,fontface.scale,fontface.legend,fontface.free Visual variable that determines +#' the font face. See Details. #' @param fontfamily The font family. See [gpar()][grid::gpar()] for details. #' @param shadow Shadow behind the text. Logical or color. -#' @param plot.order Specification in which order the spatial features are drawn. See [tm_plot_order()] for details. -#' @param trans.args,mapping.args lists that are passed on to internal transformation and mapping functions respectively -#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called. -#' @param group Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see `group.control`) -#' @param group.control In view mode, the group control determines how layer groups can be switched on and off. Options: `"radio"` for radio buttons (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), and `"none"` for no control (the group cannot be (de)selected). +#' @param plot.order Specification in which order the spatial features are drawn. +#' See [tm_plot_order()] for details. +#' @param trans.args,mapping.args lists that are passed on to internal transformation +#' and mapping functions respectively. +#' @param zindex Map layers are drawn on top of each other. The `zindex` numbers +#' (one for each map layer) determines the stacking order. +#' By default the map layers are drawn in the order they are called. +#' @param group Name of the group to which this layer belongs. This is only +#' relevant in view mode, where layer groups can be switched (see `group.control`) +#' @param group.control In view mode, the group control determines how layer +#' groups can be switched on and off. Options: `"radio"` for radio buttons +#' (meaning only one group can be shown), `"check"` for check boxes (so multiple groups can be shown), +#' and `"none"` for no control (the group cannot be (de)selected). #' @param ... to catch deprecated arguments from version < 4.0 #' @example ./examples/tm_lines.R #' @export diff --git a/R/tm_layout.R b/R/tm_layout.R index 0728c1f0..b35344a7 100644 --- a/R/tm_layout.R +++ b/R/tm_layout.R @@ -8,7 +8,7 @@ #' #' Set of tmap options that are directly related to the layout. #' -#' @param modes,crs,facet.max,facet.flip,raster.max.cells,show.messages,show.warnings,output.format,output.size,output.dpi,output.dpi.animation,value.const,value.na,value.null,value.blank,values.var,values.range,value.neutral,scales.var,scale.misc.args,label.format,label.na,scale,asp,bg.color,outer.bg.color,frame,frame.lwd,frame.r,frame.double.line,outer.margins,inner.margins,inner.margins.extra,meta.margins,meta.auto.margins,between.margin,component.offset,component.stack.margin,grid.mark.height,xylab.height,coords.height,xlab.show,xlab.text,xlab.size,xlab.color,xlab.rotation,xlab.space,xlab.fontface,xlab.fontfamily,xlab.side,ylab.show,ylab.text,ylab.size,ylab.color,ylab.rotation,ylab.space,ylab.fontface,ylab.fontfamily,ylab.side,panel.type,panel.wrap.pos,panel.xtab.pos,unit,color.sepia.intensity,color.saturation,color.vision.deficiency.sim,text.fontface,text.fontfamily,legend.show,legend.design,legend.orientation,legend.position,legend.width,legend.height,legend.stack,legend.group.frame,legend.resize.as.group,legend.reverse,legend.na.show,legend.title.color,legend.title.size,legend.title.fontface,legend.title.fontfamily,legend.xlab.color,legend.xlab.size,legend.xlab.fontface,legend.xlab.fontfamily,legend.ylab.color,legend.ylab.size,legend.ylab.fontface,legend.ylab.fontfamily,legend.text.color,legend.text.size,legend.text.fontface,legend.text.fontfamily,legend.frame,legend.frame.lwd,legend.frame.r,legend.bg.color,legend.bg.alpha,legend.settings.standard.portrait,legend.settings.standard.landscape,title.show,title.size,title.color,title.fontface,title.fontfamily,title.bg.color,title.bg.alpha,title.padding,title.frame,title.frame.lwd,title.frame.r,title.stack,title.position,title.group.frame,title.resize.as.group,credits.show,credits.size,credits.color,credits.fontface,credits.fontfamily,credits.bg.color,credits.bg.alpha,credits.padding,credits.frame,credits.frame.lwd,credits.frame.r,credits.stack,credits.position,credits.width,credits.heigth,credits.group.frame,credits.resize.as.group,compass.north,compass.type,compass.text.size,compass.size,compass.show.labels,compass.cardinal.directions,compass.text.color,compass.color.dark,compass.color.light,compass.lwd,compass.bg.color,compass.bg.alpha,compass.margins,compass.show,compass.stack,compass.position,compass.frame,compass.frame.lwd,compass.frame.r,compass.group.frame,compass.resize.as.group,scalebar.show,scalebar.breaks,scalebar.width,scalebar.text.size,scalebar.text.color,scalebar.color.dark,scalebar.color.light,scalebar.lwd,scalebar.position,scalebar.bg.color,scalebar.bg.alpha,scalebar.size,scalebar.margins,scalebar.stack,scalebar.frame,scalebar.frame.lwd,scalebar.frame.r,scalebar.group.frame,scalebar.resize.as.group,grid.show,grid.labels.pos,grid.x,grid.y,grid.n.x,grid.n.y,grid.crs,grid.col,grid.lwd,grid.alpha,grid.labels.show,grid.labels.size,grid.labels.col,grid.labels.rot,grid.labels.format,grid.labels.cardinal,grid.labels.margin.x,grid.labels.margin.y,grid.labels.space.x,grid.labels.space.y,grid.labels.inside.frame,grid.ticks,grid.lines,grid.ndiscr,mouse_coordinates.stack,mouse_coordinates.position,mouse_coordinates.show,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,qtm.scalebar,qtm.minimap,qtm.mouse.coordinates,earth.boundary,earth.boundary.color,earth.boundary.lwd,earth.datum,space.color,attr.color,max.categories,legend.hist.bg.color,legend.hist.bg.alpha,legend.hist.size,legend.hist.height,legend.hist.width,attr.outside,attr.outside.position,attr.outside.size,attr.position,attr.just,basemap.server,basemap.alpha,basemap.zoom,overlays,overlays.alpha,alpha,colorNA,symbol.size.fixed,dot.size.fixed,text.size.variable,bbox,check.and.fix,set.bounds,set.view,set.zoom.limits,name,basemap.show see[tmap_options()] +#' @param modes,crs,facet.max,facet.flip,raster.max.cells,show.messages,show.warnings,output.format,output.size,output.dpi,output.dpi.animation,value.const,value.na,value.null,value.blank,values.var,values.range,value.neutral,scales.var,scale.misc.args,label.format,label.na,scale,asp,bg.color,outer.bg.color,frame,frame.lwd,frame.r,frame.double.line,outer.margins,inner.margins,inner.margins.extra,meta.margins,meta.auto.margins,between.margin,component.offset,component.stack.margin,grid.mark.height,xylab.height,coords.height,xlab.show,xlab.text,xlab.size,xlab.color,xlab.rotation,xlab.space,xlab.fontface,xlab.fontfamily,xlab.side,ylab.show,ylab.text,ylab.size,ylab.color,ylab.rotation,ylab.space,ylab.fontface,ylab.fontfamily,ylab.side,panel.type,panel.wrap.pos,panel.xtab.pos,unit,color.sepia.intensity,color.saturation,color.vision.deficiency.sim,text.fontface,text.fontfamily,legend.show,legend.design,legend.orientation,legend.position,legend.width,legend.height,legend.stack,legend.group.frame,legend.resize.as.group,legend.reverse,legend.na.show,legend.title.color,legend.title.size,legend.title.fontface,legend.title.fontfamily,legend.xlab.color,legend.xlab.size,legend.xlab.fontface,legend.xlab.fontfamily,legend.ylab.color,legend.ylab.size,legend.ylab.fontface,legend.ylab.fontfamily,legend.text.color,legend.text.size,legend.text.fontface,legend.text.fontfamily,legend.frame,legend.frame.lwd,legend.frame.r,legend.bg.color,legend.bg.alpha,legend.settings.standard.portrait,legend.settings.standard.landscape,title.show,title.size,title.color,title.fontface,title.fontfamily,title.bg.color,title.bg.alpha,title.padding,title.frame,title.frame.lwd,title.frame.r,title.stack,title.position,title.group.frame,title.resize.as.group,credits.show,credits.size,credits.color,credits.fontface,credits.fontfamily,credits.bg.color,credits.bg.alpha,credits.padding,credits.frame,credits.frame.lwd,credits.frame.r,credits.stack,credits.position,credits.width,credits.heigth,credits.group.frame,credits.resize.as.group,compass.north,compass.type,compass.text.size,compass.size,compass.show.labels,compass.cardinal.directions,compass.text.color,compass.color.dark,compass.color.light,compass.lwd,compass.bg.color,compass.bg.alpha,compass.margins,compass.show,compass.stack,compass.position,compass.frame,compass.frame.lwd,compass.frame.r,compass.group.frame,compass.resize.as.group,scalebar.show,scalebar.breaks,scalebar.width,scalebar.text.size,scalebar.text.color,scalebar.color.dark,scalebar.color.light,scalebar.lwd,scalebar.position,scalebar.bg.color,scalebar.bg.alpha,scalebar.size,scalebar.margins,scalebar.stack,scalebar.frame,scalebar.frame.lwd,scalebar.frame.r,scalebar.group.frame,scalebar.resize.as.group,grid.show,grid.labels.pos,grid.x,grid.y,grid.n.x,grid.n.y,grid.crs,grid.col,grid.lwd,grid.alpha,grid.labels.show,grid.labels.size,grid.labels.col,grid.labels.rot,grid.labels.format,grid.labels.cardinal,grid.labels.margin.x,grid.labels.margin.y,grid.labels.space.x,grid.labels.space.y,grid.labels.inside.frame,grid.ticks,grid.lines,grid.ndiscr,mouse_coordinates.stack,mouse_coordinates.position,mouse_coordinates.show,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,qtm.scalebar,qtm.minimap,qtm.mouse.coordinates,earth.boundary,earth.boundary.color,earth.boundary.lwd,earth.datum,space.color,attr.color,max.categories,legend.hist.bg.color,legend.hist.bg.alpha,legend.hist.size,legend.hist.height,legend.hist.width,attr.outside,attr.outside.position,attr.outside.size,attr.position,attr.just,basemap.server,basemap.alpha,basemap.zoom,overlays,overlays.alpha,alpha,colorNA,symbol.size.fixed,dot.size.fixed,text.size.variable,bbox,check.and.fix,set.bounds,set.view,set.zoom.limits,name,basemap.show See [tmap_options()] #' @param title,main.title deprecated #' @param ... used to catch other deprecated arguments #' @rdname tm_layout @@ -58,10 +58,17 @@ tm_layout = function( #' @param control.position position of the control attribute #' @param control.bases base layers #' @param control.overlays overlay layers -#' @param set.bounds logical that determines whether maximum bounds are set, or a bounding box. Not applicable in plot mode. In view mode, this is passed on to [setMaxBounds()][leaflet::setMaxBounds()] -#' @param set.view numeric vector that determines the view. Either a vector of three: `lng`, `lat`, and `zoom`, or a single value: `zoom`. See [setView()][leaflet::setView()]. Only applicable if `bbox` is not specified -#' @param set.zoom.limits numeric vector of two that set the minimum and maximum zoom levels (see [tileOptions()][leaflet::tileOptions()]). -#' @param leaflet.options options passed on to [leafletOptions()][leaflet::leafletOptions()] +#' @param set.bounds logical that determines whether maximum bounds are set, +#' or a bounding box. Not applicable in plot mode. +#' In view mode, this is passed on to [setMaxBounds()][leaflet::setMaxBounds()] +#' @param set.view numeric vector that determines the view. +#' Either a vector of three: `lng`, `lat`, and `zoom`, or a single value: +#' `zoom`. See [setView()][leaflet::setView()]. +#' Only applicable if `bbox` is not specified +#' @param set.zoom.limits numeric vector of two that set the minimum and maximum +#' zoom levels (see [tileOptions()][leaflet::tileOptions()]). +#' @param leaflet.options options passed on to +#' [leafletOptions()][leaflet::leafletOptions()] #' @export tm_view = function(use.WebGL, control.position, diff --git a/R/tm_plot_order.R b/R/tm_plot_order.R index a8c9abbe..b5bbf152 100644 --- a/R/tm_plot_order.R +++ b/R/tm_plot_order.R @@ -2,9 +2,23 @@ #' #' Determine plotting order of features. #' -#' @param aes Visual variable for which the values determine the plotting order. Example: bubble map where the `"size"` aesthetic is used. A data variable (say population) is mapped via a continuous scale ([tm_scale_continuous()]) to bubble sizes. The bubbles are plotted in order of size. How is determined by the other arguments. Use `"DATA"` to keep the same order as in the data. Another special value are `"AREA"` and `"LENGTH"` which are preserved for polygons and lines respectively: rather than a data variable the polygon area / line lengths determines the plotting order. -#' @param reverse Logical that determines whether the visual values are plotted in reversed order. The visual values (specified with tmap option `"values.var"`) are by default reversed, so plotted starting from the last value. In the bubble map example, this means that large bubbles are plotted first, hence at the bottom. -#' @param na.order Where should features be plotted that have an `NA` value for (at least) one other aesthetic variable? In the (order) `"mix"`, at the `"bottom"`, or on `"top"`? In the bubble map example: if fill color is missing for some bubble, where should those bubbles be plotted? +#' @param aes Visual variable for which the values determine the plotting order. +#' Example: bubble map where the `"size"` aesthetic is used. +#' A data variable (say population) is mapped via a continuous scale ([tm_scale_continuous()]) +#' to bubble sizes. The bubbles are plotted in order of size. +#' How is determined by the other arguments. Use `"DATA"` to keep the same +#' order as in the data. Another special value are `"AREA"` and `"LENGTH"` +#' which are preserved for polygons and lines respectively: rather than a data +#' variable the polygon area / line lengths determines the plotting order. +#' @param reverse Logical that determines whether the visual values are plotted +#' in reversed order. The visual values (specified with tmap option `"values.var"`) +#' are by default reversed, so plotted starting from the last value. +#' In the bubble map example, this means that large bubbles are plotted first, +#' hence at the bottom. +#' @param na.order Where should features be plotted that have an `NA` value for +#' (at least) one other aesthetic variable? In the (order) `"mix"`, at the `"bottom"`, +#' or on `"top"`? In the bubble map example: if fill color is missing for some bubble, +#' where should those bubbles be plotted? #' @param null.order Where should non-selected (aka null) features be plotted? #' @param null.below.na Should null features be plotted below NA features? #' @export diff --git a/R/tm_pos.R b/R/tm_pos.R index c2fd57a8..e125bb68 100644 --- a/R/tm_pos.R +++ b/R/tm_pos.R @@ -1,11 +1,34 @@ #' Set the position of map components #' -#' Set the position of map components, such as legends, title, compass, scale bar, etc. `tm_pos()` is the function to position these components: `tm_pos_out()` places the components outside the map area and `tm_pos_in()` inside the map area. Each `position` argument of a map layer or component should be specified with one of these functions. The functions `tm_pos_auto_out()` and `tm_pos_auto_in()` are used to set the components automatically, and are recommended to use globally, via [tmap_options()]. See Details how the positioning works. +#' Set the position of map components, such as legends, title, compass, scale bar, etc. +#' `tm_pos()` is the function to position these components: +#' `tm_pos_out()` places the components outside the map area and `tm_pos_in()` inside the map area. +#' Each `position` argument of a map layer or component should be specified with +#' one of these functions. The functions `tm_pos_auto_out()` and `tm_pos_auto_in()` +#' are used to set the components automatically, and are recommended to use globally, +#' via [tmap_options()]. See Details how the positioning works. #' -#' @param cell.h,cell.v The plotting area is overlaid with a 3x3 grid, of which the middle grid cell is the map area. Components can be drawn into any cell. `cell.h` specifies the horizontal position (column) can take values `"left"`, `"center"`, and `"right"`, and `cell.v` specifies the vertical position (row) and can take values `"top"`, `"center"`, and `"bottom"`. See details for a graphical explanation. -#' @param pos.h,pos.v The position of the component within the cell. The main options for `pos.h` are `"left"`, `"center"`, and `"right"`, and for `cell.v` these are `"top"`, `"center"`, and `"bottom"`. These options can also be provided in upper case; in that case there is no offset (see the tmap option `component.offset`). Also numbers between 0 and 1 can be provided, which determine the position of the component inside the cell (with (0,0) being left bottom). The arguments `just.h` and `just.v` determine the justification point. -#' @param align.h,align.v The alignment of the component in case multiple components are stacked. When they are stacked horizontally, `align.v` determines how components that are smaller in height than the available height (determined by the outer.margins if specified and otherwise by the highest component) are justified: `"top"`, `"center"`, or `"bottom"`. Similarly, `align.h` determines how components are justified horizontally when they are stacked vertically: `"left"`, `"center"`, or `"right"`. -#' @param just.h,just.v The justification of the components. Only used in case `pos.h` and `pos.v` are numbers. +#' @param cell.h,cell.v The plotting area is overlaid with a 3x3 grid, of which +#' the middle grid cell is the map area. Components can be drawn into any cell. +#' `cell.h` specifies the horizontal position (column) can take values +#' `"left"`, `"center"`, and `"right"`. `cell.v` specifies the vertical position +#' (row) and can take values `"top"`, `"center"`, and `"bottom"`. +#' See details for a graphical explanation. +#' @param pos.h,pos.v The position of the component within the cell. +#' The main options for `pos.h` are `"left"`, `"center"`, and `"right"`. +#' For `cell.v` these are `"top"`, `"center"`, and `"bottom"`. +#' These options can also be provided in upper case; in that case there is no offset +#' (see the tmap option `component.offset`). Also numbers between 0 and 1 can be provided, +#' which determine the position of the component inside the cell (with (0,0) being left bottom). +#' The arguments `just.h` and `just.v` determine the justification point. +#' @param align.h,align.v The alignment of the component in case multiple components are stacked. +#' When they are stacked horizontally, `align.v` determines how components +#' that are smaller in height than the available height (determined by the outer.margins +#' if specified and otherwise by the highest component) are justified: +#' `"top"`, `"center"`, or `"bottom"`. Similarly, `align.h` determines how components +#' are justified horizontally when they are stacked vertically: `"left"`, `"center"`, or `"right"`. +#' @param just.h,just.v The justification of the components. +#' Only used in case `pos.h` and `pos.v` are numbers. #' @details #' #' | | | | | | @@ -28,21 +51,53 @@ #' | |   `"left"` |   `"center"` |    `"right"` | | #' | | |   `cell.h` | | | #' -#' `tm_pos_in()` sets the position of the component(s) inside the maps area, which is equivalent to the center-center cell (in case there are facets, these are all drawn in this center-center cell). +#' `tm_pos_in()` sets the position of the component(s) inside the maps area, +#' which is equivalent to the center-center cell (in case there are facets, +#' these are all drawn in this center-center cell). #' #' `tm_pos_out()` sets the position of the component(s) outside the map. #' -#' The amount of space that the top and bottom rows, and left and right columns occupy is determined by the [tm_layout()] arguments `meta.margins` and `meta.auto.margins`. The former sets the relative space of the bottom, left, top, and right side. In case these are set to `NA`, the space is set automatically based on 1) the maximum relative space specified by `meta.auto.margins` and 2) the presence and size of components in each cell. For instance, if there is one landscape oriented legend in the center-bottom cell, then the relative space of the bottom row is set to the height of that legend (given that it is smaller than the corresponding value of `meta.auto.margins`), while the other four sides are set to 0. +#' The amount of space that the top and bottom rows, and left and right columns +#' occupy is determined by the [tm_layout()] arguments `meta.margins` and `meta.auto.margins`. +#' The former sets the relative space of the bottom, left, top, and right side. +#' In case these are set to `NA`, the space is set automatically based on 1) +#' the maximum relative space specified by `meta.auto.margins` and 2) +#' the presence and size of components in each cell. +#' For instance, if there is one landscape oriented legend in the center-bottom cell, +#' then the relative space of the bottom row is set to the height of that legend +#' (given that it is smaller than the corresponding value of `meta.auto.margins`), +#' while the other four sides are set to 0. #' -#' `tm_pos_auto_out()` is more complex: the `cell.h` and `cell.v` arguments of should be set to one of the four corners. It does not mean that the components are drawn in a corner. The corner represents the sides of the map that the components are drawn. By default, legends are drawn either at the bottom or on the right-side of the map by default (see `tmap_options("legend.position")`). Only when there are row- and column-wise legends and a general legend (using [tm_facets_grid()]), the general legend is drawn in the corner, but in practice this case will be rare. +#' `tm_pos_auto_out()` is more complex: the `cell.h` and `cell.v` arguments should be set +#' to one of the four corners. It does not mean that the components are drawn in a corner. +#' The corner represents the sides of the map that the components are drawn. +#' By default, legends are drawn either at the bottom or on the right-side of +#' the map by default (see `tmap_options("legend.position")`). +#' Only when there are row- and column-wise legends and a general legend (using [tm_facets_grid()]), +#' the general legend is drawn in the corner, but in practice this case will be rare. #' -#' The arguments `pos.h` and `pos.v` determine where the components are drawn within the cell. Again, with `"left"`, `"center"`, and `"right"` for `pos.h` and `"top"`, `"center"`, and `"bottom"` for `pos.v`. The values can also be specified in upper-case, which influences the offset with the cell borders, which is determined by tmap option `component.offset`. By default, there is a small offset when components are drawn inside and no offset when they are drawn outside or with upper-case. +#' The arguments `pos.h` and `pos.v` determine where the components are drawn within the cell. +#' Again, with `"left"`, `"center"`, and `"right"` for `pos.h` +#' and `"top"`, `"center"`, and `"bottom"` for `pos.v`. +#' The values can also be specified in upper-case, which influences the offset +#' with the cell borders, which is determined by tmap option `component.offset`. +#' By default, there is a small offset when components are drawn inside and no +#' offset when they are drawn outside or with upper-case. #' -#' `tm_pos_auto_in()` automatically determines `pos.h` and `pos.v` given the available space inside the map. This is similar to the default positioning in tmap3. +#' `tm_pos_auto_in()` automatically determines `pos.h` and `pos.v` given the +#' available space inside the map. This is similar to the default positioning in tmap3. #' -#' In case multiple components are draw in the same cell and the same position inside that cell, they are stacked (determined which the `stack` argument in the legend or component function). The `align.h` and `align.v` arguments determine how these components will be justified with each other. +#' In case multiple components are draw in the same cell and the same position +#' inside that cell, they are stacked (determined which the `stack` argument in +#' the legend or component function). The `align.h` and `align.v` arguments +#' determine how these components will be justified with each other. #' -#' Note that legends and components may be different for a facet row or column. This is the case when [tm_facets_grid()] or [tm_facets_stack()] are applied and when scales are set to free (with the `.free` argument of the map layer functions). In case a legends or components are draw row- or column wise, and the position of the legends (or components) is right next to the maps, these legends (or components) will be aligned with the maps. +#' Note that legends and components may be different for a facet row or column. +#' This is the case when [tm_facets_grid()] or [tm_facets_stack()] are applied +#' and when scales are set to free (with the `.free` argument of the map layer functions). +#' In case a legends or components are draw row- or column wise, and the position +#' of the legends (or components) is right next to the maps, these legends +#' (or components) will be aligned with the maps. #' #' @export #' @name tm_pos diff --git a/R/tm_scale_.R b/R/tm_scale_.R index ecc32622..8c85de8d 100644 --- a/R/tm_scale_.R +++ b/R/tm_scale_.R @@ -18,11 +18,17 @@ tm_shape_vars = function() { #' Scales: automatic scale #' -#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. Such function should be used for the input of the `.scale` arguments in the layer functions (e.g. `fill.scale` in [tm_polygons()]). The function `tm_scale()` is a scale that is set automatically given by the data type (factor, numeric, and integer) and the visual variable. The tmap option `scales.var` contains information which scale is applied when. +#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. +#' Such function should be used for the input of the `.scale` arguments in the +#' layer functions (e.g. `fill.scale` in [tm_polygons()]). The function `tm_scale()` +#' is a scale that is set automatically given by the data type (factor, numeric, and integer) +#' and the visual variable. The tmap option `scales.var` contains information +#' which scale is applied when. #' #' @param ... arguments passed on to the applied scale function `tm_scale_*()` #' @export tm_scale = function(...) { + # maybe add the generic scales parameters after ... here? structure(c(list(FUN = "tmapScaleAuto"), list(...)), class = c("tm_scale_auto", "tm_scale", "list")) } @@ -52,7 +58,14 @@ tm_scale_ordinal = function(n.max = 30, #' Scales: categorical and ordinal scale #' -#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. Such function should be used for the input of the `.scale` arguments in the layer functions (e.g. `fill.scale` in [tm_polygons()]). The functions `tm_scale_categorical()` and `tm_scale_ordinal()` are used for categorical data. The only difference between these functions is that the former assumes unordered categories whereas the latter assumes ordered categories. For colors (the visual variable `fill` or `col`), different default color palettes are used (see the tmap option `values.var`). +#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. +#' Such function should be used for the input of the `.scale` arguments in the +#' layer functions (e.g. `fill.scale` in [tm_polygons()]). +#' The functions `tm_scale_categorical()` and `tm_scale_ordinal()` are used +#' for categorical data. The only difference between these functions is that the +#' former assumes unordered categories whereas the latter assumes ordered categories. +#' For colors (the visual variable `fill` or `col`), different default color +#' palettes are used (see the tmap option `values.var`). #' #' @param n.max Maximum number of categories (factor levels). In case there are more, they are grouped into `n.max` groups. #' @param values (generic scale argument) The visual values. For colors (e.g. `fill` or `col` for `tm_polygons()`) this is a palette name from the `cols4all` package (see [cols4all::c4a()]) or vector of colors, for size (e.g. `size` for `tm_symbols()`) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. `shape` for [tm_symbols()]) these are a set of symbols, etc. The tmap option `values.var` contains the default values per visual variable and in some cases also per data type. @@ -90,7 +103,10 @@ tm_scale_categorical = function(n.max = 30, #' Scales: interval scale #' -#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. Such function should be used for the input of the `.scale` arguments in the layer functions (e.g. `fill.scale` in [tm_polygons()]). The function `tm_scale_interval` is used for numerical data. +#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. +#' Such function should be used for the input of the `.scale` arguments in the +#' layer functions (e.g. `fill.scale` in [tm_polygons()]). +#' The function `tm_scale_interval()` is used for numerical data. #' #' @param n Number of intervals. For some styles (see argument `style` below) it is the preferred number rather than the exact number. #' @param style Method to create intervals. Options are `"cat"`, `"fixed"`, `"sd"`, `"equal"`, `"pretty"`, `"quantile"`, `"kmeans"`, `"hclust"`, `"bclust"`, `"fisher"`, `"jenks"`, `"dpih"`, `"headtails"`, and `"log10_pretty"`. See the details in [classInt::classIntervals()] (extra arguments can be passed on via `style.args`). @@ -134,7 +150,10 @@ tm_scale_intervals = function(n = 5, #' Scales: discrete scale #' -#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. Such function should be used for the input of the `.scale` arguments in the layer functions (e.g. `fill.scale` in [tm_polygons()]). The function `tm_scale_discrete()` is used for discrete numerical data, such as integers. +#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. +#' Such function should be used for the input of the `.scale` arguments in the +#' layer functions (e.g. `fill.scale` in [tm_polygons()]). +#' The function `tm_scale_discrete()` is used for discrete numerical data, such as integers. #' #' @param ticks Discrete values. If not specified, it is determined automatically: unique values are put on a discrete scale. #' @param midpoint The data value that is interpreted as the midpoint. By default it is set to 0 if negative and positive values are present. Useful when values are diverging colors. 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. If it is specified for sequential color palettes (e.g. `"Blues"`), then this color palette will be treated as a diverging color palette. @@ -169,7 +188,11 @@ tm_scale_discrete = function(ticks = NA, #' Scales: continuous scale #' -#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. Such function should be used for the input of the `.scale` arguments in the layer functions (e.g. `fill.scale` in [tm_polygons()]). The function `tm_scale_continuous` is used for continuous data. The functions `tm_scale_continuous_` use transformation functions x. +#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. +#' Such function should be used for the input of the `.scale` arguments in the layer +#' functions (e.g. `fill.scale` in [tm_polygons()]). +#' The function `tm_scale_continuous()` is used for continuous data. +#' The functions `tm_scale_continuous_()` use transformation functions x. #' #' @param n Preferred number of tick labels. Only used if `ticks` is not specified #' @param limits Limits of the data values that are mapped to the continuous scale diff --git a/R/tm_scale_bivariate.R b/R/tm_scale_bivariate.R index 4d91e74a..0d84dfb6 100644 --- a/R/tm_scale_bivariate.R +++ b/R/tm_scale_bivariate.R @@ -1,8 +1,11 @@ #' Scales: bivariate scale #' -#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. Such function should be used for the input of the `.scale` arguments in the layer functions (e.g. `fill.scale` in [tm_polygons()]). The function `tm_scale_bivariate()` is used or `bivariate.scales`. +#' Scales in tmap are configured by the family of functions with prefix `tm_scale`. +#' Such function should be used for the input of the `.scale` arguments in the +#' layer functions (e.g. `fill.scale` in [tm_polygons()]). +#' The function `tm_scale_bivariate()` is used for `bivariate.scales`. #' -#' @param scale1,scale2 two `tm_scale` objects. Currently, all `tm_scale_` functions are supported except `tm_scale_continous()`. +#' @param scale1,scale2 two `tm_scale` objects. Currently, all `tm_scale_*()` functions are supported except `tm_scale_continous()`. #' @param values (generic scale argument) The visual values. For colors (e.g. `fill` or `col` for `tm_polygons()`) this is a palette name from the `cols4all` package (see [cols4all::c4a()]) or vector of colors, for size (e.g. `size` for `tm_symbols()`) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. `shape` for [tm_symbols()]) these are a set of symbols, etc. The tmap option `values.var` contains the default values per visual variable and in some cases also per data type. #' @param values.repeat (generic scale argument) Should the values be repeated in case there are more categories? #' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a grey scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark grey to light grey are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. diff --git a/R/tm_shape.R b/R/tm_shape.R index 9b0b06ed..8c12d657 100644 --- a/R/tm_shape.R +++ b/R/tm_shape.R @@ -1,10 +1,12 @@ #' Shape (spatial object) specification #' -#' Specify a shape, which is a spatial object from one of these spatial object class packages: [`sf`][`sf::sf`], [`stars`][stars::st_as_stars()], `terra`. +#' Specify a shape, which is a spatial object from one of these spatial object +#' class packages: [`sf`][`sf::sf`], [`stars`][stars::st_as_stars()], or `terra`. #' #' @param shp Spatial object #' @param name Name of the shape -#' @param is.main Is `shp` the main shape, which determines the crs and bounding box of the map? +#' @param is.main Is `shp` the main shape, which determines the crs and +#' bounding box of the map? #' @param crs CRS to which `shp` is reprojected (only used if `is.main = TRUE`) #' @param bbox Bounding box of he map (only used if `is.main = TRUE`) #' @param unit Unit of the coordinates diff --git a/R/tmapSplitShp.R b/R/tmapSplitShp.R index 448f4e6e..6d221110 100644 --- a/R/tmapSplitShp.R +++ b/R/tmapSplitShp.R @@ -1,6 +1,7 @@ #' Internal method that split shape objects #' -#' Internal method that split shape objects. So far, only used to split stars object (from dimension to attributes) +#' Internal method that split shape objects. So far, only used to split stars object +#' (from dimension to attributes) #' #' @param shp shape #' @param split_stars_dim name of the dimension to split (`""` to skip) diff --git a/R/tmap_animation.R b/R/tmap_animation.R index 02271b6c..191d522e 100644 --- a/R/tmap_animation.R +++ b/R/tmap_animation.R @@ -2,17 +2,34 @@ #' #' Create a gif animation or video from a tmap plot. #' -#' @param tm tmap or a list of tmap objects. If `tm` is a tmap object, facets should be created, where nrow and ncol in [tm_facets()] have to be set to 1 in order to create one map per frame. -#' @param filename filename. If omitted (default), the animation will be shown in the viewer or browser. If specified, it should be a gif file or a video file (i.e. mp4). The package `gifski` is required to create a gif animation. The package `av` (which uses the `FFmpeg` library) is required for video formats. The mp4 format is recommended but many other video formats are supported, such as wmv, avi, and mkv. -#' @param width,height width and height of the animation file (in pixels). Required when `tm` is a list, and recommended to specify in advance when `tm` is a `tmap` object. If not specified in the latter case, it will be determined by the aspect ratio of the map. -#' @param dpi dots per inch. By default 100, but this can be set with the option `output.dpi.animation` in [tmap_options()]. +#' @param tm tmap or a list of tmap objects. If `tm` is a tmap object, +#' facets should be created, where `nrow` and `ncol` in [tm_facets()] have to +#' be set to 1 in order to create one map per frame. +#' @param filename filename. If omitted (default), the animation will be shown +#' in the viewer or browser. If specified, it should be a gif file or a video +#' file (i.e. mp4). The package `gifski` is required to create a gif animation. +#' The package `av` (which uses the `FFmpeg` library) is required for video formats. +#' The mp4 format is recommended but many other video formats are supported, +#' such as wmv, avi, and mkv. +#' @param width,height Dimensions of the animation file (in pixels). +#' Required when `tm` is a list, and recommended to specify in advance when +#' `tm` is a `tmap` object. If not specified in the latter case, it will be +#' determined by the aspect ratio of the map. +#' @param dpi dots per inch. By default 100, but this can be set with the option +#' `output.dpi.animation` in [tmap_options()]. #' @param delay delay time between images (in 1/100th of a second). See also `fps` -#' @param fps frames per second, calculated as `100 / delay`. If `fps` is specified, the `delay` will be set to `100/fps`. -#' @param loop logical that determined whether the animation is looped, or an integer value that determines how many times the animation is looped. -#' @param outer.margins (passed on to [tmap_save()]) overrides the outer.margins argument of [tm_layout()] (unless set to `NA`) -#' @param asp (passed on to [tmap_save()]) if specified, it overrides the asp argument of [tm_layout()]. Tip: set to `0` if map frame should be placed on the edges of the image. -#' @param scale (passed on to [tmap_save()]) overrides the scale argument of [tm_layout()] (unless set to `NA`) -#' @param restart.delay not used anymore +#' @param fps frames per second, calculated as `100 / delay`. If `fps` is specified, +#' the `delay` will be set to `100/fps`. +#' @param loop logical that determined whether the animation is looped, or an +#' integer value that determines how many times the animation is looped. +#' @param outer.margins (passed on to [tmap_save()]) overrides the outer.margins +#' argument of `tm_layout()` (unless set to `NA`) +#' @param asp (passed on to [tmap_save()]) if specified, it overrides the `asp` +#' argument of `tm_layout()`. Tip: set to `0` if map frame should be placed on +#' the edges of the image. +#' @param scale (passed on to [tmap_save()]) overrides the scale argument of +#' [tm_layout()] (unless set to `NA`) +#' @param restart.delay not used anymore. #' @param ... arguments passed on to [av::av_encode_video()] #' @note Not only tmap plots are supported, but any series of R plots. #' @concept animation diff --git a/R/tmap_arrange.R b/R/tmap_arrange.R index 232c29e3..b9e199a4 100644 --- a/R/tmap_arrange.R +++ b/R/tmap_arrange.R @@ -1,18 +1,34 @@ #' Arrange small multiples in grid layout #' -#' Arrange small multiples in a grid layout. Normally, small multiples are created by specifying multiple variables for one aesthetic or by specifying the by argument (see [tm_facets()]). This function can be used to arrange custom small multiples in a grid layout. +#' Arrange small multiples in a grid layout. Normally, small multiples are created +#' by specifying multiple variables for one aesthetic or by specifying the by argument +#' (see [tm_facets()]). This function can be used to arrange custom small multiples in a grid layout. #' -#' The global option `tmap.limits` controls the limit of the number of facets that are plotted. By default, `tmap_options(tmap.limits = c(facets.view=4, facets.plot=64))`. The maximum number of interactive facets is set to four since otherwise it may become very slow. +#' The global option `tmap.limits` controls the limit of the number of facets that are plotted. +#' By default, `tmap_options(tmap.limits = c(facets.view=4, facets.plot=64))`. +#' The maximum number of interactive facets is set to four since otherwise it may become very slow. #' -#' @param ... [`tmap`] objects or one list of [`tmap`] objects. The number of multiples that can be plot is limited (see details). +#' @param ... [`tmap`] objects or one list of [`tmap`] objects. +#' The number of multiples that can be plot is limited (see details). #' @param ncol number of columns #' @param nrow number of rows -#' @param widths vector of column widths. It should add up to 1 and the length should be equal to `ncol` -#' @param heights vector of row heights. It should add up to 1 and the length should be equal to `nrow` -#' @param sync logical. Should the navigation in view mode (zooming and panning) be synchronized? By default `FALSE`. -#' @param asp aspect ratio. The aspect ratio of each map. Normally, this is controlled by the `asp` argument from [tm_layout()] (also a tmap option). This argument will overwrite it, unless set to `NULL`. The default value for `asp` is 0, which means that the aspect ratio is adjusted to the size of the device divided by the number of columns and rows. When `asp` is set to `NA`, which is also the default value for [tm_layout()], the aspect ratio will be adjusted to the used shapes. -#' @param outer.margins outer.margins, numeric vector four or a single value. If defines the outer margins for each multiple. If will overwrite the `outer.margins` argument from [tm_layout()], unless set to `NULL`. -#' @param x a `tmap_arrange` object (returned from `tmap_arrange()`) +#' @param widths vector of column widths. It should add up to 1 and the length +#' should be equal to `ncol`. +#' @param heights vector of row heights. It should add up to 1 and the length +#' should be equal to `nrow`. +#' @param sync logical. Should the navigation in view mode (zooming and panning) +#' be synchronized? By default `FALSE`. +#' @param asp aspect ratio. The aspect ratio of each map. Normally, this is +#' controlled by the `asp` argument from [tm_layout()] (also a tmap option). +#' This argument will overwrite it, unless set to `NULL`. +#' The default value for `asp` is 0, which means that the aspect ratio is +#' adjusted to the size of the device divided by the number of columns and rows. +#' When `asp` is set to `NA`, which is also the default value for `tm_layout()`, +#' the aspect ratio will be adjusted to the used shapes. +#' @param outer.margins outer.margins, numeric vector four or a single value. +#' If defines the outer margins for each multiple. If will overwrite the +#' `outer.margins` argument from [tm_layout()], unless set to `NULL`. +#' @param x a `tmap_arrange` object (returned from `tmap_arrange()`). #' @param knit should [knitr::knit_print()] be enabled, or the normal [base::print()] function? #' @param options options passed on to [knitr::knit_print()] #' @example ./examples/tmap_arrange.R diff --git a/R/tmap_format.R b/R/tmap_format.R index cf5dc05a..10a5ddcd 100644 --- a/R/tmap_format.R +++ b/R/tmap_format.R @@ -1,12 +1,18 @@ #' Get or add format options #' -#' Format options are tmap options that are shape dependent. With `tmap_format()` the predefined formats can be retrieved. The values for a specific format can be retrieved with `tmap_format(format)`, where format is the name of the format. The function `tmap_format_add()` is used to add a format. +#' Format options are tmap options that are shape dependent. +#' With `tmap_format()` the predefined formats can be retrieved. +#' The values for a specific format can be retrieved with `tmap_format(format)`, +#' where format is the name of the format. The function `tmap_format_add()` is used to add a format. #' #' @param format Name of the format. Run `tmap_format()` to see the choices. -#' @return The function `tmap_format()` returns the names of the available formats. When `format` is defined, it returns the option list corresponding the that format. -#' @seealso [tm_layout()] for predefined styles, `tmap_style_catalogue` (not migrated to v4 yet) to create a style catalogue of all available styles, and [tmap_options()] for tmap options. +#' @return The function `tmap_format()` returns the names of the available formats. +#' When `format` is defined, it returns the option list corresponding the that format. +#' @seealso +#' * [tm_layout()] for predefined styles +#' * `tmap_style_catalogue` (not migrated to v4 yet) to create a style catalogue of all available styles +#' * [tmap_options()] for tmap options #' @example ./examples/tmap_format.R -#' @seealso [tmap_options()] for tmap options #' @rdname tmap_format #' @export tmap_format = function(format) { diff --git a/R/tmap_icons.R b/R/tmap_icons.R index 0a00ac7e..d00d4267 100644 --- a/R/tmap_icons.R +++ b/R/tmap_icons.R @@ -1,19 +1,25 @@ #' Specify icons #' -#' Specifies icons from a png images, which can be used as markers in thematic maps. The function `marker_icon()` is the specification of the default marker. +#' Specifies icons from a png images, which can be used as markers in thematic maps. +#' The function `marker_icon()` is the specification of the default marker. #' #' @param file character value/vector containing the file path(s) or url(s). #' @param width width of the icon. If `keep.asp`, this is interpreted as the maximum width. #' @param height height of the icon. If `keep.asp`, this is interpreted as the maximum height. -#' @param keep.asp keep the aspect ratio of the png image. If `TRUE` and the aspect ratio differs from `width/height` either `width` or `height` is adjusted accordingly. -#' @param just justification of the icons 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 alignment and 1 right alignment. The default value of `just` is `c("center", "center")`. +#' @param keep.asp keep the aspect ratio of the png image. If `TRUE` and the aspect +#' ratio differs from `width/height`, either `width` or `height` is adjusted accordingly. +#' @param just justification of the icons 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 alignment and 1 right alignment. +#' The default value of `just` is `c("center", "center")`. #' @param as.local if the `file` is a url, should it be saved to local temporary file? -#' @param ... arguments passed on to [leaflet::icons()]. When `iconWidth`, `iconHeight`, `iconAnchorX` and `iconAnchorY` are specified, they override `width` and `height`, and `just`. +#' @param ... arguments passed on to [leaflet::icons()]. +#' When `iconWidth`, `iconHeight`, `iconAnchorX`, and `iconAnchorY` are specified, +#' they override `width` and `height`, and `just`. #' @return icon data (see [leaflet::icons()]) #' @export #' @seealso [tm_symbols()] -#' @name tmap_icons -#' @rdname tmap_icons tmap_icons <- function(file, width=48, height=48, keep.asp=TRUE, just=c("center", "center"), as.local=TRUE, ...) { icon_names <- names(file) icons <- lapply(file, tmap_one_icon, width=width, height=height, keep.asp=keep.asp, just=just, as.local=as.local, ...) diff --git a/R/tmap_leaflet.R b/R/tmap_leaflet.R index ae12b84a..4929c734 100644 --- a/R/tmap_leaflet.R +++ b/R/tmap_leaflet.R @@ -8,7 +8,8 @@ #' @inheritDotParams print.tmap #' @return #' * `tmap_grid()` returns a [`grob`][grid::grob()] object (`"plot"` mode) -#' * `tmap_leaflet()` a [`leaflet`][leaflet::leaflet()] object (`"view"` mode). In case small multiples are shown, a list is returned. +#' * `tmap_leaflet()` a [`leaflet`][leaflet::leaflet()] object (`"view"` mode). +#' In case small multiples are shown, a list is returned. #' @export #' @examples #' map = tm_shape(World) + tm_polygons() diff --git a/R/tmap_mode.R b/R/tmap_mode.R index 4173d3b6..096d5378 100644 --- a/R/tmap_mode.R +++ b/R/tmap_mode.R @@ -1,25 +1,56 @@ #' Set tmap mode to static plotting or interactive viewing #' -#' Set tmap mode to static plotting or interactive viewing. The global option `tmap.mode` determines the whether thematic maps are plot in the graphics device, or shown as an interactive leaflet map (see also [tmap_options()]. The function `tmap_mode` is a wrapper to set this global option. The convenient function `ttm`, which stands for toggle thematic map, is a toggle switch between the two modes. The function `ttmp` stands for toggle thematic map and print last map: it does the same as `ttm` followed by [tmap_last()]; in order words, it shows the last map in the other mode. It is recommended to use `tmap_mode()` in scripts and `ttm`/`ttmp` in the console. +#' Set tmap mode to static plotting or interactive viewing. +#' The global option `tmap.mode` determines the whether thematic maps are plot +#' in the graphics device, or shown as an interactive leaflet map (see also [tmap_options()]. +#' The function `tmap_mode()` is a wrapper to set this global option. +#' The convenient function `ttm()`, which stands for toggle thematic map, +#' is a toggle switch between the two modes. The function `ttmp()` stands for +#' toggle thematic map and print last map: it does the same as `ttm()` followed +#' by [tmap_last()]; in order words, it shows the last map in the other mode. +#' It is recommended to use `tmap_mode()` in scripts and `ttm()`/`ttmp()` in the console. #' -#' @param mode One of: -#' \describe{ -#' \item{`"plot"`}{Thematic maps are shown in the graphics device. This is the default mode, and supports all tmap's features, such as small multiples (see [tm_facets()]) and extensive layout settings (see [tm_layout()]). It is recommended for saving static maps (see [tmap_save()]).} -#' \item{`"view"`}{Thematic maps are viewed interactively in the web browser or RStudio's Viewer pane. Maps are fully interactive with tiles from OpenStreetMap or other map providers (see [tm_tiles()]). See also [tm_view()] for options related to the `"view"` mode. This mode generates a [leaflet::leaflet()] widget, which can also be directly obtained with [tmap_leaflet()]. With R Markdown, it is possible to publish it to an HTML page. -#' There are a couple of constraints in comparison to `"plot"`: -#' \itemize{ -#' \item The map is always projected according to the Web Mercator projection. Although this projection is the de facto standard for interactive web-based mapping, it lacks the equal-area property, which is important for many thematic maps, especially choropleths (see examples from [tm_shape()]). -#' \item Small multiples are not supported -#' \item The legend cannot be made for aesthetics regarding size, which are symbol size and line width. -#' \item Text labels are not supported (yet) -#' \item The layout options set with [tm_layout()]) regarding map format are not used. However, the styling options still apply.} -#' }} -#' @return The mode before changing +#' # mode = "plot" +#' +#' Thematic maps are shown in the graphics device. +#' This is the default mode, and supports all tmap's features, +#' such as small multiples (see [tm_facets()]) and extensive layout settings (see [tm_layout()]). +#' It is recommended to use [tmap_save()] for saving static maps. +#' +#' # mode = "view" +#' +#' Thematic maps are viewed interactively in the web browser or RStudio's Viewer pane. +#' Maps are fully interactive with tiles from OpenStreetMap or other map providers +#' (see [tm_tiles()]). See also [tm_view()] for options related to the `"view"` mode. +#' This mode generates a [leaflet::leaflet()] widget, which can also be directly +#' obtained with [tmap_leaflet()]. +#' With R Markdown, it is possible to publish it to an HTML page. +#' +#' However, there are a couple of constraints in comparison to `"plot"`: +#' +#' * The map is always projected according to the Web Mercator projection. +#' Although this projection is the de facto standard for interactive web-based mapping, +#' it lacks the equal-area property, which is important for many thematic maps, +#' especially choropleths (see examples from [tm_shape()]). +#' * Small multiples are not supported +#' * The legend cannot be made for aesthetics regarding size, which are symbol size and line width. +#' * Text labels are not supported (yet) +#' * The layout options set with [tm_layout()]) regarding map format are not used. +#' However, the styling options still apply. +#' +#' @param mode One of `"plot"` or `"view"`. See Details for more info. +#' @return The previous tmap mode before switching. #' @example ./examples/tmap_mode.R -#' @seealso `vignette("tmap_sneak_peek")`, [tmap_last()] to show the last map, [tm_view()] for viewing options, and [tmap_leaflet()] for obtaining a leaflet widget, and [tmap_options()] for tmap options. -#' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} +#' @seealso +#' * `vignette("tmap_sneak_peek")` +#' * [tmap_last()] to show the last map +#' * [tm_view()] for viewing options +#' * [tmap_leaflet()] for obtaining a leaflet widget +#' * [tmap_options()] for tmap options +#' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, +#' Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} #' @export -tmap_mode = function(mode=NULL) { +tmap_mode = function(mode = NULL) { current.mode = getOption("tmap.mode") tOpt = get("tmapOptions", envir = .TMAP) @@ -52,10 +83,15 @@ get_modes = function() { #' Set the design mode #' -#' When the so-called "design mode" is enabled, inner and outer margins, legend position, and aspect ratio are shown explicitly in plot mode. Also, information about aspect ratios is printed in the console. This function sets the global option `tmap.design.mode`. It can be used as toggle function without arguments. +#' When the so-called "design mode" is enabled, inner and outer margins, +#' legend position, and aspect ratio are shown explicitly in plot mode. +#' Also, information about aspect ratios is printed in the console. +#' This function sets the global option `tmap.design.mode`. +#' It can be used as toggle function without arguments. #' #' @seealso [tmap_options()] -#' @param design.mode Logical value that determines the design mode. If omitted then the design mode is toggled. +#' @param design.mode Logical value that determines the design mode. +#' If omitted then the design mode is toggled. #' @export tmap_design_mode = function(design.mode) { dm = if (missing(design.mode)) { @@ -66,14 +102,18 @@ tmap_design_mode = function(design.mode) { } options(tmap.design.mode = dm) - message("design.mode: ", if (!dm) "OFF" else "ON", if (dm && getOption("tmap.mode") == "view") " (only effective in plot mode)" else "") + message( + "design.mode: ", if (!dm) "OFF" else "ON", + if (dm && getOption("tmap.mode") == "view") " (only effective in plot mode)" else "") } #' Set the development mode #' -#' When the so-called "development mode" is enabled, helpful messages and timings are printed in the console +#' When the so-called "development mode" is enabled, helpful messages and timings +#' are printed in the console #' -#' @param devel.mode logical value that determines the development mode. If omitted then the development mode is toggled. +#' @param devel.mode logical value that determines the development mode. +#' If omitted then the development mode is toggled. #' @export tmap_devel_mode = function(devel.mode) { dm = if (missing(devel.mode)) { diff --git a/R/tmap_options.R b/R/tmap_options.R index 9f2b3017..936be8f0 100644 --- a/R/tmap_options.R +++ b/R/tmap_options.R @@ -93,8 +93,10 @@ fill_alpha = 0, col_alpha = 0 ), - values.var = list(fill = list(seq = "hcl.blues3", div = "pu_gn_div", unord = "tol.muted", ord = "hcl.blues3", cyc = "tol.rainbow_pu_rd", biv = "pu_gn_bivs"), - col = list(seq = "hcl.blues3", div = "pu_gn_div", unord = "tol.muted", ord = "hcl.blues3", cyc = "tol.rainbow_pu_rd", biv = "pu_gn_bivs"), + values.var = list(fill = list(seq = "hcl.blues3", div = "pu_gn_div", + unord = "tol.muted", ord = "hcl.blues3", cyc = "tol.rainbow_pu_rd", biv = "pu_gn_bivs"), + col = list(seq = "hcl.blues3", div = "pu_gn_div", + unord = "tol.muted", ord = "hcl.blues3", cyc = "tol.rainbow_pu_rd", biv = "pu_gn_bivs"), size = tmap_seq(0, 1, power = "sqrt"), size.bubbles = tmap_seq(0, 1, power = "sqrt"), lwd = c(0, 3), @@ -105,7 +107,9 @@ col_alpha = c(0.25, 1), shape = 21:25, area = c(0, 1)), - values.range = list(fill = NA, col = NA, size = c(0, 1), lwd = c(0.1, 1), lty = NA, text = NA, fontface = NA, fill_alpha = NA, col_alpha = NA, shape = NA), # NA = automatic, NULL is not applicable + values.range = list(fill = NA, col = NA, size = c(0, 1), lwd = c(0.1, 1), + lty = NA, text = NA, fontface = NA, fill_alpha = NA, + col_alpha = NA, shape = NA), # NA = automatic, NULL is not applicable value.neutral = list(size = 0.75, lwd = 2, lty = "solid", @@ -235,7 +239,9 @@ legend.show = TRUE, legend.design = "standard", legend.orientation = "portrait", - legend.position = tm_pos_auto_out(cell.h = "right", cell.v = "bottom", pos.h = "left", pos.v = "top", align.h = "left", align.v = "top", just.h = "left", just.v = "top"), + legend.position = tm_pos_auto_out(cell.h = "right", cell.v = "bottom", + pos.h = "left", pos.v = "top", + align.h = "left", align.v = "top", just.h = "left", just.v = "top"), legend.width = NA, legend.height = NA, legend.stack = c(all = "vertical", per_row = "horizontal", per_col = "horizontal", all_row = "vertical", all_col = "horizontal", manual = "vertical"), @@ -1098,7 +1104,9 @@ get_vector_id = function(x, id) { #' Internal tmap function to add a default value for the layer functions #' #' @param option, one of: `"value.const"`, `"value.na"`, `"value.blank"`, `"values.var"`, `'values.range'`, `"value.neutral"`, `"scales.var"` -#' @param id name of the visual variable with layer, in the format `"x.y"`, where `x` is the visual variable and `y` is the layer. It is also possible to set `x` only; then it applies to all layer functions. +#' @param id name of the visual variable with layer, in the format `"x.y"`, +#' where `x` is the visual variable and `y` is the layer. +#' It is also possible to set `x` only; then it applies to all layer functions. #' @param value value #' @keywords internal #' @export diff --git a/R/tmap_save.R b/R/tmap_save.R index 4912ecb9..fb91af74 100644 --- a/R/tmap_save.R +++ b/R/tmap_save.R @@ -3,27 +3,64 @@ #' Save tmap to a file. This can be either a static plot (e.g. png) or an interactive map (html). #' #' @param tm tmap object -#' @param filename filename including extension, and optionally the path. The extensions pdf, eps, svg, wmf (Windows only), png, jpg, bmp, tiff, and html are supported. If the extension is missing, the file will be saved as a static plot in `"plot"` mode and as an interactive map (html) in `"view"` mode (see details). The default format for static plots is png, but this can be changed using the option `"output.format"` in [tmap_options()]. If `NA` (the default), the file is saved as "tmap01" in the default format, and the number incremented if the file already exists. -#' @param device graphic device to use. Either a device function (e.g., [`png`][grDevices::png()] or [`cairo_pdf`][grDevices::cairo_pdf()]) or a text indicating selected graphic device: "pdf", "eps", "svg", "wmf" (Windows only), "png", "jpg", "bmp", "tiff". If NULL, the graphic device is guessed based on the `filename` argument. -#' @param height,width The width and height of the plot (not applicable for html files). Units are set with the argument `units`. If one of them is not specified, this is calculated using the formula asp = width / height, where asp is the estimated aspect ratio of the map. If both are missing, they are set such that `width * height` is equal to the option `"output.size"` in [tmap_options()]. This is by default 49, meaning that is the map is a square (so aspect ratio of 1) both width and height are set to 7. -#' @param units units for width and height (`"in"`, `"cm"`, or `"mm"`). By default, pixels (`"px"`) are used if either width or height is set to a value greater than 50. Else, the units are inches (`"in"`) -#' @param dpi dots per inch. Only applicable for raster graphics. By default it is set to 300, but this can be changed using the option `"output.dpi"` in [tmap_options()]. +# The docs for filename could be put in tmap_mode. +#' @param filename filename including extension, and optionally the path. +#' The extensions pdf, eps, svg, wmf (Windows only), png, jpg, bmp, tiff, and html are supported. +#' If the extension is missing, the file will be saved as a static plot in `"plot"` +#' mode and as an interactive map (html) in `"view"` mode (see details). +#' The default format for static plots is png, but this can be changed using +#' the option `"output.format"` in [tmap_options()]. If `NA` (the default), +#' the file is saved as "tmap01" in the default format, and the number incremented +#' if the file already exists. +#' @param device graphic device to use. Either a device function +#' (e.g., [`png`][grDevices::png()] or [`cairo_pdf`][grDevices::cairo_pdf()]) +#' or a text indicating selected graphic device: "pdf", "eps", "svg", "wmf" (Windows only), "png", "jpg", "bmp", "tiff". +#' If `NULL`, the graphic device is guessed based on the `filename` argument. +#' @param height,width The dimensions of the plot (not applicable for html files). +#' Units are set with the argument `units`. If one of them is not specified, +#' this is calculated using the formula asp = width / height, where asp is the +#' estimated aspect ratio of the map. If both are missing, they are set such +#' that `width * height` is equal to the option `"output.size"` in [tmap_options()]. +#' This is by default 49, meaning that is the map is a square (so aspect ratio of 1) +#' both width and height are set to 7. +#' @param units units for width and height (`"in"`, `"cm"`, or `"mm"`). +#' By default, pixels (`"px"`) are used if either width or height is set to a +#' value greater than 50. Else, the units are inches (`"in"`). +#' @param dpi dots per inch. Only applicable for raster graphics. By default it +#' is set to 300, but this can be changed using the option `"output.dpi"` in [tmap_options()]. #' @param outer.margins overrides the outer.margins argument of [tm_layout()] (unless set to `NA`) -#' @param asp if specified, it overrides the asp argument of [tm_layout()]. Tip: set to `0` if map frame should be placed on the edges of the image. +#' @param asp if specified, it overrides the asp argument of [tm_layout()]. +#' **Tip**: set to `0` if map frame should be placed on the edges of the image. #' @param scale overrides the scale argument of [tm_layout()] (unless set to `NA`) -#' @param insets_tm tmap object of an inset map, or a list of tmap objects of multiple inset maps. The number of tmap objects should be equal to the number of viewports specified with `insets_vp`. -#' @param insets_vp [`viewport`][grid::viewport()] of an inset map, or a list of [`viewport`][grid::viewport()]s of multiple inset maps. The number of viewports should be equal to the number of tmap objects specified with `insets_tm`. +#' @param insets_tm tmap object of an inset map, or a list of tmap objects of +#' multiple inset maps. The number of tmap objects should be equal to the number +#' of viewports specified with `insets_vp`. +#' @param insets_vp [`viewport`][grid::viewport()] of an inset map, or a list +#' of [`viewport`][grid::viewport()]s of multiple inset maps. The number of +#' viewports should be equal to the number of tmap objects specified with `insets_tm`. #' @param add.titles add titles to leaflet object. -#' @param in.iframe should an interactive map be saved as an iframe? If so, two HTML files will be saved; one small parent HTML file with the iframe container, and one large child HTML file with the actual widget. See [widgetframe::saveWidgetframe()] for details. By default `FALSE` which means that one large HTML file is saved (see [saveWidget()][htmlwidgets::saveWidget()]). -#' @param selfcontained when an interactive map is saved, should the resources (e.g. JavaScript libraries) be contained in the HTML file? If `FALSE`, they are placed in an adjacent directory (see also [htmlwidgets::saveWidget()]). Note that the HTML file will often still be large when `selfcontained = FALSE`, since the map data (polygons and popups), which are also contained in the HTML file, usually take more space then the map resources. -#' @param verbose Deprecated. It is now controlled by the tmap option `show.messages` (see [tmap_options()]) -#' @param ... arguments passed on to device functions or to [`saveWidget()`][htmlwidgets::saveWidget()] or [`saveWidgetFrame()`][widgetframe::saveWidgetframe()] +#' @param in.iframe should an interactive map be saved as an iframe? +#' If so, two HTML files will be saved; one small parent HTML file with the +#' iframe container, and one large child HTML file with the actual widget. +#' See [widgetframe::saveWidgetframe()] for details. By default `FALSE`, +#' which means that one large HTML file is saved (see [saveWidget()][htmlwidgets::saveWidget()]). +#' @param selfcontained when an interactive map is saved, should the resources +#' (e.g. JavaScript libraries) be contained in the HTML file? If `FALSE`, they +#' are placed in an adjacent directory (see also [htmlwidgets::saveWidget()]). +#' Note that the HTML file will often still be large when `selfcontained = FALSE`, +#' since the map data (polygons and popups), which are also contained in the HTML file, +#' usually take more space then the map resources. +#' @param verbose Deprecated. It is now controlled by the tmap option `show.messages` +#' (see [tmap_options()]) +#' @param ... arguments passed on to device functions or to +#' [`saveWidget()`][htmlwidgets::saveWidget()] or [`saveWidgetFrame()`][widgetframe::saveWidgetframe()] #' @importFrom htmlwidgets saveWidget #' @import tmaptools #' @example ./examples/tmap_save.R #' @export tmap_save = function(tm=NULL, filename=NA, device=NULL, width=NA, height=NA, units = NA, - dpi=NA, outer.margins=NA, asp=NULL, scale=NA, insets_tm=NULL, insets_vp=NULL, add.titles = TRUE, in.iframe = FALSE, selfcontained = !in.iframe, verbose = NULL, ...) { + dpi=NA, outer.margins=NA, asp=NULL, scale=NA, insets_tm=NULL, + insets_vp=NULL, add.titles = TRUE, in.iframe = FALSE, selfcontained = !in.iframe, verbose = NULL, ...) { .tmapOptions = get("tmapOptions", envir = .TMAP) show.warnings =.tmapOptions$show.warnings if (!missing(verbose) && show.warnings) warning("The argument verbose is deprecated. Please use the option show.messages of tmap_options instead.") @@ -325,6 +362,10 @@ plot_device = function(device, ext, filename, dpi, units_target){ choose_unit = function(x) { units = ifelse(x > 50, "px", "in") - if (x > 15 && x < 100) message("The argument 'units' has been set to \"", units, "\" since the specified width or height is ", ifelse(units == "px", "greater than ", "less than or equal to "), 50, ". Specify units = \"", ifelse(units == "px", "in", "px"),"\" to change this.") + if (x > 15 && x < 100) { + message("The argument 'units' has been set to \"", + units, "\" since the specified width or height is ", + ifelse(units == "px", "greater than ", "less than or equal to "), 50, ". Specify units = \"", ifelse(units == "px", "in", "px"),"\" to change this.") + } units } diff --git a/R/tmap_style.R b/R/tmap_style.R index aa9d4371..dcb5498d 100644 --- a/R/tmap_style.R +++ b/R/tmap_style.R @@ -1,16 +1,27 @@ #' Set or get the default tmap style #' -#' Set or get the default tmap style. Without arguments, the current style is returned. Also the available styles are displayed. When a style is set, the corresponding tmap options (see [tmap_options()]) will be set accordingly. The default style (i.e. when loading the package) is `"white"`. +#' Set or get the default tmap style. Without arguments, the current style is returned. +#' Also the available styles are displayed. When a style is set, the corresponding tmap +#' options (see [tmap_options()]) will be set accordingly. +#' The default style (i.e. when loading the package) is `"white"`. #' -#' Note that [tm_style()] is used within a plot call (so it only affects that plot), whereas `tmap_style()` sets the style globally. +#' Note that [tm_style()] is used within a plot call (so it only affects that plot), +#' whereas `tmap_style()` sets the style globally. #' -#' After loading a style, the options that defined this style (i.e. the difference with the default `"white"` style) can be obtained by [tmap_options_diff()]. +#' After loading a style, the options that defined this style +#' (i.e. the difference with the default `"white"` style) can be obtained by [tmap_options_diff()]. #' -#' The documentation of [tmap_options()] (details and the examples) shows how a new style is created. +#' The documentation of [tmap_options()] (details and the examples) shows how to create a new style. #' -#' @param style Name of the style. When omitted, `tmap_style()` returns the current style and also shows all available styles. When the style is specified, `tmap_style()` sets the style accordingly. Note that in that case, all tmap options (see [tmap_options()]) will be reset according to the style definition. See [tm_layout()] for predefined styles, and `tmap_style_catalogue` (not migrated to v4 yet) for creating a catalogue. +#' @param style Name of the style. When omitted, `tmap_style()` returns the current style +#' and also shows all available styles. When the style is specified,`tmap_style()` +#' sets the style accordingly. Note that in that case, all tmap options (see [tmap_options()]) +#' will be reset according to the style definition. +#' See [tm_layout()] for predefined styles, and `tmap_style_catalogue` (not migrated to v4 yet) for creating a catalogue. #' @return The style before changing -#' @seealso [tmap_options()] for tmap options, and `tmap_style_catalogue` (not migrated to v4 yet) to create a style catalogue of all available styles. +#' @seealso +#' * [tmap_options()] for tmap options +#' * `tmap_style_catalogue` (not migrated to v4 yet) to create a style catalogue of all available styles. #' @example ./examples/tmap_style.R #' @export #' @rdname tmap_style @@ -67,5 +78,8 @@ get_style_names = function(except_style = NULL, remove_grey = TRUE) { check_style = function(style) { styles = get_style_names(remove_grey = FALSE) - if (!style %in% styles) stop("style \"" , style, "\" unknown. The available styles are: ", print_text_vector(get_style_names()), call. = FALSE) + if (!style %in% styles) { + stop("style \"" , style, "\" unknown. The available styles are: ", + print_text_vector(get_style_names()), call. = FALSE) + } } diff --git a/man/Shapes.Rd b/man/Shapes.Rd index 6b394423..aba21353 100644 --- a/man/Shapes.Rd +++ b/man/Shapes.Rd @@ -21,16 +21,22 @@ NLD_prov NLD_muni } \description{ -Maps of the world and the Netherlands (province and municipality level), class \code{\link[sf:sf]{sf}} +Maps of the world and the Netherlands (province and municipality level), +class \code{\link[sf:sf]{sf}} } \details{ -The default projections for these maps are Eckhart IV (World) and Rijksdriehoekstelsel (Netherlands). See below. The projection can be changed temporarily for plotting purposes by using the projection argument of \code{\link[=tm_shape]{tm_shape()}}. +The default projections for these maps are Eckhart IV (World) and +Rijksdriehoekstelsel (Netherlands). See below. The projection can be changed +temporarily for plotting purposes by using the projection argument of \code{\link[=tm_shape]{tm_shape()}}. -\code{World} World map. The default projection for this world map is Eckhart IV since area sizes are preserved, which is a very important property for choropleths. +\code{World} World map. The default projection for this world map is Eckhart IV +since area sizes are preserved, which is a very important property for choropleths. -\code{NLD_prov} and \code{NLD_muni}, maps of the Netherlands at province and municipality level of 2013. The used projection is the Rijksdriehoekstelsel projection. +\code{NLD_prov} and \code{NLD_muni}, maps of the Netherlands at province and municipality +level of 2013. The used projection is the Rijksdriehoekstelsel projection. -\strong{Important:} publication of these maps is only allowed when citing Statistics Netherlands (CBS) and Kadaster Nederland as source. +\strong{Important:} publication of these maps is only allowed when citing +Statistics Netherlands (CBS) and Kadaster Nederland as source. } \references{ Statistics Netherlands (2014), The Hague/Heerlen, Netherlands, \url{https://www.cbs.nl/}. diff --git a/man/qtm.Rd b/man/qtm.Rd index ffa0f594..3476bbe4 100644 --- a/man/qtm.Rd +++ b/man/qtm.Rd @@ -30,28 +30,45 @@ qtm( ) } \arguments{ -\item{shp}{One of +\item{shp}{One of: \itemize{ -\item shape object, which is an object from a class defined by the \code{\link[sf:sf]{sf}} or \code{\link[stars:st_as_stars]{stars}} package. Objects from the packages \code{sp} and \code{raster} are also supported, but discouraged. -\item Not specified, i.e. \code{qtm()} is executed. In this case a plain interactive map is shown. -\item An OpenStreetMap search string, e.g. \code{qtm("Amsterdam")}. In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim) +\item shape object, which is an object from a class defined by the \code{\link[sf:sf]{sf}} +or \code{\link[stars:st_as_stars]{stars}} package. Objects from the packages \code{sp} +and \code{raster} are also supported, but discouraged. +\item Not specified, i.e. \code{qtm()} is executed. In this case a plain interactive +map is shown. +\item An OpenStreetMap search string, e.g. \code{qtm("Amsterdam")}. In this case a +plain interactive map is shown positioned according to the results of the +search query (from OpenStreetMap nominatim) }} \item{fill, col, size, shape, lwd, lty, fill_alpha, col_alpha}{Visual variables.} -\item{by}{data variable name by which the data is split, or a vector of two variable names to split the data by two variables (where the first is used for the rows and the second for the columns). See also \code{\link[=tm_facets]{tm_facets()}}} +\item{by}{data variable name by which the data is split, or a vector of two +variable names to split the data by two variables (where the first is used +for the rows and the second for the columns). See also \code{\link[=tm_facets]{tm_facets()}}.} -\item{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. The parameters \code{symbols.size}, \code{text.size}, and \code{lines.lwd} can be scaled separately with respectively \code{symbols.scale}, \code{text.scale}, and \code{lines.scale}. See also \code{...}.} +\item{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. +The parameters \code{symbols.size}, \code{text.size}, and \code{lines.lwd} can be scaled +separately with respectively \code{symbols.scale}, \code{text.scale}, and +\code{lines.scale}. See also \code{...}.} -\item{title}{main title. For legend titles, use \code{X.style}, where X is the layer name (see \code{...}).} +\item{title}{main title. For legend titles, use \code{X.style}, where X is the +layer name (see \code{...}).} -\item{crs}{Either a \code{\link[sf:st_crs]{crs}} object or a character value (\code{PROJ.4} character string). By default, the projection is used that is defined in the \code{shp} object itself.} +\item{crs}{Either a \code{\link[sf:st_crs]{crs}} object or a character value +(\code{PROJ.4} character string). By default, the projection is used that is +defined in the \code{shp} object itself.} \item{bbox}{bounding box. Argument passed on to \code{\link[=tm_shape]{tm_shape()}}} -\item{basemaps}{name(s) of the provider or an URL of a tiled basemap. It is a shortcut to \code{\link[=tm_basemap]{tm_basemap()}}. Set to \code{NULL} to disable basemaps. By default, it is set to the tmap option \code{basemaps}.} +\item{basemaps}{name(s) of the provider or an URL of a tiled basemap. +It is a shortcut to \code{\link[=tm_basemap]{tm_basemap()}}. Set to \code{NULL} to disable basemaps. +By default, it is set to the tmap option \code{basemaps}.} -\item{overlays}{name(s) of the provider or an URL of a tiled overlay map. It is a shortcut to \code{\link[=tm_tiles]{tm_tiles()}}.} +\item{overlays}{name(s) of the provider or an URL of a tiled overlay map. +It is a shortcut to \code{\link[=tm_tiles]{tm_tiles()}}.} \item{zindex}{zindex} @@ -59,22 +76,40 @@ qtm( \item{group.control}{group.control} -\item{style}{Layout options (see \code{\link[=tm_layout]{tm_layout()}}) that define the style. See \code{\link[=tmap_style]{tmap_style()}} for details.} +\item{style}{Layout options (see \code{\link[=tm_layout]{tm_layout()}}) that define the style. +See \code{\link[=tmap_style]{tmap_style()}} for details.} -\item{format}{Layout options (see \code{\link[=tm_layout]{tm_layout()}}) that define the format. See \code{\link[=tmap_format]{tmap_format()}} for details.} +\item{format}{Layout options (see \code{\link[=tm_layout]{tm_layout()}}) that define the format. +See \code{\link[=tmap_format]{tmap_format()}} for details.} -\item{...}{arguments passed on to the \verb{tm_*} functions. The prefix of these arguments should be with the layer function name without \code{"tm_"} and a period. For instance, the palette for polygon fill color is called \code{fill.palette}. The following prefixes are supported: \code{shape.}, \code{fill.}, \code{borders.}, \code{polygons.}, \code{symbols.}, \code{dots.}, \code{lines.}, \code{raster.}, \code{text.}, \code{layout.}, \code{grid.}, \code{facets.}, and \code{view.}. Arguments that have a unique name, i.e. that does not exist in any other layer function, e.g. \code{convert2density}, can also be called without prefix.} +\item{...}{arguments passed on to the \verb{tm_*} functions. The prefix of these +arguments should be with the layer function name without \code{"tm_"} and a period. +For instance, the palette for polygon fill color is called \code{fill.palette}. +The following prefixes are supported: \code{shape.}, \code{fill.}, \code{borders.}, \code{polygons.}, +\code{symbols.}, \code{dots.}, \code{lines.}, \code{raster.}, \code{text.}, \code{layout.}, \code{grid.}, +\code{facets.}, and \code{view.}. Arguments that have a unique name, i.e. that does +not exist in any other layer function, e.g. \code{convert2density}, can also be +called without prefix.} } \value{ A \code{\link{tmap-element}} } \description{ -Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking \code{\link{tmap-element}}s. Without arguments or with a search term, this functions draws an interactive map. +Draw a thematic map quickly. This function is a convenient wrapper of the main +plotting method of stacking \code{\link{tmap-element}}s. Without arguments or with a +search term, this functions draws an interactive map. } \details{ -The first argument is a shape object (normally specified by \code{\link[=tm_shape]{tm_shape()}}). The next arguments, from \code{fill} to \code{raster}, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as \code{\link[=tm_polygons]{tm_polygons()}}, can be specified (see \code{...}). It is also possible to stack \code{\link{tmap-element}}s on a \code{qtm} plot. See examples. - -By default, a scale bar is shown. This option can be set with \code{\link[=tmap_options]{tmap_options()}} (argument \code{qtm.scalebar}). A minimap is shown by default when \code{qtm} is called without arguments of with a search term. This option can be set with \code{\link[=tmap_options]{tmap_options()}} (argument \code{qtm.minimap}). +The first argument is a shape object (normally specified by \code{\link[=tm_shape]{tm_shape()}}). +The next arguments, from \code{fill} to \code{raster}, are the aesthetics from the main +layers. The remaining arguments are related to the map layout. Any argument +from any main layer function, such as \code{\link[=tm_polygons]{tm_polygons()}}, can be specified (see \code{...}). +It is also possible to stack \code{\link{tmap-element}}s on a \code{qtm} plot. See examples. + +By default, a scale bar is shown. This option can be set with \code{\link[=tmap_options]{tmap_options()}} +(argument \code{qtm.scalebar}). A minimap is shown by default when \code{qtm} is called +without arguments of with a search term. This option can be set with \code{\link[=tmap_options]{tmap_options()}} +(argument \code{qtm.minimap}). } \examples{ data(World, rivers, metro) @@ -124,7 +159,8 @@ qtm("Amsterdam") } } \references{ -Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} +Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, +Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} } \seealso{ \code{vignette("tmap_sneak_peek")} diff --git a/man/theme_ps.Rd b/man/theme_ps.Rd index ce819c1a..71efce9d 100644 --- a/man/theme_ps.Rd +++ b/man/theme_ps.Rd @@ -21,5 +21,6 @@ theme_ps( \item{plot.legend}{should the legend(s) be shown?} } \description{ -ggplot2 theme for proportional symbols. By default, this theme only shows the plotting area, so without titles, axes, and legend +ggplot2 theme for proportional symbols. By default, this theme only shows the +plotting area, so without titles, axes, and legend. } diff --git a/man/tm_add_legend.Rd b/man/tm_add_legend.Rd index 27b0fd6a..a550105c 100644 --- a/man/tm_add_legend.Rd +++ b/man/tm_add_legend.Rd @@ -18,11 +18,15 @@ tm_add_legend( ) } \arguments{ -\item{...}{visual variables and arguments passed on to \code{tm_legend}. By default, the argument \code{type} is set to \code{"Symbols"}, which means that the supported visual variables are: \code{"fill"}, \code{"col"}, \code{"shape"}, \code{"size"}, \code{"fill_alpha"}, \code{"col_alpha"}, \code{"lty"}, \code{"lwd"}, \code{"linejoin"}, and \code{"lineend"}.} +\item{...}{visual variables and arguments passed on to \code{tm_legend()}. +By default, the argument \code{type} is set to \code{"Symbols"}, which means that the +supported visual variables are: \code{"fill"}, \code{"col"}, \code{"shape"}, \code{"size"}, +\code{"fill_alpha"}, \code{"col_alpha"}, \code{"lty"}, \code{"lwd"}, \code{"linejoin"}, and \code{"lineend"}.} \item{labels}{labels} -\item{type}{the layer type from which the visual variables (see ...) are taken. Options: \code{"Symbols"} (default), \code{"Lines"}, \code{"Polygons"}, and \code{"Text"}.} +\item{type}{the layer type from which the visual variables (see \code{...}) are taken. +Options: \code{"Symbols"} (default), \code{"Lines"}, \code{"Polygons"}, and \code{"Text"}.} \item{title}{text of the title} @@ -30,9 +34,14 @@ tm_add_legend( \item{orientation}{legend orientation} -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} +\item{group}{Name of the group to which this layer belongs. This is only +relevant in view mode, where layer groups can be switched (see \code{group.control})} -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{group.control}{In view mode, the group control determines how +layer groups can be switched on and off. Options: \code{"radio"} for radio +buttons (meaning only one group can be shown), \code{"check"} for check boxes +(so multiple groups can be shown), and \code{"none"} for no control +(the group cannot be (de)selected).} \item{resize.as.group}{resize.as.group} diff --git a/man/tm_basemap.Rd b/man/tm_basemap.Rd index 5b88cd2f..62209bd4 100644 --- a/man/tm_basemap.Rd +++ b/man/tm_basemap.Rd @@ -24,20 +24,39 @@ tm_tiles( ) } \arguments{ -\item{server}{Name of the provider or an URL. The list of available providers can be obtained with \code{providers} (tip: in RStudio, type \verb{providers$} to see the options). See \url{https://leaflet-extras.github.io/leaflet-providers/preview/} for a preview of those. When a URL is provided, it should be in template format, e.g. \code{"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"}. Use \code{NULL} in \code{tm_basemap()} to disable basemaps.} +\item{server}{Name of the provider or an URL. The list of available providers +can be obtained with \code{providers} (tip: in RStudio, type \verb{providers$} to see +the options). See \url{https://leaflet-extras.github.io/leaflet-providers/preview/} +for a preview of those. When a URL is provided, it should be in template format, +e.g. \code{"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"}. +Use \code{NULL} in \code{tm_basemap()} to disable basemaps.} \item{alpha}{Transparency level} \item{zoom}{Zoom level (only used in plot mode)} -\item{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 \code{"tmap401"}, \code{"tmap402"}, etc., except for the base tile layers, which are placed in the standard \code{"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, if \code{zindex} is set to 500, the pane will be named \code{"tmap500"}.} +\item{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 \code{"tmap401"}, \code{"tmap402"}, etc., except for the base tile +layers, which are placed in the standard \code{"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, if \code{zindex} is set to 500, the pane will +be named \code{"tmap500"}.} -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} +\item{group}{Name of the group to which this layer belongs. This is only +relevant in view mode, where layer groups can be switched (see \code{group.control})} -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{group.control}{In view mode, the group control determines how layer +groups can be switched on and off. Options: \code{"radio"} for radio buttons +(meaning only one group can be shown), \code{"check"} for check boxes +(so multiple groups can be shown), and \code{"none"} for no control +(the group cannot be (de)selected).} } \description{ -Map layer that draws tiles from a tile server. \code{tm_basemap()} draws the tile layer as basemap, i.e. as bottom layer. In contrast, \code{tm_tiles()} draws the tile layer as overlay layer, where the stacking order corresponds with the order in which this layer is called, just like other map layers. +Map layer that draws tiles from a tile server. \code{tm_basemap()} draws the tile +layer as basemap, i.e. as bottom layer. In contrast, \code{tm_tiles()} draws the +tile layer as overlay layer, where the stacking order corresponds with the +order in which this layer is called, just like other map layers. } \examples{ if (requireNamespace("maptiles")) { diff --git a/man/tm_cartogram.Rd b/man/tm_cartogram.Rd index b42fbc77..03c6a0ea 100644 --- a/man/tm_cartogram.Rd +++ b/man/tm_cartogram.Rd @@ -15,9 +15,11 @@ tm_cartogram( ) } \arguments{ -\item{size, size.scale, size.legend, size.free}{Transformation variable that determines the size of the polygons.} +\item{size, size.scale, size.legend, size.free}{Transformation variable that +determines the size of the polygons.} -\item{plot.order}{Specification in which order the spatial features are drawn. See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} +\item{plot.order}{Specification in which order the spatial features are drawn. +See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} \item{trans.args}{lists that are passed on to internal transformation function} @@ -28,17 +30,38 @@ tm_cartogram( \item{\code{col,col.scale,col.legend,col.free}}{Visual variable that determines the border color. See details.} \item{\code{lwd,lwd.scale,lwd.legend,lwd.free}}{Visual variable that determines the line width. See details.} \item{\code{lty,lty.scale,lty.legend,lty.free}}{Visual variable that determines the line type. See details.} - \item{\code{fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free}}{Visual variable that determines the fill color alpha transparency See details.} - \item{\code{col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free}}{Visual variable that determines the border color alpha transparency. See details.} + \item{\code{fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free}}{Visual +variable that determines the fill color alpha transparency See details.} + \item{\code{col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free}}{Visual variable +that determines the border color alpha transparency. See details.} \item{\code{linejoin,lineend}}{Line join and line end. See \link[grid:gpar]{gpar()} for details.} - \item{\code{trans.args,mapping.args}}{lists that are passed on to internal transformation and mapping functions respectively} - \item{\code{zindex}}{Map layers are drawn on top of each other. The \code{zindex} numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called.} - \item{\code{group}}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} - \item{\code{group.control}}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} - \item{\code{popup.vars}}{names of data variables that are shown in the popups in \code{"view"} mode. Set popup.vars to \code{TRUE} to show all variables in the shape object. Set popup.vars to \code{FALSE} to disable popups. Set popup.vars to a character vector of variable names to those those variables in the popups. The default (\code{NA}) depends on whether visual variables (e.g.\code{col}) are used. If so, only those are shown. If not all variables in the shape object are shown.} - \item{\code{popup.format}}{list of formatting options for the popup values. See the argument \code{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 \code{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.} + \item{\code{trans.args,mapping.args}}{lists that are passed on to internal transformation +and mapping functions respectively.} + \item{\code{zindex}}{Map layers are drawn on top of each other. The \code{zindex} numbers +(one for each map layer) determines the stacking order. +By default the map layers are drawn in the order they are called.} + \item{\code{group}}{Name of the group to which this layer belongs. This is only +relevant in view mode, where layer groups can be switched (see \code{group.control})} + \item{\code{group.control}}{In view mode, the group control determines how layer groups +can be switched on and off. Options: \code{"radio"} for radio buttons +(meaning only one group can be shown), \code{"check"} for check boxes +(so multiple groups can be shown), and \code{"none"} for no control +(the group cannot be (de)selected).} + \item{\code{popup.vars}}{names of data variables that are shown in the popups +in \code{"view"} mode. Set popup.vars to \code{TRUE} to show all variables in the +shape object. Set popup.vars to \code{FALSE} to disable popups. Set \code{popup.vars} +to a character vector of variable names to those those variables in the popups. +The default (\code{NA}) depends on whether visual variables (e.g.\code{fill}) are used. +If so, only those are shown. If not all variables in the shape object are shown.} + \item{\code{popup.format}}{list of formatting options for the popup values. +See the argument \code{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 \code{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.} \item{\code{hover}}{name of the data variable that specifies the hover labels} - \item{\code{id}}{name of the data variable that specifies the indices of the spatial features. Only used for \code{"view"} mode.} + \item{\code{id}}{name of the data variable that specifies the indices of the spatial +features. Only used for \code{"view"} mode.} }} } \description{ diff --git a/man/tm_facets.Rd b/man/tm_facets.Rd index bb819b1e..e466fc3c 100644 --- a/man/tm_facets.Rd +++ b/man/tm_facets.Rd @@ -67,21 +67,45 @@ tm_facets_flip() \item{orientation}{For facet stack: horizontal or vertical?} -\item{free.coords}{Logical. If the \code{by} argument is specified, should each map has its own coordinate ranges? By default \code{TRUE}, unless facets are shown in as different layers (\code{as.layers = TRUE})} - -\item{drop.units}{Logical. If the \code{by} argument is specified, should non-selected spatial units be dropped? If \code{FALSE}, they are plotted where mapped aesthetics are regarded as missing values. Not applicable for raster shapes. By default \code{TRUE}.} - -\item{drop.empty.facets}{Logical. If the \code{by} argument is specified, should empty facets be dropped? Empty facets occur when the \code{by}-variable contains unused levels. When \code{TRUE} and two \code{by}-variables are specified, empty rows and columns are dropped.} - -\item{drop.NA.facets}{Logical. If the \code{by} argument is specified, and all data values for specific facets are missing, should these facets be dropped? \code{FALSE} by default.} - -\item{sync}{Logical. Should the navigation in view mode (zooming and panning) be synchronized? By default \code{TRUE} if the facets have the same bounding box. This is generally the case when rasters are plotted, or when free.coords is \code{FALSE}.} - -\item{showNA}{If the \code{by} argument is specified, should missing values of the \code{by}-variable be shown in a facet? If two \code{by}-variables are specified, should missing values be shown in an additional row and column? If \code{NA}, missing values only are shown if they exist. Similar to the \code{useNA} argument of \link[base:table]{table()}, where \code{TRUE}, \code{FALSE}, and \code{NA} correspond to \code{"always"}, \code{"no"}, and \code{"ifany"} respectively.} +\item{free.coords}{Logical. If the \code{by} argument is specified, should each +map has its own coordinate ranges? By default \code{TRUE}, unless facets are shown +in as different layers (\code{as.layers = TRUE})} + +\item{drop.units}{Logical. If the \code{by} argument is specified, should +non-selected spatial units be dropped? If \code{FALSE}, they are plotted where +mapped aesthetics are regarded as missing values. Not applicable for +raster shapes. By default \code{TRUE}.} + +\item{drop.empty.facets}{Logical. If the \code{by} argument is specified, should +empty facets be dropped? Empty facets occur when the \code{by}-variable contains +unused levels. When \code{TRUE} and two \code{by}-variables are specified, empty rows +and columns are dropped.} + +\item{drop.NA.facets}{Logical. If the \code{by} argument is specified, and all +data values for specific facets are missing, should these facets be dropped? +\code{FALSE} by default.} + +\item{sync}{Logical. Should the navigation in view mode (zooming and panning) +be synchronized? By default \code{TRUE} if the facets have the same bounding box. +This is generally the case when rasters are plotted, or when \code{free.coords} is +\code{FALSE}.} + +\item{showNA}{If the \code{by} argument is specified, should missing values of the +\code{by}-variable be shown in a facet? If two \code{by}-variables are specified, +should missing values be shown in an additional row and column? +If \code{NA}, missing values only are shown if they exist. Similar to the +\code{useNA} argument of \link[base:table]{table()}, where \code{TRUE}, \code{FALSE}, +and \code{NA} correspond to \code{"always"}, \code{"no"}, and \code{"ifany"} respectively.} \item{textNA}{Text used for facets of missing values.} -\item{scale.factor}{Number that determines how the elements (e.g. font sizes, symbol sizes, line widths) of the small multiples are scaled in relation to the scaling factor of the shapes. The elements are scaled to the \code{scale.factor}th root of the scaling factor of the shapes. So, for \code{scale.factor=1}, they are scaled proportional to the scaling of the shapes. Since elements, especially text, are often too small to read, a higher value is recommended. By default, \code{scale.factor=2}.} +\item{scale.factor}{Number that determines how the elements (e.g. font sizes, +symbol sizes, line widths) of the small multiples are scaled in relation to +the scaling factor of the shapes. The elements are scaled to the \code{scale.factor}th +root of the scaling factor of the shapes. So, for \code{scale.factor=1}, +they are scaled proportional to the scaling of the shapes. Since elements, +especially text, are often too small to read, a higher value is recommended. +By default, \code{scale.factor=2}.} \item{type}{\code{"grid"}, \code{"wrap"} or \code{"stack"}} @@ -90,5 +114,10 @@ tm_facets_flip() \item{...}{passed on to \code{tm_facets()}} } \description{ -Specify facets. \code{tm_facets()} is the core function, but recommended is to use \code{tm_facets_wrap()}, \code{tm_facets_stack()} or \code{tm_facets_grid()}. The former two specify facets for one grouping variable (so one faceting dimension). The difference is that wrap may place facets in multiple rows and columns whereas \code{tm_facets_stack()} stacks the facets either horizontally or vertically. \code{tm_facets_grid()} supports up to three faceting dimensions. +Specify facets. \code{tm_facets()} is the core function, but recommended is to use +\code{tm_facets_wrap()}, \code{tm_facets_stack()} or \code{tm_facets_grid()}. +The former two specify facets for one grouping variable (so one faceting dimension). +The difference is that wrap may place facets in multiple rows and columns whereas +\code{tm_facets_stack()} stacks the facets either horizontally or vertically. +\code{tm_facets_grid()} supports up to three faceting dimensions. } diff --git a/man/tm_grid.Rd b/man/tm_grid.Rd index 520d7db1..fd45bbdf 100644 --- a/man/tm_grid.Rd +++ b/man/tm_grid.Rd @@ -47,26 +47,44 @@ tm_grid( ) } \arguments{ -\item{x}{X coordinates for vertical grid lines. If \code{NA}, it is specified with a pretty scale and \code{n.x}.} +\item{x}{X coordinates for vertical grid lines. If \code{NA}, it is specified +with a pretty scale and \code{n.x}.} -\item{y}{Y coordinates for horizontal grid lines. If \code{NA}, it is specified with a pretty scale and \code{n.y}.} +\item{y}{Y coordinates for horizontal grid lines. If \code{NA}, it is specified +with a pretty scale and \code{n.y}.} -\item{n.x}{Preferred number of grid lines for the x axis. For the labels, a \code{\link[=pretty]{pretty()}} sequence is used, so the number of actual labels may be different than \code{n.x}.} +\item{n.x}{Preferred number of grid lines for the x axis. For the labels, +a \code{\link[=pretty]{pretty()}} sequence is used, so the number of actual labels may be different than \code{n.x}.} -\item{n.y}{Preferred number of grid lines for the y axis. For the labels, a \code{\link[=pretty]{pretty()}} sequence is used, so the number of actual labels may be different than \code{n.y}.} +\item{n.y}{Preferred number of grid lines for the y axis. For the labels, a +\code{\link[=pretty]{pretty()}} sequence is used, so the number of actual labels may be different than \code{n.y}.} -\item{crs}{Projection character. If specified, the grid lines are projected accordingly. Many world maps are projected, but still have latitude longitude (EPSG 4326) grid lines.} +\item{crs}{Projection character. If specified, the grid lines are projected +accordingly. Many world maps are projected, but still have latitude longitude +(EPSG 4326) grid lines.} \item{labels.format}{List of formatting options for the grid labels. Parameters are: \describe{ -\item{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 \code{scientific}, \code{format}, and \code{digits} (see below) are not used.} -\item{scientific}{Should the labels be formatted scientifically? If so, square brackets are used, and the \code{format} of the numbers is \code{"g"}. Otherwise, \code{format="f"}, and \code{text.separator}, \code{text.less.than}, and \code{text.or.more} are used. Also, the numbers are automatically rounded to millions or billions if applicable.} -\item{format}{By default, \code{"f"}, i.e. the standard notation \code{xxx.xxx}, is used. If \code{scientific=TRUE} then \code{"g"}, which means that numbers are formatted scientifically, i.e. \code{n.dddE+nn} if needed to save space.} -\item{digits}{Number of digits after the decimal point if \code{format="f"}, and the number of significant digits otherwise.} +\item{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 \code{scientific}, +\code{format}, and \code{digits} (see below) are not used.} +\item{scientific}{Should the labels be formatted scientifically? +If so, square brackets are used, and the \code{format} of the numbers is \code{"g"}. +Otherwise, \code{format="f"}, and \code{text.separator}, \code{text.less.than}, and +\code{text.or.more} are used. Also, the numbers are automatically rounded to +millions or billions if applicable.} +\item{format}{By default, \code{"f"}, i.e. the standard notation \code{xxx.xxx}, is used. +If \code{scientific=TRUE} then \code{"g"}, which means that numbers are formatted scientifically, +i.e. \code{n.dddE+nn} if needed to save space.} +\item{digits}{Number of digits after the decimal point if \code{format="f"}, and +the number of significant digits otherwise.} \item{...}{Other arguments passed on to \code{\link[=formatC]{formatC()}}} }} -\item{labels.cardinal}{Add the four cardinal directions (N, E, S, W) to the labels, instead of using negative coordinates for west and south (so it assumes that the coordinates are positive in the north-east direction).} +\item{labels.cardinal}{Add the four cardinal directions (N, E, S, W) to the labels, +instead of using negative coordinates for west and south (so it assumes that +the coordinates are positive in the north-east direction).} \item{...}{Arguments passed on to \code{\link[=tm_grid]{tm_grid()}}} @@ -74,42 +92,73 @@ tm_grid( \item{lwd}{Line width of the grid lines} -\item{alpha}{Alpha transparency of the grid lines. Number between 0 and 1. By default, the alpha transparency of \code{col} is taken.} +\item{alpha}{Alpha transparency of the grid lines. Number between 0 and 1. +By default, the alpha transparency of \code{col} is taken.} -\item{labels.show}{Show tick labels. Either one value for both \code{x} and \code{y} axis, or a vector two: the first for \code{x} and latter for \code{y}.} +\item{labels.show}{Show tick labels. Either one value for both \code{x} and \code{y} axis, +or a vector two: the first for \code{x} and latter for \code{y}.} -\item{labels.pos}{position of the labels. Vector of two: the horizontal ("left" or "right") and the vertical ("top" or "bottom") position.} +\item{labels.pos}{position of the labels. Vector of two: the horizontal +("left" or "right") and the vertical ("top" or "bottom") position.} \item{labels.size}{Font size of the tick labels} \item{labels.col}{Font color of the tick labels} -\item{labels.rot}{Rotation angles of the labels. Vector of two values: the first is the rotation angle (in degrees) of the tick labels on the x axis and the second is the rotation angle of the tick labels on the y axis. Only \code{0}, \code{90}, \code{180}, and \code{270} are valid values.} +\item{labels.rot}{Rotation angles of the labels. Vector of two values: the +first is the rotation angle (in degrees) of the tick labels on the x axis +and the second is the rotation angle of the tick labels on the y axis. +Only \code{0}, \code{90}, \code{180}, and \code{270} are valid values.} -\item{labels.margin.x}{Margin between tick labels of x axis and the frame. Note that when \code{labels.inside.frame == FALSE} and \code{ticks == TRUE}, the ticks will be adjusted accordingly.} +\item{labels.margin.x}{Margin between tick labels of x axis and the frame. +Note that when \code{labels.inside.frame == FALSE} and \code{ticks == TRUE}, +the ticks will be adjusted accordingly.} -\item{labels.margin.y}{Margin between tick labels of y axis and the frame. Note that when \code{labels.inside.frame == FALSE} and \code{ticks == TRUE}, the ticks will be adjusted accordingly.} +\item{labels.margin.y}{Margin between tick labels of y axis and the frame. +Note that when \code{labels.inside.frame == FALSE} and \code{ticks == TRUE}, +the ticks will be adjusted accordingly.} -\item{labels.space.x}{Space that is used for the labels and ticks for the x-axis when \code{labels.inside.frame == FALSE}. By default, it is determined automatically using the widths and heights of the tick labels. The unit of this parameter is text line height.} +\item{labels.space.x}{Space that is used for the labels and ticks for the x-axis +when \code{labels.inside.frame == FALSE}. By default, it is determined automatically +using the widths and heights of the tick labels. The unit of this parameter is text line height.} -\item{labels.space.y}{Space that is used for the labels and ticks for the y-axis when \code{labels.inside.frame == FALSE}. By default, it is determined automatically using the widths and heights of the tick labels. The unit of this parameter is text line height.} +\item{labels.space.y}{Space that is used for the labels and ticks for the y-axis +when \code{labels.inside.frame == FALSE}. By default, it is determined automatically +using the widths and heights of the tick labels. The unit of this parameter is text line height.} -\item{labels.inside.frame}{Show labels inside the frame? By default \code{FALSE}} +\item{labels.inside.frame}{Show labels inside the frame? By default \code{FALSE}.} -\item{ticks}{If \code{labels.inside.frame = FALSE}, should ticks can be drawn between the labels and the frame? Either one value for both \code{x} and \code{y} axis, or a vector two: the first for \code{x} and latter for \code{y}.} +\item{ticks}{If \code{labels.inside.frame = FALSE}, should ticks can be drawn between the labels and the frame? +Either one value for both \code{x} and \code{y} axis, or a vector two: the first for \code{x} and latter for \code{y}.} \item{lines}{If \code{labels.inside.frame = FALSE}, should grid lines can be drawn?} -\item{ndiscr}{Number of points to discretize a parallel or meridian (only applicable for curved grid lines)} - -\item{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 \code{"tmap401"}, \code{"tmap402"}, etc., except for the base tile layers, which are placed in the standard \code{"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, if \code{zindex} is set to 500, the pane will be named \code{"tmap500"}.} - -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} - -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{ndiscr}{Number of points to discretize a parallel or meridian +(only applicable for curved grid lines)} + +\item{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 \code{"tmap401"}, \code{"tmap402"}, etc., except for the base tile +layers, which are placed in the standard \code{"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, if \code{zindex} is set to 500, +the pane will be named \code{"tmap500"}.} + +\item{group}{Name of the group to which this layer belongs. +This is only relevant in view mode, where layer groups can be +switched (see \code{group.control})} + +\item{group.control}{In view mode, the group control determines how layer groups +can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), +\code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} +for no control (the group cannot be (de)selected).} } \description{ -Creates a \code{\link{tmap-element}} that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. By default, \code{tm_grid()} draws horizontal and vertical lines according to the coordinate system of the (master) shape object. Latitude and longitude graticules are drawn with \code{tm_graticules()}. +Creates a \code{\link{tmap-element}} that draws coordinate grid lines. It serves as a +layer that can be drawn anywhere between other layers. +By default, \code{tm_grid()} draws horizontal and vertical lines according to the +coordinate system of the (master) shape object. Latitude and longitude +graticules are drawn with \code{tm_graticules()}. } \examples{ current.mode <- tmap_mode("plot") diff --git a/man/tm_layout.Rd b/man/tm_layout.Rd index 5ef343c3..e82657d1 100644 --- a/man/tm_layout.Rd +++ b/man/tm_layout.Rd @@ -264,7 +264,7 @@ tm_style(style, ...) tm_format(format, ...) } \arguments{ -\item{modes, crs, facet.max, facet.flip, raster.max.cells, show.messages, show.warnings, output.format, output.size, output.dpi, output.dpi.animation, value.const, value.na, value.null, value.blank, values.var, values.range, value.neutral, scales.var, scale.misc.args, label.format, label.na, scale, asp, bg.color, outer.bg.color, frame, frame.lwd, frame.r, frame.double.line, outer.margins, inner.margins, inner.margins.extra, meta.margins, meta.auto.margins, between.margin, component.offset, component.stack.margin, grid.mark.height, xylab.height, coords.height, xlab.show, xlab.text, xlab.size, xlab.color, xlab.rotation, xlab.space, xlab.fontface, xlab.fontfamily, xlab.side, ylab.show, ylab.text, ylab.size, ylab.color, ylab.rotation, ylab.space, ylab.fontface, ylab.fontfamily, ylab.side, panel.type, panel.wrap.pos, panel.xtab.pos, unit, color.sepia.intensity, color.saturation, color.vision.deficiency.sim, text.fontface, text.fontfamily, legend.show, legend.design, legend.orientation, legend.position, legend.width, legend.height, legend.stack, legend.group.frame, legend.resize.as.group, legend.reverse, legend.na.show, legend.title.color, legend.title.size, legend.title.fontface, legend.title.fontfamily, legend.xlab.color, legend.xlab.size, legend.xlab.fontface, legend.xlab.fontfamily, legend.ylab.color, legend.ylab.size, legend.ylab.fontface, legend.ylab.fontfamily, legend.text.color, legend.text.size, legend.text.fontface, legend.text.fontfamily, legend.frame, legend.frame.lwd, legend.frame.r, legend.bg.color, legend.bg.alpha, legend.settings.standard.portrait, legend.settings.standard.landscape, title.show, title.size, title.color, title.fontface, title.fontfamily, title.bg.color, title.bg.alpha, title.padding, title.frame, title.frame.lwd, title.frame.r, title.stack, title.position, title.group.frame, title.resize.as.group, credits.show, credits.size, credits.color, credits.fontface, credits.fontfamily, credits.bg.color, credits.bg.alpha, credits.padding, credits.frame, credits.frame.lwd, credits.frame.r, credits.stack, credits.position, credits.width, credits.heigth, credits.group.frame, credits.resize.as.group, compass.north, compass.type, compass.text.size, compass.size, compass.show.labels, compass.cardinal.directions, compass.text.color, compass.color.dark, compass.color.light, compass.lwd, compass.bg.color, compass.bg.alpha, compass.margins, compass.show, compass.stack, compass.position, compass.frame, compass.frame.lwd, compass.frame.r, compass.group.frame, compass.resize.as.group, scalebar.show, scalebar.breaks, scalebar.width, scalebar.text.size, scalebar.text.color, scalebar.color.dark, scalebar.color.light, scalebar.lwd, scalebar.position, scalebar.bg.color, scalebar.bg.alpha, scalebar.size, scalebar.margins, scalebar.stack, scalebar.frame, scalebar.frame.lwd, scalebar.frame.r, scalebar.group.frame, scalebar.resize.as.group, grid.show, grid.labels.pos, grid.x, grid.y, grid.n.x, grid.n.y, grid.crs, grid.col, grid.lwd, grid.alpha, grid.labels.show, grid.labels.size, grid.labels.col, grid.labels.rot, grid.labels.format, grid.labels.cardinal, grid.labels.margin.x, grid.labels.margin.y, grid.labels.space.x, grid.labels.space.y, grid.labels.inside.frame, grid.ticks, grid.lines, grid.ndiscr, mouse_coordinates.stack, mouse_coordinates.position, mouse_coordinates.show, 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, qtm.scalebar, qtm.minimap, qtm.mouse.coordinates, earth.boundary, earth.boundary.color, earth.boundary.lwd, earth.datum, space.color, attr.color, max.categories, legend.hist.bg.color, legend.hist.bg.alpha, legend.hist.size, legend.hist.height, legend.hist.width, attr.outside, attr.outside.position, attr.outside.size, attr.position, attr.just, basemap.server, basemap.alpha, basemap.zoom, overlays, overlays.alpha, alpha, colorNA, symbol.size.fixed, dot.size.fixed, text.size.variable, bbox, check.and.fix, set.bounds, set.view, set.zoom.limits, name, basemap.show}{see\code{\link[=tmap_options]{tmap_options()}}} +\item{modes, crs, facet.max, facet.flip, raster.max.cells, show.messages, show.warnings, output.format, output.size, output.dpi, output.dpi.animation, value.const, value.na, value.null, value.blank, values.var, values.range, value.neutral, scales.var, scale.misc.args, label.format, label.na, scale, asp, bg.color, outer.bg.color, frame, frame.lwd, frame.r, frame.double.line, outer.margins, inner.margins, inner.margins.extra, meta.margins, meta.auto.margins, between.margin, component.offset, component.stack.margin, grid.mark.height, xylab.height, coords.height, xlab.show, xlab.text, xlab.size, xlab.color, xlab.rotation, xlab.space, xlab.fontface, xlab.fontfamily, xlab.side, ylab.show, ylab.text, ylab.size, ylab.color, ylab.rotation, ylab.space, ylab.fontface, ylab.fontfamily, ylab.side, panel.type, panel.wrap.pos, panel.xtab.pos, unit, color.sepia.intensity, color.saturation, color.vision.deficiency.sim, text.fontface, text.fontfamily, legend.show, legend.design, legend.orientation, legend.position, legend.width, legend.height, legend.stack, legend.group.frame, legend.resize.as.group, legend.reverse, legend.na.show, legend.title.color, legend.title.size, legend.title.fontface, legend.title.fontfamily, legend.xlab.color, legend.xlab.size, legend.xlab.fontface, legend.xlab.fontfamily, legend.ylab.color, legend.ylab.size, legend.ylab.fontface, legend.ylab.fontfamily, legend.text.color, legend.text.size, legend.text.fontface, legend.text.fontfamily, legend.frame, legend.frame.lwd, legend.frame.r, legend.bg.color, legend.bg.alpha, legend.settings.standard.portrait, legend.settings.standard.landscape, title.show, title.size, title.color, title.fontface, title.fontfamily, title.bg.color, title.bg.alpha, title.padding, title.frame, title.frame.lwd, title.frame.r, title.stack, title.position, title.group.frame, title.resize.as.group, credits.show, credits.size, credits.color, credits.fontface, credits.fontfamily, credits.bg.color, credits.bg.alpha, credits.padding, credits.frame, credits.frame.lwd, credits.frame.r, credits.stack, credits.position, credits.width, credits.heigth, credits.group.frame, credits.resize.as.group, compass.north, compass.type, compass.text.size, compass.size, compass.show.labels, compass.cardinal.directions, compass.text.color, compass.color.dark, compass.color.light, compass.lwd, compass.bg.color, compass.bg.alpha, compass.margins, compass.show, compass.stack, compass.position, compass.frame, compass.frame.lwd, compass.frame.r, compass.group.frame, compass.resize.as.group, scalebar.show, scalebar.breaks, scalebar.width, scalebar.text.size, scalebar.text.color, scalebar.color.dark, scalebar.color.light, scalebar.lwd, scalebar.position, scalebar.bg.color, scalebar.bg.alpha, scalebar.size, scalebar.margins, scalebar.stack, scalebar.frame, scalebar.frame.lwd, scalebar.frame.r, scalebar.group.frame, scalebar.resize.as.group, grid.show, grid.labels.pos, grid.x, grid.y, grid.n.x, grid.n.y, grid.crs, grid.col, grid.lwd, grid.alpha, grid.labels.show, grid.labels.size, grid.labels.col, grid.labels.rot, grid.labels.format, grid.labels.cardinal, grid.labels.margin.x, grid.labels.margin.y, grid.labels.space.x, grid.labels.space.y, grid.labels.inside.frame, grid.ticks, grid.lines, grid.ndiscr, mouse_coordinates.stack, mouse_coordinates.position, mouse_coordinates.show, 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, qtm.scalebar, qtm.minimap, qtm.mouse.coordinates, earth.boundary, earth.boundary.color, earth.boundary.lwd, earth.datum, space.color, attr.color, max.categories, legend.hist.bg.color, legend.hist.bg.alpha, legend.hist.size, legend.hist.height, legend.hist.width, attr.outside, attr.outside.position, attr.outside.size, attr.position, attr.just, basemap.server, basemap.alpha, basemap.zoom, overlays, overlays.alpha, alpha, colorNA, symbol.size.fixed, dot.size.fixed, text.size.variable, bbox, check.and.fix, set.bounds, set.view, set.zoom.limits, name, basemap.show}{See \code{\link[=tmap_options]{tmap_options()}}} \item{title, main.title}{deprecated} diff --git a/man/tm_plot_order.Rd b/man/tm_plot_order.Rd index c43ad831..47b4b134 100644 --- a/man/tm_plot_order.Rd +++ b/man/tm_plot_order.Rd @@ -13,11 +13,25 @@ tm_plot_order( ) } \arguments{ -\item{aes}{Visual variable for which the values determine the plotting order. Example: bubble map where the \code{"size"} aesthetic is used. A data variable (say population) is mapped via a continuous scale (\code{\link[=tm_scale_continuous]{tm_scale_continuous()}}) to bubble sizes. The bubbles are plotted in order of size. How is determined by the other arguments. Use \code{"DATA"} to keep the same order as in the data. Another special value are \code{"AREA"} and \code{"LENGTH"} which are preserved for polygons and lines respectively: rather than a data variable the polygon area / line lengths determines the plotting order.} +\item{aes}{Visual variable for which the values determine the plotting order. +Example: bubble map where the \code{"size"} aesthetic is used. +A data variable (say population) is mapped via a continuous scale (\code{\link[=tm_scale_continuous]{tm_scale_continuous()}}) +to bubble sizes. The bubbles are plotted in order of size. +How is determined by the other arguments. Use \code{"DATA"} to keep the same +order as in the data. Another special value are \code{"AREA"} and \code{"LENGTH"} +which are preserved for polygons and lines respectively: rather than a data +variable the polygon area / line lengths determines the plotting order.} -\item{reverse}{Logical that determines whether the visual values are plotted in reversed order. The visual values (specified with tmap option \code{"values.var"}) are by default reversed, so plotted starting from the last value. In the bubble map example, this means that large bubbles are plotted first, hence at the bottom.} +\item{reverse}{Logical that determines whether the visual values are plotted +in reversed order. The visual values (specified with tmap option \code{"values.var"}) +are by default reversed, so plotted starting from the last value. +In the bubble map example, this means that large bubbles are plotted first, +hence at the bottom.} -\item{na.order}{Where should features be plotted that have an \code{NA} value for (at least) one other aesthetic variable? In the (order) \code{"mix"}, at the \code{"bottom"}, or on \code{"top"}? In the bubble map example: if fill color is missing for some bubble, where should those bubbles be plotted?} +\item{na.order}{Where should features be plotted that have an \code{NA} value for +(at least) one other aesthetic variable? In the (order) \code{"mix"}, at the \code{"bottom"}, +or on \code{"top"}? In the bubble map example: if fill color is missing for some bubble, +where should those bubbles be plotted?} \item{null.order}{Where should non-selected (aka null) features be plotted?} diff --git a/man/tm_polygons.Rd b/man/tm_polygons.Rd index 5dc31ff5..12f47a18 100644 --- a/man/tm_polygons.Rd +++ b/man/tm_polygons.Rd @@ -59,43 +59,83 @@ tm_borders(col = tm_const(), ...) \item{lty, lty.scale, lty.legend, lty.free}{Visual variable that determines the line type. See details.} -\item{fill_alpha, fill_alpha.scale, fill_alpha.legend, fill_alpha.free}{Visual variable that determines the fill color alpha transparency See details.} +\item{fill_alpha, fill_alpha.scale, fill_alpha.legend, fill_alpha.free}{Visual +variable that determines the fill color alpha transparency See details.} -\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable that determines the border color alpha transparency. See details.} +\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable +that determines the border color alpha transparency. See details.} \item{linejoin, lineend}{Line join and line end. See \link[grid:gpar]{gpar()} for details.} -\item{plot.order}{Specification in which order the spatial features are drawn. See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} +\item{plot.order}{Specification in which order the spatial features are drawn. +See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} -\item{trans.args, mapping.args}{lists that are passed on to internal transformation and mapping functions respectively} +\item{trans.args, mapping.args}{lists that are passed on to internal transformation +and mapping functions respectively.} -\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called.} +\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers +(one for each map layer) determines the stacking order. +By default the map layers are drawn in the order they are called.} -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} +\item{group}{Name of the group to which this layer belongs. This is only +relevant in view mode, where layer groups can be switched (see \code{group.control})} -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{group.control}{In view mode, the group control determines how layer groups +can be switched on and off. Options: \code{"radio"} for radio buttons +(meaning only one group can be shown), \code{"check"} for check boxes +(so multiple groups can be shown), and \code{"none"} for no control +(the group cannot be (de)selected).} -\item{popup.vars}{names of data variables that are shown in the popups in \code{"view"} mode. Set popup.vars to \code{TRUE} to show all variables in the shape object. Set popup.vars to \code{FALSE} to disable popups. Set popup.vars to a character vector of variable names to those those variables in the popups. The default (\code{NA}) depends on whether visual variables (e.g.\code{col}) are used. If so, only those are shown. If not all variables in the shape object are shown.} +\item{popup.vars}{names of data variables that are shown in the popups +in \code{"view"} mode. Set popup.vars to \code{TRUE} to show all variables in the +shape object. Set popup.vars to \code{FALSE} to disable popups. Set \code{popup.vars} +to a character vector of variable names to those those variables in the popups. +The default (\code{NA}) depends on whether visual variables (e.g.\code{fill}) are used. +If so, only those are shown. If not all variables in the shape object are shown.} -\item{popup.format}{list of formatting options for the popup values. See the argument \code{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 \code{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.} +\item{popup.format}{list of formatting options for the popup values. +See the argument \code{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 \code{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.} \item{hover}{name of the data variable that specifies the hover labels} -\item{id}{name of the data variable that specifies the indices of the spatial features. Only used for \code{"view"} mode.} +\item{id}{name of the data variable that specifies the indices of the spatial +features. Only used for \code{"view"} mode.} \item{...}{to catch deprecated arguments from version < 4.0} } \description{ -Map layer that draws polygons. Supported visual variables are: \code{fill} (the fill color), \code{col} (the border color), \code{lwd} (line width), \code{lty} (line type), \code{fill_alpha} (fill color alpha transparency) and \code{col_alpha} (border color alpha transparency). +Map layer that draws polygons. Supported visual variables are: \code{fill} (the fill color), +\code{col} (the border color), \code{lwd} (line width), \code{lty} (line type), +\code{fill_alpha} (fill color alpha transparency) and \code{col_alpha} (border color alpha transparency). } \details{ -The visual variable arguments (e.g. \code{col}) can be specified with either a data variable name (e.g., a spatial vector attribute or a raster layer of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value (for \code{col}, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}. - -The \code{.scale} arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available \code{tm_scale_} functions. The default is specified by the tmap option (\code{\link[=tm_options]{tm_options()}}) \code{scales.var}. - -The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. The default legend and its settings are determined by the tmap options (\code{\link[=tm_options]{tm_options()}}) \code{legend.} . - -The \code{.free} arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual variable \code{col}, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension, so the \code{.free} argument requires only one logical value. +The visual variable arguments (e.g. \code{col}) can be specified with either a data +variable name (e.g., a spatial vector attribute or a raster layer of the object +specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value (for \code{col}, a color is expected). +Multiple values can be specified: in that case facets are created. +These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}. + +The \verb{*.scale} arguments determine the used scale to map the data values to +visual variable values. These can be specified with one of the available +\verb{tm_scale_*()} functions. The default is specified by the tmap option (\code{\link[=tm_options]{tm_options()}}) \code{scales.var}. + +The \verb{*.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. +The default legend and its settings are determined by the tmap options (\code{\link[=tm_options]{tm_options()}}) \code{legend.} . + +The \verb{*.free} arguments determine whether scales are applied freely across facets, or shared. +A logical value is required. They can also be specified with a vector of three +logical values; these determine whether scales are applied freely per facet dimension. +This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). +There are maximally three facet dimensions: rows, columns, and pages. This only +applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)} +means that for the visual variable \code{col}, each row of facets will have its own +scale, and therefore its own legend. For facet wraps and stacks +(\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension, +so the \verb{*.free} argument requires only one logical value. } \examples{ # load Africa country data diff --git a/man/tm_pos.Rd b/man/tm_pos.Rd index 4f250a25..7784df40 100644 --- a/man/tm_pos.Rd +++ b/man/tm_pos.Rd @@ -19,16 +19,39 @@ tm_pos_auto_out(cell.h, cell.v, pos.h, pos.v, align.h, align.v, just.h, just.v) tm_pos_auto_in(align.h, align.v, just.h, just.v) } \arguments{ -\item{cell.h, cell.v}{The plotting area is overlaid with a 3x3 grid, of which the middle grid cell is the map area. Components can be drawn into any cell. \code{cell.h} specifies the horizontal position (column) can take values \code{"left"}, \code{"center"}, and \code{"right"}, and \code{cell.v} specifies the vertical position (row) and can take values \code{"top"}, \code{"center"}, and \code{"bottom"}. See details for a graphical explanation.} - -\item{pos.h, pos.v}{The position of the component within the cell. The main options for \code{pos.h} are \code{"left"}, \code{"center"}, and \code{"right"}, and for \code{cell.v} these are \code{"top"}, \code{"center"}, and \code{"bottom"}. These options can also be provided in upper case; in that case there is no offset (see the tmap option \code{component.offset}). Also numbers between 0 and 1 can be provided, which determine the position of the component inside the cell (with (0,0) being left bottom). The arguments \code{just.h} and \code{just.v} determine the justification point.} - -\item{align.h, align.v}{The alignment of the component in case multiple components are stacked. When they are stacked horizontally, \code{align.v} determines how components that are smaller in height than the available height (determined by the outer.margins if specified and otherwise by the highest component) are justified: \code{"top"}, \code{"center"}, or \code{"bottom"}. Similarly, \code{align.h} determines how components are justified horizontally when they are stacked vertically: \code{"left"}, \code{"center"}, or \code{"right"}.} - -\item{just.h, just.v}{The justification of the components. Only used in case \code{pos.h} and \code{pos.v} are numbers.} +\item{cell.h, cell.v}{The plotting area is overlaid with a 3x3 grid, of which +the middle grid cell is the map area. Components can be drawn into any cell. +\code{cell.h} specifies the horizontal position (column) can take values +\code{"left"}, \code{"center"}, and \code{"right"}. \code{cell.v} specifies the vertical position +(row) and can take values \code{"top"}, \code{"center"}, and \code{"bottom"}. +See details for a graphical explanation.} + +\item{pos.h, pos.v}{The position of the component within the cell. +The main options for \code{pos.h} are \code{"left"}, \code{"center"}, and \code{"right"}. +For \code{cell.v} these are \code{"top"}, \code{"center"}, and \code{"bottom"}. +These options can also be provided in upper case; in that case there is no offset +(see the tmap option \code{component.offset}). Also numbers between 0 and 1 can be provided, +which determine the position of the component inside the cell (with (0,0) being left bottom). +The arguments \code{just.h} and \code{just.v} determine the justification point.} + +\item{align.h, align.v}{The alignment of the component in case multiple components are stacked. +When they are stacked horizontally, \code{align.v} determines how components +that are smaller in height than the available height (determined by the outer.margins +if specified and otherwise by the highest component) are justified: +\code{"top"}, \code{"center"}, or \code{"bottom"}. Similarly, \code{align.h} determines how components +are justified horizontally when they are stacked vertically: \code{"left"}, \code{"center"}, or \code{"right"}.} + +\item{just.h, just.v}{The justification of the components. +Only used in case \code{pos.h} and \code{pos.v} are numbers.} } \description{ -Set the position of map components, such as legends, title, compass, scale bar, etc. \code{tm_pos()} is the function to position these components: \code{tm_pos_out()} places the components outside the map area and \code{tm_pos_in()} inside the map area. Each \code{position} argument of a map layer or component should be specified with one of these functions. The functions \code{tm_pos_auto_out()} and \code{tm_pos_auto_in()} are used to set the components automatically, and are recommended to use globally, via \code{\link[=tmap_options]{tmap_options()}}. See Details how the positioning works. +Set the position of map components, such as legends, title, compass, scale bar, etc. +\code{tm_pos()} is the function to position these components: +\code{tm_pos_out()} places the components outside the map area and \code{tm_pos_in()} inside the map area. +Each \code{position} argument of a map layer or component should be specified with +one of these functions. The functions \code{tm_pos_auto_out()} and \code{tm_pos_auto_in()} +are used to set the components automatically, and are recommended to use globally, +via \code{\link[=tmap_options]{tmap_options()}}. See Details how the positioning works. } \details{ \tabular{rllll}{ @@ -53,19 +76,51 @@ Set the position of map components, such as legends, title, compass, scale bar, } -\code{tm_pos_in()} sets the position of the component(s) inside the maps area, which is equivalent to the center-center cell (in case there are facets, these are all drawn in this center-center cell). +\code{tm_pos_in()} sets the position of the component(s) inside the maps area, +which is equivalent to the center-center cell (in case there are facets, +these are all drawn in this center-center cell). \code{tm_pos_out()} sets the position of the component(s) outside the map. -The amount of space that the top and bottom rows, and left and right columns occupy is determined by the \code{\link[=tm_layout]{tm_layout()}} arguments \code{meta.margins} and \code{meta.auto.margins}. The former sets the relative space of the bottom, left, top, and right side. In case these are set to \code{NA}, the space is set automatically based on 1) the maximum relative space specified by \code{meta.auto.margins} and 2) the presence and size of components in each cell. For instance, if there is one landscape oriented legend in the center-bottom cell, then the relative space of the bottom row is set to the height of that legend (given that it is smaller than the corresponding value of \code{meta.auto.margins}), while the other four sides are set to 0. - -\code{tm_pos_auto_out()} is more complex: the \code{cell.h} and \code{cell.v} arguments of should be set to one of the four corners. It does not mean that the components are drawn in a corner. The corner represents the sides of the map that the components are drawn. By default, legends are drawn either at the bottom or on the right-side of the map by default (see \code{tmap_options("legend.position")}). Only when there are row- and column-wise legends and a general legend (using \code{\link[=tm_facets_grid]{tm_facets_grid()}}), the general legend is drawn in the corner, but in practice this case will be rare. - -The arguments \code{pos.h} and \code{pos.v} determine where the components are drawn within the cell. Again, with \code{"left"}, \code{"center"}, and \code{"right"} for \code{pos.h} and \code{"top"}, \code{"center"}, and \code{"bottom"} for \code{pos.v}. The values can also be specified in upper-case, which influences the offset with the cell borders, which is determined by tmap option \code{component.offset}. By default, there is a small offset when components are drawn inside and no offset when they are drawn outside or with upper-case. - -\code{tm_pos_auto_in()} automatically determines \code{pos.h} and \code{pos.v} given the available space inside the map. This is similar to the default positioning in tmap3. - -In case multiple components are draw in the same cell and the same position inside that cell, they are stacked (determined which the \code{stack} argument in the legend or component function). The \code{align.h} and \code{align.v} arguments determine how these components will be justified with each other. - -Note that legends and components may be different for a facet row or column. This is the case when \code{\link[=tm_facets_grid]{tm_facets_grid()}} or \code{\link[=tm_facets_stack]{tm_facets_stack()}} are applied and when scales are set to free (with the \code{.free} argument of the map layer functions). In case a legends or components are draw row- or column wise, and the position of the legends (or components) is right next to the maps, these legends (or components) will be aligned with the maps. +The amount of space that the top and bottom rows, and left and right columns +occupy is determined by the \code{\link[=tm_layout]{tm_layout()}} arguments \code{meta.margins} and \code{meta.auto.margins}. +The former sets the relative space of the bottom, left, top, and right side. +In case these are set to \code{NA}, the space is set automatically based on 1) +the maximum relative space specified by \code{meta.auto.margins} and 2) +the presence and size of components in each cell. +For instance, if there is one landscape oriented legend in the center-bottom cell, +then the relative space of the bottom row is set to the height of that legend +(given that it is smaller than the corresponding value of \code{meta.auto.margins}), +while the other four sides are set to 0. + +\code{tm_pos_auto_out()} is more complex: the \code{cell.h} and \code{cell.v} arguments should be set +to one of the four corners. It does not mean that the components are drawn in a corner. +The corner represents the sides of the map that the components are drawn. +By default, legends are drawn either at the bottom or on the right-side of +the map by default (see \code{tmap_options("legend.position")}). +Only when there are row- and column-wise legends and a general legend (using \code{\link[=tm_facets_grid]{tm_facets_grid()}}), +the general legend is drawn in the corner, but in practice this case will be rare. + +The arguments \code{pos.h} and \code{pos.v} determine where the components are drawn within the cell. +Again, with \code{"left"}, \code{"center"}, and \code{"right"} for \code{pos.h} +and \code{"top"}, \code{"center"}, and \code{"bottom"} for \code{pos.v}. +The values can also be specified in upper-case, which influences the offset +with the cell borders, which is determined by tmap option \code{component.offset}. +By default, there is a small offset when components are drawn inside and no +offset when they are drawn outside or with upper-case. + +\code{tm_pos_auto_in()} automatically determines \code{pos.h} and \code{pos.v} given the +available space inside the map. This is similar to the default positioning in tmap3. + +In case multiple components are draw in the same cell and the same position +inside that cell, they are stacked (determined which the \code{stack} argument in +the legend or component function). The \code{align.h} and \code{align.v} arguments +determine how these components will be justified with each other. + +Note that legends and components may be different for a facet row or column. +This is the case when \code{\link[=tm_facets_grid]{tm_facets_grid()}} or \code{\link[=tm_facets_stack]{tm_facets_stack()}} are applied +and when scales are set to free (with the \code{.free} argument of the map layer functions). +In case a legends or components are draw row- or column wise, and the position +of the legends (or components) is right next to the maps, these legends +(or components) will be aligned with the maps. } diff --git a/man/tm_raster.Rd b/man/tm_raster.Rd index adf39fb3..02aaa0b3 100644 --- a/man/tm_raster.Rd +++ b/man/tm_raster.Rd @@ -21,29 +21,54 @@ tm_raster( ) } \arguments{ -\item{col, col.scale, col.legend, col.free}{Visual variable that determines the color. See details.} +\item{col, col.scale, col.legend, col.free}{Visual variable that determines the color. +See details.} -\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable that determines the alpha transparency. See details.} +\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable +that determines the alpha transparency. See details.} -\item{trans.args, mapping.args}{lists that are passed on to internal transformation and mapping functions respectively} +\item{trans.args, mapping.args}{lists that are passed on to internal transformation +and mapping functions respectively.} -\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called.} +\item{zindex}{Map layers are drawn on top of each other. +The \code{zindex} numbers (one for each map layer) determines the stacking order. +By default the map layers are drawn in the order they are called.} -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} +\item{group}{Name of the group to which this layer belongs. This is only +relevant in view mode, where layer groups can be switched (see \code{group.control})} -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{group.control}{In view mode, the group control determines how layer groups +can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only +one group can be shown), \code{"check"} for check boxes (so multiple groups can be +shown), and \code{"none"} for no control (the group cannot be (de)selected).} } \description{ Map layer that draws rasters. Supported visual variable is: \code{col} (the color). } \details{ -The visual variable arguments (e.g. \code{col}) can be specified with either a data variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value (for \code{col}, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}. - -The \code{.scale} arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available \code{tm_scale_} functions. The default scale that is used is specified by the tmap option \code{scales.var}. - -The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. The default legend and its settings are determined by the tmap options \code{legend.}. - -The \code{.free} arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual variable \code{col}, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension, so the \code{.free} argument requires only one logical value. +The visual variable arguments (e.g. \code{col}) can be specified with either a data +variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value +(for \code{col}, a color is expected). Multiple values can be specified: in that +case facets are created. These facets can be combined with other faceting data +variables, specified with \code{\link[=tm_facets]{tm_facets()}}. +\itemize{ +\item The \code{.scale} arguments determine the used scale to map the data values to +visual variable values. These can be specified with one of the available +\code{tm_scale_()} functions. The default scale that is used is specified by the +tmap option \code{scales.var}. +\item The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. +The default legend and its settings are determined by the tmap options \code{legend.}. +\item The \code{.free} arguments determine whether scales are applied freely across +facets, or shared. A logical value is required. They can also be specified +with a vector of three logical values; these determine whether scales are applied +freely per facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). +There are maximally three facet dimensions: rows, columns, and pages. +This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). +For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual +variable \code{col}, each row of facets will have its own scale, and therefore its +own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}), +there is only one facet dimension, so the \code{.free} argument requires only one logical value. +} } \examples{ # load land data diff --git a/man/tm_rgb.Rd b/man/tm_rgb.Rd index 8f703054..3cca3f45 100644 --- a/man/tm_rgb.Rd +++ b/man/tm_rgb.Rd @@ -12,7 +12,8 @@ tm_rgb( ) } \arguments{ -\item{col, col.scale, col.legend, col.free}{Visual variable that determines the col color.} +\item{col, col.scale, col.legend, col.free}{Visual variable that determines +the col color.} } \description{ Map layer: RGB diff --git a/man/tm_scale.Rd b/man/tm_scale.Rd index 96b8baa6..472ee8b2 100644 --- a/man/tm_scale.Rd +++ b/man/tm_scale.Rd @@ -10,5 +10,10 @@ tm_scale(...) \item{...}{arguments passed on to the applied scale function \verb{tm_scale_*()}} } \description{ -Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. Such function should be used for the input of the \code{.scale} arguments in the layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The function \code{tm_scale()} is a scale that is set automatically given by the data type (factor, numeric, and integer) and the visual variable. The tmap option \code{scales.var} contains information which scale is applied when. +Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. +Such function should be used for the input of the \code{.scale} arguments in the +layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The function \code{tm_scale()} +is a scale that is set automatically given by the data type (factor, numeric, and integer) +and the visual variable. The tmap option \code{scales.var} contains information +which scale is applied when. } diff --git a/man/tm_scale_bivariate.Rd b/man/tm_scale_bivariate.Rd index 18a982f7..db9663af 100644 --- a/man/tm_scale_bivariate.Rd +++ b/man/tm_scale_bivariate.Rd @@ -20,7 +20,7 @@ tm_scale_bivariate( ) } \arguments{ -\item{scale1, scale2}{two \code{tm_scale} objects. Currently, all \code{tm_scale_} functions are supported except \code{tm_scale_continous()}.} +\item{scale1, scale2}{two \code{tm_scale} objects. Currently, all \verb{tm_scale_*()} functions are supported except \code{tm_scale_continous()}.} \item{values}{(generic scale argument) The visual values. For colors (e.g. \code{fill} or \code{col} for \code{tm_polygons()}) this is a palette name from the \code{cols4all} package (see \code{\link[cols4all:c4a]{cols4all::c4a()}}) or vector of colors, for size (e.g. \code{size} for \code{tm_symbols()}) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. \code{shape} for \code{\link[=tm_symbols]{tm_symbols()}}) these are a set of symbols, etc. The tmap option \code{values.var} contains the default values per visual variable and in some cases also per data type.} @@ -43,5 +43,8 @@ tm_scale_bivariate( \item{label.null}{(generic scale argument) Label for null (out-of-scope) values} } \description{ -Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. Such function should be used for the input of the \code{.scale} arguments in the layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The function \code{tm_scale_bivariate()} is used or \code{bivariate.scales}. +Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. +Such function should be used for the input of the \code{.scale} arguments in the +layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). +The function \code{tm_scale_bivariate()} is used for \code{bivariate.scales}. } diff --git a/man/tm_scale_categorical.Rd b/man/tm_scale_categorical.Rd index 6d5a067c..92d06187 100644 --- a/man/tm_scale_categorical.Rd +++ b/man/tm_scale_categorical.Rd @@ -69,5 +69,12 @@ tm_scale_categorical( \item{label.format}{(generic scale argument) Label formatting (similar to \code{legend.format} in tmap3)} } \description{ -Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. Such function should be used for the input of the \code{.scale} arguments in the layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The functions \code{tm_scale_categorical()} and \code{tm_scale_ordinal()} are used for categorical data. The only difference between these functions is that the former assumes unordered categories whereas the latter assumes ordered categories. For colors (the visual variable \code{fill} or \code{col}), different default color palettes are used (see the tmap option \code{values.var}). +Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. +Such function should be used for the input of the \code{.scale} arguments in the +layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). +The functions \code{tm_scale_categorical()} and \code{tm_scale_ordinal()} are used +for categorical data. The only difference between these functions is that the +former assumes unordered categories whereas the latter assumes ordered categories. +For colors (the visual variable \code{fill} or \code{col}), different default color +palettes are used (see the tmap option \code{values.var}). } diff --git a/man/tm_scale_continuous.Rd b/man/tm_scale_continuous.Rd index 1cfa8d8b..692a7d6b 100644 --- a/man/tm_scale_continuous.Rd +++ b/man/tm_scale_continuous.Rd @@ -68,5 +68,9 @@ tm_scale_continuous_log1p(...) \item{...}{passed on to \code{tm_scale_continuous}} } \description{ -Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. Such function should be used for the input of the \code{.scale} arguments in the layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The function \code{tm_scale_continuous} is used for continuous data. The functions \verb{tm_scale_continuous_} use transformation functions x. +Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. +Such function should be used for the input of the \code{.scale} arguments in the layer +functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). +The function \code{tm_scale_continuous()} is used for continuous data. +The functions \verb{tm_scale_continuous_()} use transformation functions x. } diff --git a/man/tm_scale_discrete.Rd b/man/tm_scale_discrete.Rd index 8c0a2ebd..b8107e6b 100644 --- a/man/tm_scale_discrete.Rd +++ b/man/tm_scale_discrete.Rd @@ -48,5 +48,8 @@ tm_scale_discrete( \item{label.format}{(generic scale argument) Label formatting (similar to \code{legend.format} in tmap3)} } \description{ -Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. Such function should be used for the input of the \code{.scale} arguments in the layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The function \code{tm_scale_discrete()} is used for discrete numerical data, such as integers. +Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. +Such function should be used for the input of the \code{.scale} arguments in the +layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). +The function \code{tm_scale_discrete()} is used for discrete numerical data, such as integers. } diff --git a/man/tm_scale_intervals.Rd b/man/tm_scale_intervals.Rd index 629c9136..a9bbd443 100644 --- a/man/tm_scale_intervals.Rd +++ b/man/tm_scale_intervals.Rd @@ -63,5 +63,8 @@ tm_scale_intervals( \item{label.format}{(generic scale argument) Label formatting (similar to legend.format in tmap3)} } \description{ -Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. Such function should be used for the input of the \code{.scale} arguments in the layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The function \code{tm_scale_interval} is used for numerical data. +Scales in tmap are configured by the family of functions with prefix \code{tm_scale}. +Such function should be used for the input of the \code{.scale} arguments in the +layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). +The function \code{tm_scale_interval()} is used for numerical data. } diff --git a/man/tm_scalebar.Rd b/man/tm_scalebar.Rd index 13696c0a..8524c2f3 100644 --- a/man/tm_scalebar.Rd +++ b/man/tm_scalebar.Rd @@ -60,5 +60,7 @@ tm_scalebar( \item{z}{z} } \description{ -Map component that adds a scale bar. As of version 4.0, \code{tm_scalebar()} is used instead of \code{tm_scale_bar} (now deprecated), because of the potential confusion with the \code{tm_scale_x} scaling functions (like \code{\link[=tm_scale_continuous]{tm_scale_continuous()}}). +Map component that adds a scale bar. As of version 4.0, \code{tm_scalebar()} is +used instead of \code{tm_scale_bar()} (now deprecated), because of the potential +confusion with the \verb{tm_scale_*()} scaling functions (like \code{\link[=tm_scale_continuous]{tm_scale_continuous()}}). } diff --git a/man/tm_sf.Rd b/man/tm_sf.Rd index eca52283..02ff3bee 100644 --- a/man/tm_sf.Rd +++ b/man/tm_sf.Rd @@ -53,47 +53,84 @@ tm_sf( ) } \arguments{ -\item{fill, fill.scale, fill.legend, fill.free}{Visual variable that determines the fill color. See details.} +\item{fill, fill.scale, fill.legend, fill.free}{Visual variable that determines +the fill color. See details.} -\item{col, col.scale, col.legend, col.free}{Visual variable that determines the col color. See details.} +\item{col, col.scale, col.legend, col.free}{Visual variable that determines +the col color. See details.} -\item{size, size.scale, size.legend, size.free}{Visual variable that determines the size. See details.} +\item{size, size.scale, size.legend, size.free}{Visual variable that determines +the size. See details.} -\item{shape, shape.scale, shape.legend, shape.free}{Visual variable that determines the shape. See details.} +\item{shape, shape.scale, shape.legend, shape.free}{Visual variable that determines +the shape. See details.} -\item{lwd, lwd.scale, lwd.legend, lwd.free}{Visual variable that determines the line width. See details.} +\item{lwd, lwd.scale, lwd.legend, lwd.free}{Visual variable that determines +the line width. See details.} -\item{lty, lty.scale, lty.legend, lty.free}{Visual variable that determines the line type. See details.} +\item{lty, lty.scale, lty.legend, lty.free}{Visual variable that determines +the line type. See details.} -\item{fill_alpha, fill_alpha.scale, fill_alpha.legend, fill_alpha.free}{Visual variable that determines the fill color alpha transparency See details.} +\item{fill_alpha, fill_alpha.scale, fill_alpha.legend, fill_alpha.free}{Visual +variable that determines the fill color alpha transparency See details.} -\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable that determines the border color alpha transparency. See details.} +\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable +that determines the border color alpha transparency. See details.} \item{linejoin, lineend}{line join and line end. See \link[grid:gpar]{gpar()} for details.} -\item{plot.order.list}{Specification in which order the spatial features are drawn. This consists of a list of three elementary geometry types: for polygons, lines and, points. For each of these types, which are drawn in that order, a \code{\link[=tm_plot_order]{tm_plot_order()}} is required.} +\item{plot.order.list}{Specification in which order the spatial features are drawn. +This consists of a list of three elementary geometry types: for polygons, lines and, points. +For each of these types, which are drawn in that order, a \code{\link[=tm_plot_order]{tm_plot_order()}} is required.} -\item{trans.args.list, mapping.args.list}{lists that are passed on to internal transformation and mapping functions respectively. Each is a list of three items, named \code{polygons}, \code{lines}, and \code{points}. See \code{\link[=tm_polygons]{tm_polygons()}}, \code{\link[=tm_lines]{tm_lines()}}, and \code{\link[=tm_dots]{tm_dots()}}.} +\item{trans.args.list, mapping.args.list}{lists that are passed on to internal +transformation and mapping functions respectively. Each is a list of three +items, named \code{polygons}, \code{lines}, and \code{points}. See \code{\link[=tm_polygons]{tm_polygons()}}, \code{\link[=tm_lines]{tm_lines()}}, and \code{\link[=tm_dots]{tm_dots()}}.} -\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called.} +\item{zindex}{Map layers are drawn on top of each other. +The \code{zindex} numbers (one for each map layer) determines the stacking order. +By default the map layers are drawn in the order they are called.} -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} +\item{group}{Name of the group to which this layer belongs. +This is only relevant in view mode, where layer groups can be switched (see \code{group.control}).} -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{group.control}{In view mode, the group control determines how layer +groups can be switched on and off. Options: \code{"radio"} for radio buttons +(meaning only one group can be shown), \code{"check"} for check boxes +(so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} \item{...}{passed on to \code{\link[=tm_polygons]{tm_polygons()}}, \code{\link[=tm_lines]{tm_lines()}}, and \code{\link[=tm_dots]{tm_dots()}}} } \description{ -Map layer that draws simple features as they are. Supported visual variables are: \code{fill} (the fill color), \code{col} (the border color), \code{size} the point size, \code{shape} the symbol shape, \code{lwd} (line width), \code{lty} (line type), \code{fill_alpha} (fill color alpha transparency) and \code{col_alpha} (border color alpha transparency). +Map layer that draws simple features as they are. Supported visual variables +are: \code{fill} (the fill color), \code{col} (the border color), \code{size} the point size, +\code{shape} the symbol shape, \code{lwd} (line width), \code{lty} (line type), \code{fill_alpha} (fill color alpha transparency) +and \code{col_alpha} (border color alpha transparency). } \details{ -The visual variable arguments (e.g. \code{col}) can be specified with either a data variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value (for \code{col}, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}. - -The \code{.scale} arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available \code{tm_scale_} functions. The default scale that is used is specified by the tmap option \code{scales.var}. - -The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. The default legend and its settings are determined by the tmap options \code{legend.}. - -The \code{.free} arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual variable \code{col}, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension, so the \code{.free} argument requires only one logical value. +The visual variable arguments (e.g. \code{col}) can be specified with either a data +variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value +(for \code{col}, a color is expected). Multiple values can be specified: in that case +facets are created. These facets can be combined with other faceting data variables, +specified with \code{\link[=tm_facets]{tm_facets()}}. + +The \code{.scale} arguments determine the used scale to map the data values to visual +variable values. These can be specified with one of the available \code{tm_scale_()} functions. +The default scale that is used is specified by the tmap option \code{scales.var}. + +The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. +The default legend and its settings are determined by the tmap options \code{legend.}. + +The \code{.free} arguments determine whether scales are applied freely across facets, +or shared. A logical value is required. They can also be specified with a +vector of three logical values; these determine whether scales are applied freely +per facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). +There are maximally three facet dimensions: rows, columns, and pages. This only applies +for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means +that for the visual variable \code{col}, each row of facets will have its own scale, +and therefore its own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and +\code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension, so the \code{.free} argument requires +only one logical value. } \examples{ data(World) diff --git a/man/tm_shape.Rd b/man/tm_shape.Rd index 62ed52cc..b097f015 100644 --- a/man/tm_shape.Rd +++ b/man/tm_shape.Rd @@ -22,7 +22,8 @@ tm_shape( \item{crs}{CRS to which \code{shp} is reprojected (only used if \code{is.main = TRUE})} -\item{is.main}{Is \code{shp} the main shape, which determines the crs and bounding box of the map?} +\item{is.main}{Is \code{shp} the main shape, which determines the crs and +bounding box of the map?} \item{name}{Name of the shape} @@ -33,5 +34,6 @@ tm_shape( \item{...}{to catch deprecated arguments from version < 4.0} } \description{ -Specify a shape, which is a spatial object from one of these spatial object class packages: \code{\link[sf:sf]{sf}}, \code{\link[stars:st_as_stars]{stars}}, \code{terra}. +Specify a shape, which is a spatial object from one of these spatial object +class packages: \code{\link[sf:sf]{sf}}, \code{\link[stars:st_as_stars]{stars}}, or \code{terra}. } diff --git a/man/tm_symbols.Rd b/man/tm_symbols.Rd index 6f35a650..13baa254 100644 --- a/man/tm_symbols.Rd +++ b/man/tm_symbols.Rd @@ -136,41 +136,81 @@ tm_bubbles( \item{lty, lty.scale, lty.legend, lty.free}{Visual variable that determines the line type. See details.} -\item{fill_alpha, fill_alpha.scale, fill_alpha.legend, fill_alpha.free}{Visual variable that determines the fill color alpha transparency See details.} +\item{fill_alpha, fill_alpha.scale, fill_alpha.legend, fill_alpha.free}{Visual variable that determines +the fill color alpha transparency See details.} -\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable that determines the border color alpha transparency. See details.} +\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable that determines +the border color alpha transparency. See details.} -\item{plot.order}{Specification in which order the spatial features are drawn. See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} +\item{plot.order}{Specification in which order the spatial features are drawn. +See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} -\item{trans.args, mapping.args}{lists that are passed on to internal transformation and mapping functions respectively} +\item{trans.args, mapping.args}{lists that are passed on to internal +transformation and mapping functions respectively} -\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called.} +\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers +(one for each map layer) determines the stacking order. By default the map +layers are drawn in the order they are called.} -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} +\item{group}{Name of the group to which this layer belongs. +This is only relevant in view mode, where layer groups can be switched +(see \code{group.control})} -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{group.control}{In view mode, the group control determines how layer +groups can be switched on and off. Options: \code{"radio"} for radio buttons +(meaning only one group can be shown), \code{"check"} for check boxes +(so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} -\item{popup.vars}{names of data variables that are shown in the popups in \code{"view"} mode. Set popup.vars to \code{TRUE} to show all variables in the shape object. Set popup.vars to \code{FALSE} to disable popups. Set popup.vars to a character vector of variable names to those those variables in the popups. The default (\code{NA}) depends on whether visual variables (e.g.\code{col}) are used. If so, only those are shown. If not all variables in the shape object are shown.} +\item{popup.vars}{names of data variables that are shown in the popups in +\code{"view"} mode. Set popup.vars to \code{TRUE} to show all variables in the shape object. +Set popup.vars to \code{FALSE} to disable popups. Set popup.vars to a character vector +of variable names to those those variables in the popups. The default (\code{NA}) +depends on whether visual variables (e.g.\code{col}) are used. If so, only those are shown. +If not all variables in the shape object are shown.} -\item{popup.format}{list of formatting options for the popup values. See the argument \code{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 \code{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.} +\item{popup.format}{list of formatting options for the popup values. +See the argument \code{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 \code{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.} \item{hover}{name of the data variable that specifies the hover labels} -\item{id}{name of the data variable that specifies the indices of the spatial features. Only used for \code{"view"} mode.} +\item{id}{name of the data variable that specifies the indices of the spatial features. +Only used for \code{"view"} mode.} \item{...}{to catch deprecated arguments from version < 4.0} } \description{ -Map layer that draws symbols Supported visual variables are: \code{fill} (the fill color), \code{col} (the border color), \code{size} the symbol size, \code{shape} the symbol shape, \code{lwd} (line width), \code{lty} (line type), \code{fill_alpha} (fill color alpha transparency) and \code{col_alpha} (border color alpha transparency). +Map layer that draws symbols Supported visual variables are: +\code{fill} (the fill color), \code{col} (the border color), \code{size} the symbol size, +\code{shape} the symbol shape, \code{lwd} (line width), \code{lty} (line type), \code{fill_alpha} +(fill color alpha transparency) and \code{col_alpha} (border color alpha transparency). } \details{ -The visual variable arguments (e.g. \code{col}) can be specified with either a data variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value (for \code{col}, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}. - -The \code{.scale} arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available \code{tm_scale_} functions. The default scale that is used is specified by the tmap option \code{scales.var}. - -The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. The default legend and its settings are determined by the tmap options \code{legend.}. - -The \code{.free} arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual variable \code{col}, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension, so the \code{.free} argument requires only one logical value. +The visual variable arguments (e.g. \code{col}) can be specified with either a data +variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value +(for \code{col}, a color is expected). Multiple values can be specified: in that case +facets are created. These facets can be combined with other faceting data variables, +specified with \code{\link[=tm_facets]{tm_facets()}}. + +The \code{.scale} arguments determine the used scale to map the data values to visual +variable values. These can be specified with one of the available \code{tm_scale_} functions. +The default scale that is used is specified by the tmap option \code{scales.var}. + +The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. +The default legend and its settings are determined by the tmap options \code{legend.}. + +The \code{.free} arguments determine whether scales are applied freely across facets, +or shared. A logical value is required. They can also be specified with a vector +of three logical values; these determine whether scales are applied freely per +facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). +There are maximally three facet dimensions: rows, columns, and pages. +This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). +For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual variable +\code{col}, each row of facets will have its own scale, and therefore its own legend. +For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}), +there is only one facet dimension, so the \code{.free} argument requires only one logical value. } \examples{ # load Africa country data diff --git a/man/tm_text.Rd b/man/tm_text.Rd index 407fd789..8f5143f4 100644 --- a/man/tm_text.Rd +++ b/man/tm_text.Rd @@ -37,43 +37,74 @@ tm_text( ) } \arguments{ -\item{text, text.scale, text.legend, text.free}{Visual variable that determines the text. See details.} +\item{text, text.scale, text.legend, text.free}{Visual variable that determines +the text. See details.} -\item{size, size.scale, size.legend, size.free}{Visual variable that determines the font size. See details.} +\item{size, size.scale, size.legend, size.free}{Visual variable that determines +the font size. See details.} -\item{col, col.scale, col.legend, col.free}{Visual variable that determines the col color. See details.} +\item{col, col.scale, col.legend, col.free}{Visual variable that determines +the col color. See details.} -\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable that determines the border color alpha transparency. See Details.} +\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.free}{Visual variable that determines +the border color alpha transparency. See Details.} -\item{fontface, fontface.scale, fontface.legend, fontface.free}{Visual variable that determines the font face. See Details.} +\item{fontface, fontface.scale, fontface.legend, fontface.free}{Visual variable that determines +the font face. See Details.} \item{fontfamily}{The font family. See \link[grid:gpar]{gpar()} for details.} \item{shadow}{Shadow behind the text. Logical or color.} -\item{plot.order}{Specification in which order the spatial features are drawn. See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} +\item{plot.order}{Specification in which order the spatial features are drawn. +See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.} -\item{trans.args, mapping.args}{lists that are passed on to internal transformation and mapping functions respectively} +\item{trans.args, mapping.args}{lists that are passed on to internal transformation +and mapping functions respectively.} -\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called.} +\item{zindex}{Map layers are drawn on top of each other. The \code{zindex} numbers +(one for each map layer) determines the stacking order. +By default the map layers are drawn in the order they are called.} -\item{group}{Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see \code{group.control})} +\item{group}{Name of the group to which this layer belongs. This is only +relevant in view mode, where layer groups can be switched (see \code{group.control})} -\item{group.control}{In view mode, the group control determines how layer groups can be switched on and off. Options: \code{"radio"} for radio buttons (meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), and \code{"none"} for no control (the group cannot be (de)selected).} +\item{group.control}{In view mode, the group control determines how layer +groups can be switched on and off. Options: \code{"radio"} for radio buttons +(meaning only one group can be shown), \code{"check"} for check boxes (so multiple groups can be shown), +and \code{"none"} for no control (the group cannot be (de)selected).} \item{...}{to catch deprecated arguments from version < 4.0} } \description{ -Map layer that draws symbols Supported visual variables are: \code{text} (the text itself) \code{col} (color), \code{size} (font size), and \code{fontface} (font face). +Map layer that draws symbols Supported visual variables are: \code{text} +(the text itself) \code{col} (color), \code{size} (font size), and \code{fontface} (font face). } \details{ -The visual variable arguments (e.g. \code{col}) can be specified with either a data variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual value (for \code{col}, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}. - -The \code{.scale} arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available \code{tm_scale_} functions. The default scale that is used is specified by the tmap option \code{scales.var}. - -The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. The default legend and its settings are determined by the tmap options \code{legend.}. - -The \code{.free} arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual variable \code{col}, each row of facets will has its own scale, and therefore its own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension, so the \code{.free} argument requires only one logical value. +The visual variable arguments (e.g. \code{col}) can be specified with either a +data variable name (of the object specified in \code{\link[=tm_shape]{tm_shape()}}), or with a visual +value (for \code{col}, a color is expected). Multiple values can be specified: +in that case facets are created. These facets can be combined with other +faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}. + +The \code{.scale} arguments determine the used scale to map the data values to +visual variable values. These can be specified with one of the available +\code{tm_scale_()} functions. The default scale that is used is specified by the +tmap option \code{scales.var}. + +The \code{.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}. +The default legend and its settings are determined by the tmap options \code{legend.}. + +The \code{.free} arguments determine whether scales are applied freely across facets, +or shared. A logical value is required. They can also be specified with a +vector of three logical values; these determine whether scales are applied +freely per facet dimension. This is only useful when facets are applied +(see \code{\link[=tm_facets]{tm_facets()}}). There are maximally three facet dimensions: rows, columns, +and pages. This only applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). +For instance, \code{col.free = c(TRUE, FALSE, FALSE)} means that for the visual +variable \code{col}, each row of facets will has its own scale, and therefore its +own legend. For facet wraps and stacks (\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) +there is only one facet dimension, so the \code{.free} argument requires only one logical value. } \examples{ data(rivers) diff --git a/man/tm_view.Rd b/man/tm_view.Rd index 4a574edc..14a9e358 100644 --- a/man/tm_view.Rd +++ b/man/tm_view.Rd @@ -24,13 +24,20 @@ tm_view( \item{control.overlays}{overlay layers} -\item{set.bounds}{logical that determines whether maximum bounds are set, or a bounding box. Not applicable in plot mode. In view mode, this is passed on to \link[leaflet:map-methods]{setMaxBounds()}} +\item{set.bounds}{logical that determines whether maximum bounds are set, +or a bounding box. Not applicable in plot mode. +In view mode, this is passed on to \link[leaflet:map-methods]{setMaxBounds()}} -\item{set.view}{numeric vector that determines the view. Either a vector of three: \code{lng}, \code{lat}, and \code{zoom}, or a single value: \code{zoom}. See \link[leaflet:map-methods]{setView()}. Only applicable if \code{bbox} is not specified} +\item{set.view}{numeric vector that determines the view. +Either a vector of three: \code{lng}, \code{lat}, and \code{zoom}, or a single value: +\code{zoom}. See \link[leaflet:map-methods]{setView()}. +Only applicable if \code{bbox} is not specified} -\item{set.zoom.limits}{numeric vector of two that set the minimum and maximum zoom levels (see \link[leaflet:map-options]{tileOptions()}).} +\item{set.zoom.limits}{numeric vector of two that set the minimum and maximum +zoom levels (see \link[leaflet:map-options]{tileOptions()}).} -\item{leaflet.options}{options passed on to \link[leaflet:leaflet]{leafletOptions()}} +\item{leaflet.options}{options passed on to +\link[leaflet:leaflet]{leafletOptions()}} } \description{ View mode options. These options are specific to the view mode. diff --git a/man/tmap-package.Rd b/man/tmap-package.Rd index c2bfc884..3577e19a 100644 --- a/man/tmap-package.Rd +++ b/man/tmap-package.Rd @@ -6,10 +6,14 @@ \alias{tmap-package} \title{Thematic Map Visualization} \description{ -Thematic maps are geographical maps in which spatial data distributions are visualized. This package offers a flexible, layer-based, and easy to use approach to create thematic maps, such as choropleths and bubble maps. It is based on the grammar of graphics, and resembles the syntax of ggplot2. +Thematic maps are geographical maps in which spatial data distributions are visualized. +This package offers a flexible, layer-based, and easy to use approach to create +thematic maps, such as choropleths and bubble maps. It is based on the grammar +of graphics, and resembles the syntax of ggplot2. } \details{ -This page provides a brief overview of all package functions. See \code{vignette("tmap_sneak_peek")} for a short introduction with examples. +This page provides a brief overview of all package functions. +See \code{vignette("tmap_sneak_peek")} for a short introduction with examples. } \section{Quick plotting method}{ diff --git a/man/tmapAddLayerOptions.Rd b/man/tmapAddLayerOptions.Rd index 7df3518b..b4006197 100644 --- a/man/tmapAddLayerOptions.Rd +++ b/man/tmapAddLayerOptions.Rd @@ -9,7 +9,9 @@ tmapAddLayerOptions(option, id, value) \arguments{ \item{option, }{one of: \code{"value.const"}, \code{"value.na"}, \code{"value.blank"}, \code{"values.var"}, \code{'values.range'}, \code{"value.neutral"}, \code{"scales.var"}} -\item{id}{name of the visual variable with layer, in the format \code{"x.y"}, where \code{x} is the visual variable and \code{y} is the layer. It is also possible to set \code{x} only; then it applies to all layer functions.} +\item{id}{name of the visual variable with layer, in the format \code{"x.y"}, +where \code{x} is the visual variable and \code{y} is the layer. +It is also possible to set \code{x} only; then it applies to all layer functions.} \item{value}{value} } diff --git a/man/tmapSplitShp.Rd b/man/tmapSplitShp.Rd index e7cc0434..48f3540d 100644 --- a/man/tmapSplitShp.Rd +++ b/man/tmapSplitShp.Rd @@ -12,6 +12,7 @@ tmapSplitShp(shp, split_stars_dim) \item{split_stars_dim}{name of the dimension to split (\code{""} to skip)} } \description{ -Internal method that split shape objects. So far, only used to split stars object (from dimension to attributes) +Internal method that split shape objects. So far, only used to split stars object +(from dimension to attributes) } \keyword{internal} diff --git a/man/tmap_animation.Rd b/man/tmap_animation.Rd index 6947d605..a607d1ec 100644 --- a/man/tmap_animation.Rd +++ b/man/tmap_animation.Rd @@ -21,27 +21,44 @@ tmap_animation( ) } \arguments{ -\item{tm}{tmap or a list of tmap objects. If \code{tm} is a tmap object, facets should be created, where nrow and ncol in \code{\link[=tm_facets]{tm_facets()}} have to be set to 1 in order to create one map per frame.} +\item{tm}{tmap or a list of tmap objects. If \code{tm} is a tmap object, +facets should be created, where \code{nrow} and \code{ncol} in \code{\link[=tm_facets]{tm_facets()}} have to +be set to 1 in order to create one map per frame.} -\item{filename}{filename. If omitted (default), the animation will be shown in the viewer or browser. If specified, it should be a gif file or a video file (i.e. mp4). The package \code{gifski} is required to create a gif animation. The package \code{av} (which uses the \code{FFmpeg} library) is required for video formats. The mp4 format is recommended but many other video formats are supported, such as wmv, avi, and mkv.} +\item{filename}{filename. If omitted (default), the animation will be shown +in the viewer or browser. If specified, it should be a gif file or a video +file (i.e. mp4). The package \code{gifski} is required to create a gif animation. +The package \code{av} (which uses the \code{FFmpeg} library) is required for video formats. +The mp4 format is recommended but many other video formats are supported, +such as wmv, avi, and mkv.} -\item{width, height}{width and height of the animation file (in pixels). Required when \code{tm} is a list, and recommended to specify in advance when \code{tm} is a \code{tmap} object. If not specified in the latter case, it will be determined by the aspect ratio of the map.} +\item{width, height}{Dimensions of the animation file (in pixels). +Required when \code{tm} is a list, and recommended to specify in advance when +\code{tm} is a \code{tmap} object. If not specified in the latter case, it will be +determined by the aspect ratio of the map.} -\item{dpi}{dots per inch. By default 100, but this can be set with the option \code{output.dpi.animation} in \code{\link[=tmap_options]{tmap_options()}}.} +\item{dpi}{dots per inch. By default 100, but this can be set with the option +\code{output.dpi.animation} in \code{\link[=tmap_options]{tmap_options()}}.} \item{delay}{delay time between images (in 1/100th of a second). See also \code{fps}} -\item{fps}{frames per second, calculated as \code{100 / delay}. If \code{fps} is specified, the \code{delay} will be set to \code{100/fps}.} +\item{fps}{frames per second, calculated as \code{100 / delay}. If \code{fps} is specified, +the \code{delay} will be set to \code{100/fps}.} -\item{loop}{logical that determined whether the animation is looped, or an integer value that determines how many times the animation is looped.} +\item{loop}{logical that determined whether the animation is looped, or an +integer value that determines how many times the animation is looped.} -\item{outer.margins}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) overrides the outer.margins argument of \code{\link[=tm_layout]{tm_layout()}} (unless set to \code{NA})} +\item{outer.margins}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) overrides the outer.margins +argument of \code{tm_layout()} (unless set to \code{NA})} -\item{asp}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) if specified, it overrides the asp argument of \code{\link[=tm_layout]{tm_layout()}}. Tip: set to \code{0} if map frame should be placed on the edges of the image.} +\item{asp}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) if specified, it overrides the \code{asp} +argument of \code{tm_layout()}. Tip: set to \code{0} if map frame should be placed on +the edges of the image.} -\item{scale}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) overrides the scale argument of \code{\link[=tm_layout]{tm_layout()}} (unless set to \code{NA})} +\item{scale}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) overrides the scale argument of +\code{\link[=tm_layout]{tm_layout()}} (unless set to \code{NA})} -\item{restart.delay}{not used anymore} +\item{restart.delay}{not used anymore.} \item{...}{arguments passed on to \code{\link[av:encoding]{av::av_encode_video()}}} } diff --git a/man/tmap_arrange.Rd b/man/tmap_arrange.Rd index 473ce0b3..b68c3c01 100644 --- a/man/tmap_arrange.Rd +++ b/man/tmap_arrange.Rd @@ -22,33 +22,49 @@ knit_print.tmap_arrange(x, ..., options = NULL) \method{print}{tmap_arrange}(x, knit = FALSE, ..., options = NULL) } \arguments{ -\item{...}{\code{\link{tmap}} objects or one list of \code{\link{tmap}} objects. The number of multiples that can be plot is limited (see details).} +\item{...}{\code{\link{tmap}} objects or one list of \code{\link{tmap}} objects. +The number of multiples that can be plot is limited (see details).} \item{ncol}{number of columns} \item{nrow}{number of rows} -\item{widths}{vector of column widths. It should add up to 1 and the length should be equal to \code{ncol}} +\item{widths}{vector of column widths. It should add up to 1 and the length +should be equal to \code{ncol}.} -\item{heights}{vector of row heights. It should add up to 1 and the length should be equal to \code{nrow}} +\item{heights}{vector of row heights. It should add up to 1 and the length +should be equal to \code{nrow}.} -\item{sync}{logical. Should the navigation in view mode (zooming and panning) be synchronized? By default \code{FALSE}.} +\item{sync}{logical. Should the navigation in view mode (zooming and panning) +be synchronized? By default \code{FALSE}.} -\item{asp}{aspect ratio. The aspect ratio of each map. Normally, this is controlled by the \code{asp} argument from \code{\link[=tm_layout]{tm_layout()}} (also a tmap option). This argument will overwrite it, unless set to \code{NULL}. The default value for \code{asp} is 0, which means that the aspect ratio is adjusted to the size of the device divided by the number of columns and rows. When \code{asp} is set to \code{NA}, which is also the default value for \code{\link[=tm_layout]{tm_layout()}}, the aspect ratio will be adjusted to the used shapes.} +\item{asp}{aspect ratio. The aspect ratio of each map. Normally, this is +controlled by the \code{asp} argument from \code{\link[=tm_layout]{tm_layout()}} (also a tmap option). +This argument will overwrite it, unless set to \code{NULL}. +The default value for \code{asp} is 0, which means that the aspect ratio is +adjusted to the size of the device divided by the number of columns and rows. +When \code{asp} is set to \code{NA}, which is also the default value for \code{tm_layout()}, +the aspect ratio will be adjusted to the used shapes.} -\item{outer.margins}{outer.margins, numeric vector four or a single value. If defines the outer margins for each multiple. If will overwrite the \code{outer.margins} argument from \code{\link[=tm_layout]{tm_layout()}}, unless set to \code{NULL}.} +\item{outer.margins}{outer.margins, numeric vector four or a single value. +If defines the outer margins for each multiple. If will overwrite the +\code{outer.margins} argument from \code{\link[=tm_layout]{tm_layout()}}, unless set to \code{NULL}.} -\item{x}{a \code{tmap_arrange} object (returned from \code{tmap_arrange()})} +\item{x}{a \code{tmap_arrange} object (returned from \code{tmap_arrange()}).} \item{options}{options passed on to \code{\link[knitr:knit_print]{knitr::knit_print()}}} \item{knit}{should \code{\link[knitr:knit_print]{knitr::knit_print()}} be enabled, or the normal \code{\link[base:print]{base::print()}} function?} } \description{ -Arrange small multiples in a grid layout. Normally, small multiples are created by specifying multiple variables for one aesthetic or by specifying the by argument (see \code{\link[=tm_facets]{tm_facets()}}). This function can be used to arrange custom small multiples in a grid layout. +Arrange small multiples in a grid layout. Normally, small multiples are created +by specifying multiple variables for one aesthetic or by specifying the by argument +(see \code{\link[=tm_facets]{tm_facets()}}). This function can be used to arrange custom small multiples in a grid layout. } \details{ -The global option \code{tmap.limits} controls the limit of the number of facets that are plotted. By default, \code{tmap_options(tmap.limits = c(facets.view=4, facets.plot=64))}. The maximum number of interactive facets is set to four since otherwise it may become very slow. +The global option \code{tmap.limits} controls the limit of the number of facets that are plotted. +By default, \code{tmap_options(tmap.limits = c(facets.view=4, facets.plot=64))}. +The maximum number of interactive facets is set to four since otherwise it may become very slow. } \examples{ tm1 = tm_shape(World) + tm_polygons("HPI") diff --git a/man/tmap_design_mode.Rd b/man/tmap_design_mode.Rd index 34d9cdea..ec46692a 100644 --- a/man/tmap_design_mode.Rd +++ b/man/tmap_design_mode.Rd @@ -7,10 +7,15 @@ tmap_design_mode(design.mode) } \arguments{ -\item{design.mode}{Logical value that determines the design mode. If omitted then the design mode is toggled.} +\item{design.mode}{Logical value that determines the design mode. +If omitted then the design mode is toggled.} } \description{ -When the so-called "design mode" is enabled, inner and outer margins, legend position, and aspect ratio are shown explicitly in plot mode. Also, information about aspect ratios is printed in the console. This function sets the global option \code{tmap.design.mode}. It can be used as toggle function without arguments. +When the so-called "design mode" is enabled, inner and outer margins, +legend position, and aspect ratio are shown explicitly in plot mode. +Also, information about aspect ratios is printed in the console. +This function sets the global option \code{tmap.design.mode}. +It can be used as toggle function without arguments. } \seealso{ \code{\link[=tmap_options]{tmap_options()}} diff --git a/man/tmap_devel_mode.Rd b/man/tmap_devel_mode.Rd index 7863ee8f..11f0c5b4 100644 --- a/man/tmap_devel_mode.Rd +++ b/man/tmap_devel_mode.Rd @@ -7,8 +7,10 @@ tmap_devel_mode(devel.mode) } \arguments{ -\item{devel.mode}{logical value that determines the development mode. If omitted then the development mode is toggled.} +\item{devel.mode}{logical value that determines the development mode. +If omitted then the development mode is toggled.} } \description{ -When the so-called "development mode" is enabled, helpful messages and timings are printed in the console +When the so-called "development mode" is enabled, helpful messages and timings +are printed in the console } diff --git a/man/tmap_format.Rd b/man/tmap_format.Rd index caed6731..51891c43 100644 --- a/man/tmap_format.Rd +++ b/man/tmap_format.Rd @@ -17,10 +17,14 @@ tmap_format_add(..., name) \item{name}{Name of the new format.} } \value{ -The function \code{tmap_format()} returns the names of the available formats. When \code{format} is defined, it returns the option list corresponding the that format. +The function \code{tmap_format()} returns the names of the available formats. +When \code{format} is defined, it returns the option list corresponding the that format. } \description{ -Format options are tmap options that are shape dependent. With \code{tmap_format()} the predefined formats can be retrieved. The values for a specific format can be retrieved with \code{tmap_format(format)}, where format is the name of the format. The function \code{tmap_format_add()} is used to add a format. +Format options are tmap options that are shape dependent. +With \code{tmap_format()} the predefined formats can be retrieved. +The values for a specific format can be retrieved with \code{tmap_format(format)}, +where format is the name of the format. The function \code{tmap_format_add()} is used to add a format. } \examples{ # available formats @@ -41,7 +45,9 @@ data(World) #qtm(World, fill="HPI", format="World_small") } \seealso{ -\code{\link[=tm_layout]{tm_layout()}} for predefined styles, \code{tmap_style_catalogue} (not migrated to v4 yet) to create a style catalogue of all available styles, and \code{\link[=tmap_options]{tmap_options()}} for tmap options. - -\code{\link[=tmap_options]{tmap_options()}} for tmap options +\itemize{ +\item \code{\link[=tm_layout]{tm_layout()}} for predefined styles +\item \code{tmap_style_catalogue} (not migrated to v4 yet) to create a style catalogue of all available styles +\item \code{\link[=tmap_options]{tmap_options()}} for tmap options +} } diff --git a/man/tmap_icons.Rd b/man/tmap_icons.Rd index 140682c0..3a6f72bf 100644 --- a/man/tmap_icons.Rd +++ b/man/tmap_icons.Rd @@ -24,19 +24,27 @@ marker_icon() \item{height}{height of the icon. If \code{keep.asp}, this is interpreted as the maximum height.} -\item{keep.asp}{keep the aspect ratio of the png image. If \code{TRUE} and the aspect ratio differs from \code{width/height} either \code{width} or \code{height} is adjusted accordingly.} +\item{keep.asp}{keep the aspect ratio of the png image. If \code{TRUE} and the aspect +ratio differs from \code{width/height}, either \code{width} or \code{height} is adjusted accordingly.} -\item{just}{justification of the icons relative to the point coordinates. The first value specifies horizontal and the second value vertical justification. Possible values are: \code{"left"} , \code{"right"}, \code{"center"}, \code{"bottom"}, and \code{"top"}. Numeric values of 0 specify left alignment and 1 right alignment. The default value of \code{just} is \code{c("center", "center")}.} +\item{just}{justification of the icons relative to the point coordinates. +The first value specifies horizontal and the second value vertical justification. +Possible values are: \code{"left"} , \code{"right"}, \code{"center"}, \code{"bottom"}, and \code{"top"}. +Numeric values of 0 specify left alignment and 1 right alignment. +The default value of \code{just} is \code{c("center", "center")}.} \item{as.local}{if the \code{file} is a url, should it be saved to local temporary file?} -\item{...}{arguments passed on to \code{\link[leaflet:icons]{leaflet::icons()}}. When \code{iconWidth}, \code{iconHeight}, \code{iconAnchorX} and \code{iconAnchorY} are specified, they override \code{width} and \code{height}, and \code{just}.} +\item{...}{arguments passed on to \code{\link[leaflet:icons]{leaflet::icons()}}. +When \code{iconWidth}, \code{iconHeight}, \code{iconAnchorX}, and \code{iconAnchorY} are specified, +they override \code{width} and \code{height}, and \code{just}.} } \value{ icon data (see \code{\link[leaflet:icons]{leaflet::icons()}}) } \description{ -Specifies icons from a png images, which can be used as markers in thematic maps. The function \code{marker_icon()} is the specification of the default marker. +Specifies icons from a png images, which can be used as markers in thematic maps. +The function \code{marker_icon()} is the specification of the default marker. } \seealso{ \code{\link[=tm_symbols]{tm_symbols()}} diff --git a/man/tmap_last.Rd b/man/tmap_last.Rd index 177f0a9c..54eb180c 100644 --- a/man/tmap_last.Rd +++ b/man/tmap_last.Rd @@ -10,7 +10,9 @@ tmap_last() call } \description{ -Retrieve the last map to be modified or created. Works in the same way as \code{\link[ggplot2:last_plot]{ggplot2::last_plot()}}, although there is a difference: \code{tmap_last()} returns the last call instead of the stacked \code{\link{tmap-element}}s. +Retrieve the last map to be modified or created. Works in the same way +as \code{\link[ggplot2:last_plot]{ggplot2::last_plot()}}, although there is a difference: +\code{tmap_last()} returns the last call instead of the stacked \code{\link{tmap-element}}s. } \seealso{ \code{\link[=tmap_save]{tmap_save()}} diff --git a/man/tmap_leaflet.Rd b/man/tmap_leaflet.Rd index 7088b510..2f92b33f 100644 --- a/man/tmap_leaflet.Rd +++ b/man/tmap_leaflet.Rd @@ -24,7 +24,8 @@ tmap_grid(x, show = FALSE, ...) \value{ \itemize{ \item \code{tmap_grid()} returns a \code{\link[grid:grid.grob]{grob}} object (\code{"plot"} mode) -\item \code{tmap_leaflet()} a \code{\link[leaflet:leaflet]{leaflet}} object (\code{"view"} mode). In case small multiples are shown, a list is returned. +\item \code{tmap_leaflet()} a \code{\link[leaflet:leaflet]{leaflet}} object (\code{"view"} mode). +In case small multiples are shown, a list is returned. } } \description{ diff --git a/man/tmap_mode.Rd b/man/tmap_mode.Rd index 6583f478..29d3352f 100644 --- a/man/tmap_mode.Rd +++ b/man/tmap_mode.Rd @@ -13,25 +13,51 @@ ttm() ttmp() } \arguments{ -\item{mode}{One of: -\describe{ -\item{\code{"plot"}}{Thematic maps are shown in the graphics device. This is the default mode, and supports all tmap's features, such as small multiples (see \code{\link[=tm_facets]{tm_facets()}}) and extensive layout settings (see \code{\link[=tm_layout]{tm_layout()}}). It is recommended for saving static maps (see \code{\link[=tmap_save]{tmap_save()}}).} -\item{\code{"view"}}{Thematic maps are viewed interactively in the web browser or RStudio's Viewer pane. Maps are fully interactive with tiles from OpenStreetMap or other map providers (see \code{\link[=tm_tiles]{tm_tiles()}}). See also \code{\link[=tm_view]{tm_view()}} for options related to the \code{"view"} mode. This mode generates a \code{\link[leaflet:leaflet]{leaflet::leaflet()}} widget, which can also be directly obtained with \code{\link[=tmap_leaflet]{tmap_leaflet()}}. With R Markdown, it is possible to publish it to an HTML page. -There are a couple of constraints in comparison to \code{"plot"}: +\item{mode}{One of \code{"plot"} or \code{"view"}. See Details for more info.} +} +\value{ +The previous tmap mode before switching. +} +\description{ +Set tmap mode to static plotting or interactive viewing. +The global option \code{tmap.mode} determines the whether thematic maps are plot +in the graphics device, or shown as an interactive leaflet map (see also \code{\link[=tmap_options]{tmap_options()}}. +The function \code{tmap_mode()} is a wrapper to set this global option. +The convenient function \code{ttm()}, which stands for toggle thematic map, +is a toggle switch between the two modes. The function \code{ttmp()} stands for +toggle thematic map and print last map: it does the same as \code{ttm()} followed +by \code{\link[=tmap_last]{tmap_last()}}; in order words, it shows the last map in the other mode. +It is recommended to use \code{tmap_mode()} in scripts and \code{ttm()}/\code{ttmp()} in the console. +} +\section{mode = "plot"}{ +Thematic maps are shown in the graphics device. +This is the default mode, and supports all tmap's features, +such as small multiples (see \code{\link[=tm_facets]{tm_facets()}}) and extensive layout settings (see \code{\link[=tm_layout]{tm_layout()}}). +It is recommended to use \code{\link[=tmap_save]{tmap_save()}} for saving static maps. +} + +\section{mode = "view"}{ +Thematic maps are viewed interactively in the web browser or RStudio's Viewer pane. +Maps are fully interactive with tiles from OpenStreetMap or other map providers +(see \code{\link[=tm_tiles]{tm_tiles()}}). See also \code{\link[=tm_view]{tm_view()}} for options related to the \code{"view"} mode. +This mode generates a \code{\link[leaflet:leaflet]{leaflet::leaflet()}} widget, which can also be directly +obtained with \code{\link[=tmap_leaflet]{tmap_leaflet()}}. +With R Markdown, it is possible to publish it to an HTML page. + +However, there are a couple of constraints in comparison to \code{"plot"}: \itemize{ -\item The map is always projected according to the Web Mercator projection. Although this projection is the de facto standard for interactive web-based mapping, it lacks the equal-area property, which is important for many thematic maps, especially choropleths (see examples from \code{\link[=tm_shape]{tm_shape()}}). +\item The map is always projected according to the Web Mercator projection. +Although this projection is the de facto standard for interactive web-based mapping, +it lacks the equal-area property, which is important for many thematic maps, +especially choropleths (see examples from \code{\link[=tm_shape]{tm_shape()}}). \item Small multiples are not supported \item The legend cannot be made for aesthetics regarding size, which are symbol size and line width. \item Text labels are not supported (yet) -\item The layout options set with \code{\link[=tm_layout]{tm_layout()}}) regarding map format are not used. However, the styling options still apply.} -}}} -} -\value{ -The mode before changing +\item The layout options set with \code{\link[=tm_layout]{tm_layout()}}) regarding map format are not used. +However, the styling options still apply. } -\description{ -Set tmap mode to static plotting or interactive viewing. The global option \code{tmap.mode} determines the whether thematic maps are plot in the graphics device, or shown as an interactive leaflet map (see also \code{\link[=tmap_options]{tmap_options()}}. The function \code{tmap_mode} is a wrapper to set this global option. The convenient function \code{ttm}, which stands for toggle thematic map, is a toggle switch between the two modes. The function \code{ttmp} stands for toggle thematic map and print last map: it does the same as \code{ttm} followed by \code{\link[=tmap_last]{tmap_last()}}; in order words, it shows the last map in the other mode. It is recommended to use \code{tmap_mode()} in scripts and \code{ttm}/\code{ttmp} in the console. } + \examples{ tmap_mode() @@ -48,8 +74,15 @@ ttm() tm_shape(World) + tm_polygons("HPI") } \references{ -Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} +Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, +Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} } \seealso{ -\code{vignette("tmap_sneak_peek")}, \code{\link[=tmap_last]{tmap_last()}} to show the last map, \code{\link[=tm_view]{tm_view()}} for viewing options, and \code{\link[=tmap_leaflet]{tmap_leaflet()}} for obtaining a leaflet widget, and \code{\link[=tmap_options]{tmap_options()}} for tmap options. +\itemize{ +\item \code{vignette("tmap_sneak_peek")} +\item \code{\link[=tmap_last]{tmap_last()}} to show the last map +\item \code{\link[=tm_view]{tm_view()}} for viewing options +\item \code{\link[=tmap_leaflet]{tmap_leaflet()}} for obtaining a leaflet widget +\item \code{\link[=tmap_options]{tmap_options()}} for tmap options +} } diff --git a/man/tmap_save.Rd b/man/tmap_save.Rd index ba94c02d..5775383c 100644 --- a/man/tmap_save.Rd +++ b/man/tmap_save.Rd @@ -27,35 +27,70 @@ tmap_save( \arguments{ \item{tm}{tmap object} -\item{filename}{filename including extension, and optionally the path. The extensions pdf, eps, svg, wmf (Windows only), png, jpg, bmp, tiff, and html are supported. If the extension is missing, the file will be saved as a static plot in \code{"plot"} mode and as an interactive map (html) in \code{"view"} mode (see details). The default format for static plots is png, but this can be changed using the option \code{"output.format"} in \code{\link[=tmap_options]{tmap_options()}}. If \code{NA} (the default), the file is saved as "tmap01" in the default format, and the number incremented if the file already exists.} - -\item{device}{graphic device to use. Either a device function (e.g., \code{\link[grDevices:png]{png}} or \code{\link[grDevices:cairo]{cairo_pdf}}) or a text indicating selected graphic device: "pdf", "eps", "svg", "wmf" (Windows only), "png", "jpg", "bmp", "tiff". If NULL, the graphic device is guessed based on the \code{filename} argument.} - -\item{height, width}{The width and height of the plot (not applicable for html files). Units are set with the argument \code{units}. If one of them is not specified, this is calculated using the formula asp = width / height, where asp is the estimated aspect ratio of the map. If both are missing, they are set such that \code{width * height} is equal to the option \code{"output.size"} in \code{\link[=tmap_options]{tmap_options()}}. This is by default 49, meaning that is the map is a square (so aspect ratio of 1) both width and height are set to 7.} - -\item{units}{units for width and height (\code{"in"}, \code{"cm"}, or \code{"mm"}). By default, pixels (\code{"px"}) are used if either width or height is set to a value greater than 50. Else, the units are inches (\code{"in"})} - -\item{dpi}{dots per inch. Only applicable for raster graphics. By default it is set to 300, but this can be changed using the option \code{"output.dpi"} in \code{\link[=tmap_options]{tmap_options()}}.} +\item{filename}{filename including extension, and optionally the path. +The extensions pdf, eps, svg, wmf (Windows only), png, jpg, bmp, tiff, and html are supported. +If the extension is missing, the file will be saved as a static plot in \code{"plot"} +mode and as an interactive map (html) in \code{"view"} mode (see details). +The default format for static plots is png, but this can be changed using +the option \code{"output.format"} in \code{\link[=tmap_options]{tmap_options()}}. If \code{NA} (the default), +the file is saved as "tmap01" in the default format, and the number incremented +if the file already exists.} + +\item{device}{graphic device to use. Either a device function +(e.g., \code{\link[grDevices:png]{png}} or \code{\link[grDevices:cairo]{cairo_pdf}}) +or a text indicating selected graphic device: "pdf", "eps", "svg", "wmf" (Windows only), "png", "jpg", "bmp", "tiff". +If \code{NULL}, the graphic device is guessed based on the \code{filename} argument.} + +\item{height, width}{The dimensions of the plot (not applicable for html files). +Units are set with the argument \code{units}. If one of them is not specified, +this is calculated using the formula asp = width / height, where asp is the +estimated aspect ratio of the map. If both are missing, they are set such +that \code{width * height} is equal to the option \code{"output.size"} in \code{\link[=tmap_options]{tmap_options()}}. +This is by default 49, meaning that is the map is a square (so aspect ratio of 1) +both width and height are set to 7.} + +\item{units}{units for width and height (\code{"in"}, \code{"cm"}, or \code{"mm"}). +By default, pixels (\code{"px"}) are used if either width or height is set to a +value greater than 50. Else, the units are inches (\code{"in"}).} + +\item{dpi}{dots per inch. Only applicable for raster graphics. By default it +is set to 300, but this can be changed using the option \code{"output.dpi"} in \code{\link[=tmap_options]{tmap_options()}}.} \item{outer.margins}{overrides the outer.margins argument of \code{\link[=tm_layout]{tm_layout()}} (unless set to \code{NA})} -\item{asp}{if specified, it overrides the asp argument of \code{\link[=tm_layout]{tm_layout()}}. Tip: set to \code{0} if map frame should be placed on the edges of the image.} +\item{asp}{if specified, it overrides the asp argument of \code{\link[=tm_layout]{tm_layout()}}. +\strong{Tip}: set to \code{0} if map frame should be placed on the edges of the image.} \item{scale}{overrides the scale argument of \code{\link[=tm_layout]{tm_layout()}} (unless set to \code{NA})} -\item{insets_tm}{tmap object of an inset map, or a list of tmap objects of multiple inset maps. The number of tmap objects should be equal to the number of viewports specified with \code{insets_vp}.} +\item{insets_tm}{tmap object of an inset map, or a list of tmap objects of +multiple inset maps. The number of tmap objects should be equal to the number +of viewports specified with \code{insets_vp}.} -\item{insets_vp}{\code{\link[grid:viewport]{viewport}} of an inset map, or a list of \code{\link[grid:viewport]{viewport}}s of multiple inset maps. The number of viewports should be equal to the number of tmap objects specified with \code{insets_tm}.} +\item{insets_vp}{\code{\link[grid:viewport]{viewport}} of an inset map, or a list +of \code{\link[grid:viewport]{viewport}}s of multiple inset maps. The number of +viewports should be equal to the number of tmap objects specified with \code{insets_tm}.} \item{add.titles}{add titles to leaflet object.} -\item{in.iframe}{should an interactive map be saved as an iframe? If so, two HTML files will be saved; one small parent HTML file with the iframe container, and one large child HTML file with the actual widget. See \code{\link[widgetframe:saveWidgetframe]{widgetframe::saveWidgetframe()}} for details. By default \code{FALSE} which means that one large HTML file is saved (see \link[htmlwidgets:saveWidget]{saveWidget()}).} +\item{in.iframe}{should an interactive map be saved as an iframe? +If so, two HTML files will be saved; one small parent HTML file with the +iframe container, and one large child HTML file with the actual widget. +See \code{\link[widgetframe:saveWidgetframe]{widgetframe::saveWidgetframe()}} for details. By default \code{FALSE}, +which means that one large HTML file is saved (see \link[htmlwidgets:saveWidget]{saveWidget()}).} -\item{selfcontained}{when an interactive map is saved, should the resources (e.g. JavaScript libraries) be contained in the HTML file? If \code{FALSE}, they are placed in an adjacent directory (see also \code{\link[htmlwidgets:saveWidget]{htmlwidgets::saveWidget()}}). Note that the HTML file will often still be large when \code{selfcontained = FALSE}, since the map data (polygons and popups), which are also contained in the HTML file, usually take more space then the map resources.} +\item{selfcontained}{when an interactive map is saved, should the resources +(e.g. JavaScript libraries) be contained in the HTML file? If \code{FALSE}, they +are placed in an adjacent directory (see also \code{\link[htmlwidgets:saveWidget]{htmlwidgets::saveWidget()}}). +Note that the HTML file will often still be large when \code{selfcontained = FALSE}, +since the map data (polygons and popups), which are also contained in the HTML file, +usually take more space then the map resources.} -\item{verbose}{Deprecated. It is now controlled by the tmap option \code{show.messages} (see \code{\link[=tmap_options]{tmap_options()}})} +\item{verbose}{Deprecated. It is now controlled by the tmap option \code{show.messages} +(see \code{\link[=tmap_options]{tmap_options()}})} -\item{...}{arguments passed on to device functions or to \code{\link[htmlwidgets:saveWidget]{saveWidget()}} or \code{\link[widgetframe:saveWidgetframe]{saveWidgetFrame()}}} +\item{...}{arguments passed on to device functions or to +\code{\link[htmlwidgets:saveWidget]{saveWidget()}} or \code{\link[widgetframe:saveWidgetframe]{saveWidgetFrame()}}} } \description{ Save tmap to a file. This can be either a static plot (e.g. png) or an interactive map (html). diff --git a/man/tmap_style.Rd b/man/tmap_style.Rd index 592e8e39..f30aaa47 100644 --- a/man/tmap_style.Rd +++ b/man/tmap_style.Rd @@ -7,20 +7,29 @@ tmap_style(style) } \arguments{ -\item{style}{Name of the style. When omitted, \code{tmap_style()} returns the current style and also shows all available styles. When the style is specified, \code{tmap_style()} sets the style accordingly. Note that in that case, all tmap options (see \code{\link[=tmap_options]{tmap_options()}}) will be reset according to the style definition. See \code{\link[=tm_layout]{tm_layout()}} for predefined styles, and \code{tmap_style_catalogue} (not migrated to v4 yet) for creating a catalogue.} +\item{style}{Name of the style. When omitted, \code{tmap_style()} returns the current style +and also shows all available styles. When the style is specified,\code{tmap_style()} +sets the style accordingly. Note that in that case, all tmap options (see \code{\link[=tmap_options]{tmap_options()}}) +will be reset according to the style definition. +See \code{\link[=tm_layout]{tm_layout()}} for predefined styles, and \code{tmap_style_catalogue} (not migrated to v4 yet) for creating a catalogue.} } \value{ The style before changing } \description{ -Set or get the default tmap style. Without arguments, the current style is returned. Also the available styles are displayed. When a style is set, the corresponding tmap options (see \code{\link[=tmap_options]{tmap_options()}}) will be set accordingly. The default style (i.e. when loading the package) is \code{"white"}. +Set or get the default tmap style. Without arguments, the current style is returned. +Also the available styles are displayed. When a style is set, the corresponding tmap +options (see \code{\link[=tmap_options]{tmap_options()}}) will be set accordingly. +The default style (i.e. when loading the package) is \code{"white"}. } \details{ -Note that \code{\link[=tm_style]{tm_style()}} is used within a plot call (so it only affects that plot), whereas \code{tmap_style()} sets the style globally. +Note that \code{\link[=tm_style]{tm_style()}} is used within a plot call (so it only affects that plot), +whereas \code{tmap_style()} sets the style globally. -After loading a style, the options that defined this style (i.e. the difference with the default \code{"white"} style) can be obtained by \code{\link[=tmap_options_diff]{tmap_options_diff()}}. +After loading a style, the options that defined this style +(i.e. the difference with the default \code{"white"} style) can be obtained by \code{\link[=tmap_options_diff]{tmap_options_diff()}}. -The documentation of \code{\link[=tmap_options]{tmap_options()}} (details and the examples) shows how a new style is created. +The documentation of \code{\link[=tmap_options]{tmap_options()}} (details and the examples) shows how to create a new style. } \examples{ tmap_style() @@ -42,5 +51,8 @@ tmap_style("cobalt_v3") tm_shape(World) + tm_polygons("HPI") } \seealso{ -\code{\link[=tmap_options]{tmap_options()}} for tmap options, and \code{tmap_style_catalogue} (not migrated to v4 yet) to create a style catalogue of all available styles. +\itemize{ +\item \code{\link[=tmap_options]{tmap_options()}} for tmap options +\item \code{tmap_style_catalogue} (not migrated to v4 yet) to create a style catalogue of all available styles. +} }