1 check_deprecated_layer_fun_args <- function(auto.palette.mapping, max.categories, midpoint) {  2 2  if (!is.null(auto.palette.mapping)) {  3 0  warning("The argument auto.palette.mapping is deprecated. Please use midpoint for numeric data and stretch.palette for categorical data to control the palette mapping.", call. = FALSE)  4 0  if (auto.palette.mapping && is.null(midpoint)) midpoint <- 0 # for backwards compatability  5 2  }  6 2  if (!is.null(max.categories)) warning("The argument max.categories is deprecated. It can be specified with tmap_options.", call. = FALSE)  7 2  midpoint  8 }  9 10 #' Add text labels  11 #'  12 #' Creates a \code{\link{tmap-element}} that adds text labels.  13 #'  14 #' @param text name of the variable in the shape object that contains the text labels  15 #' @param size relative size of the text labels (see note). Either one number, a name of a numeric variable in the shape data that is used to scale the sizes proportionally, or the value \code{"AREA"}, where the text size is proportional to the area size of the polygons.  16 #' @param col color of the text labels. Either a color value or a data variable name. If multiple values are specified, small multiples are drawn (see details).  17 #' @param root root number to which the font sizes are scaled. Only applicable if \code{size} is a variable name or \code{"AREA"}. If \code{root=2}, the square root is taken, if \code{root=3}, the cube root etc.  18 #' @param clustering value that determines whether the text labels are clustered in \code{"view"} mode. One of: \code{TRUE}, \code{FALSE}, or the output of \code{\link[leaflet:markerClusterOptions]{markerClusterOptions}}.  19 #' @param size.lim vector of two limit values of the \code{size} variable. Only text labels are drawn whose value is greater than or equal to the first value. Text labels whose values exceed the second value are drawn at the size of the second value. Only applicable when \code{size} is the name of a numeric variable of \code{shp}. See also \code{size.lowerbound} which is a threshold of the relative font size.  20 #' @param sizes.legend vector of text sizes that are shown in the legend. By default, this is determined automatically.  21 #' @param sizes.legend.labels vector of labels for that correspond to \code{sizes.legend}.  22 #' @param sizes.legend.text vector of example text to show in the legend next to sizes.legend.labels. By default "Abc". When \code{NA}, examples from the data variable whose sizes are close to the sizes.legend are taken and \code{"NA"} for classes where no match is found.  23 #' @param n preferred number of color scale classes. Only applicable when \code{col} is a numeric variable name.  24 #' @param style method to process the color scale when \code{col} is a numeric variable. Discrete options are \code{"cat"}, \code{"fixed"}, \code{"sd"}, \code{"equal"}, \code{"pretty"}, \code{"quantile"}, \code{"kmeans"}, \code{"hclust"}, \code{"bclust"}, \code{"fisher"}, \code{"jenks"}, and \code{"log10_pretty"}. A numeric variable is processed as a categorical variable when using \code{"cat"}, i.e. each unique value will correspond to a distinct category. For the other discrete options (except \code{"log10_pretty"}), see the details in \code{\link[classInt:classIntervals]{classIntervals}}. Continuous options are \code{"cont"}, \code{"order"}, and \code{"log10"}. The first maps the values of \code{col} to a smooth gradient, the second maps the order of values of \code{col} to a smooth gradient, and the third uses a logarithmic transformation.  25 #' @param breaks in case \code{style=="fixed"}, breaks should be specified. The \code{breaks} argument can also be used when \code{style="cont"}. In that case, the breaks are mapped evenly to the sequential or diverging color palette.  26 #' @param interval.closure value that determines whether where the intervals are closed: \code{"left"} or \code{"right"}. Only applicable if \code{col} is a numeric variable.  27 #' @param palette a palette name or a vector of colors. See \code{tmaptools::palette_explorer()} for the named palettes. Use a \code{"-"} as prefix to reverse the palette. The default palette is taken from \code{\link{tm_layout}}'s argument \code{aes.palette}, which typically depends on the style. The type of palette from \code{aes.palette} is automatically determined, but can be overwritten: use \code{"seq"} for sequential, \code{"div"} for diverging, and \code{"cat"} for categorical.  28 #' @param labels labels of the color classes, applicable if \code{col} is a data variable name  29 #' @param labels.text Example text to show in the legend next to the \code{labels}. When \code{NA} (default), examples from the data variable are taken and \code{"NA"} for classes where they don't exist.  30 #' @param midpoint The value mapped to the middle color of a diverging palette. By default it is set to 0 if negative and positive values are present. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to \code{NA}, which means that the value that corresponds to the middle color class (see \code{style}) is mapped to the middle color. Only applies when \code{col} is a numeric variable. If it is specified for sequential color palettes (e.g. \code{"Blues"}), then this color palette will be treated as a diverging color palette.  31 #' @param stretch.palette Logical that determines whether the categorical color palette should be stretched if there are more categories than colors. If \code{TRUE} (default), interpolated colors are used (like a rainbow). If \code{FALSE}, the palette is repeated.  32 #' @param contrast vector of two numbers that determine the range that is used for sequential and diverging palettes (applicable when \code{auto.palette.mapping=TRUE}). Both numbers should be between 0 and 1. The first number determines where the palette begins, and the second number where it ends. For sequential palettes, 0 means the brightest color, and 1 the darkest color. For diverging palettes, 0 means the middle color, and 1 both extremes. If only one number is provided, this number is interpreted as the endpoint (with 0 taken as the start).  33 #' @param colorNA colour for missing values. Use \code{NULL} for transparency.  34 #' @param textNA text used for missing values.  35 #' @param showNA logical that determines whether missing values are named in the legend. By default (\code{NA}), this depends on the presence of missing values.  36 #' @param colorNULL colour for polygons that are shown on the map that are out of scope  37 #' @param fontface font face of the text labels. By default, determined by the fontface argument of \code{\link{tm_layout}}.  38 #' @param fontfamily font family of the text labels. By default, determined by the fontfamily argument of \code{\link{tm_layout}}.  39 #' @param alpha transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{fontcolor} is used (normally 1).  40 #' @param case case of the font. Use "upper" to generate upper-case text, "lower" to generate lower-case text, and \code{NA} to leave the text as is.  41 #' @param shadow logical that determines whether a shadow is depicted behind the text. The color of the shadow is either white or yellow, depending of the \code{fontcolor}.  42 #' @param bg.color background color of the text labels. By default, \code{bg.color=NA}, so no background is drawn.  43 #' @param bg.alpha number between 0 and 1 that specifies the transparency of the text background (0 is totally transparent, 1 is solid background).  44 #' @param size.lowerbound lowerbound for \code{size}. Only applicable when \code{size} is not a constant. If \code{print.tiny} is \code{TRUE}, then all text labels which relative text is smaller than \code{size.lowerbound} are depicted at relative size \code{size.lowerbound}. If \code{print.tiny} is \code{FALSE}, then text labels are only depicted if their relative sizes are at least \code{size.lowerbound} (in other words, tiny labels are omitted).  45 #' @param print.tiny boolean, see \code{size.lowerbound}  46 #' @param scale text size multiplier, useful in case \code{size} is variable or \code{"AREA"}.  47 #' @param auto.placement logical (or numeric) that determines whether the labels are placed automatically. If \code{TRUE}, the labels are placed next to the coordinate points with as little overlap as possible using the simulated annealing algorithm. Therefore, it is recommended for labeling spatial dots or symbols. If a numeric value is provided, this value acts as a parameter that specifies the distance between the coordinate points and the text labels in terms of text line heights.  48 #' @param remove.overlap logical that determines whether the overlapping labels are removed  49 #' @param along.lines logical that determines whether labels are rotated along the spatial lines. Only applicable if a spatial lines shape is used.  50 #' @param overwrite.lines logical that determines whether the part of the lines below the text labels is removed. Only applicable if a spatial lines shape is used.  51 #' @param just justification of the text relative to the point coordinates. Either one of the following values: \code{"left"} , \code{"right"}, \code{"center"}, \code{"bottom"}, and \code{"top"}, or a vector of two values where first value specifies horizontal and the second value vertical justification. Besides the mentioned values, also numeric values between 0 and 1 can be used. 0 means left justification for the first value and bottom justification for the second value. Note that in view mode, only one value is used.  52 #' @param xmod horizontal position modification of the text (relatively): 0 means no modification, and 1 corresponds to the height of one line of text. Either a single number for all polygons, or a numeric variable in the shape data specifying a number for each polygon. Together with \code{ymod}, it determines position modification of the text labels. In most coordinate systems (projections), the origin is located at the bottom left, so negative \code{xmod} move the text to the left, and negative \code{ymod} values to the bottom.  53 #' @param ymod vertical position modification. See xmod.  54 #' @param title.size title of the legend element regarding the text sizes  55 #' @param title.col title of the legend element regarding the text colors  56 #' @param legend.size.show logical that determines whether the legend for the text sizes is shown  57 #' @param legend.col.show logical that determines whether the legend for the text colors is shown  58 #' @param legend.format list of formatting options for the legend numbers. Only applicable if \code{labels} is undefined. Parameters are:  59 #' \describe{  60 #' \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.}  61 #' \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.}  62 #' \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.}  63 #' \item{digits}{Number of digits after the decimal point if \code{format="f"}, and the number of significant digits otherwise.}  64 #' \item{big.num.abbr}{Vector that defines whether and which abbrevations are used for large numbers. It is a named numeric vector, where the name indicated the abbreviation, and the number the magnitude (in terms on numbers of zero). Numbers are only abbrevation when they are large enough. Set it to \code{NA} to disable abbrevations. The default is \code{c("mln" = 6, "bln" = 9)}. For layers where \code{style} is set to \code{log10} or \code{log10_pretty}, the default is \code{NA}.}  65 #' \item{text.separator}{Character string to use to separate numbers in the legend (default: "to").}  66 #' \item{text.less.than}{Character value(s) to use to translate "Less than". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  67 #' \item{text.or.more}{Character value(s) to use to translate "or more". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  68 #' \item{text.align}{Value that determines how the numbers are aligned, \code{"left"}, \code{"center"} or \code{"right"}}. By default \code{"left"} for legends in portrait format (\code{legend.is.portrait = TRUE}), and \code{"center"} otherwise.  69 #' \item{text.to.columns}{Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default \code{FALSE}.}  70 #' \item{...}{Other arguments passed on to \code{\link[base:formatC]{formatC}}}  71 #' }  72 #' @param legend.size.is.portrait logical that determines whether the legend element regarding the text sizes is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  73 #' @param legend.size.reverse logical that determines whether the items of the legend regarding the text sizes are shown in reverse order, i.e. from bottom to top when \code{legend.size.is.portrait = TRUE} and from right to left when \code{legend.size.is.portrait = FALSE}  74 #' @param legend.hist logical that determines whether a histogram is shown regarding the text colors  75 #' @param legend.hist.title title for the histogram. By default, one title is used for both the histogram and the normal legend for text colors.  76 #' @param legend.col.is.portrait logical that determines whether the legend element regarding the text colors is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  77 #' @param legend.col.reverse logical that determines whether the items of the legend regarding the text colors are shown in reverse order, i.e. from bottom to top when \code{legend.col.is.portrait = TRUE} and from right to left when \code{legend.col.is.portrait = FALSE}  78 #' @param legend.size.z index value that determines the position of the legend element regarding the text sizes with respect to other legend elements. The legend elements are stacked according to their z values. The legend element with the lowest z value is placed on top.  79 #' @param legend.col.z index value that determines the position of the legend element regarding the text colors. (See \code{legend.size.z})  80 #' @param legend.hist.z index value that determines the position of the histogram legend element. (See \code{legend.size.z})  81 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}).  82 #' @param auto.palette.mapping deprecated. It has been replaced by \code{midpoint} for numeric variables and \code{stretch.palette} for categorical variables.  83 #' @param max.categories deprecated. It has moved to \code{\link{tmap_options}}.  84 #' @note The absolute fontsize (in points) is determined by the (ROOT) viewport, which may depend on the graphics device.  85 #' @export  86 #' @example ./examples/tm_text.R  87 #' @seealso \href{../doc/tmap-getstarted.html}{\code{vignette("tmap-getstarted")}}  88 #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \href{https://doi.org/10.18637/jss.v084.i06}{DOI}  89 #' @return \code{\link{tmap-element}}  90 tm_text <- function(text, size=1, col=NA, root=3,  91  clustering=FALSE,  92  size.lim=NA,  93  sizes.legend = NULL,  94  sizes.legend.labels = NULL,  95  sizes.legend.text = "Abc",  96  n = 5, style = ifelse(is.null(breaks), "pretty", "fixed"),  97  breaks = NULL,  98  interval.closure = "left",  99  palette = NULL,  100  labels = NULL,  101  labels.text = NA,  102  midpoint = NULL,  103  stretch.palette = TRUE,  104  contrast = NA,  105  colorNA = NA,  106  textNA = "Missing",  107  showNA = NA,  108  colorNULL = NA,  109  fontface=NA,  110  fontfamily=NA, alpha=NA, case=NA, shadow=FALSE, bg.color=NA, bg.alpha=NA, size.lowerbound=.4, print.tiny=FALSE, scale=1, auto.placement=FALSE, remove.overlap=FALSE, along.lines=FALSE, overwrite.lines=FALSE, just="center", xmod=0, ymod=0,  111  title.size = NA,  112  title.col = NA,  113  legend.size.show=TRUE,  114  legend.col.show=TRUE,  115  legend.format=list(),  116  legend.size.is.portrait=FALSE,  117  legend.col.is.portrait=TRUE,  118  legend.size.reverse=FALSE,  119  legend.col.reverse=FALSE,  120  legend.hist=FALSE,  121  legend.hist.title=NA,  122  legend.size.z=NA,  123  legend.col.z=NA,  124  legend.hist.z=NA,  125  group = NA,  126  auto.palette.mapping = NULL,  127  max.categories = NULL) {  128 2  midpoint <- check_deprecated_layer_fun_args(auto.palette.mapping, max.categories, midpoint)  129 130 2  g <- list(tm_text=c(as.list(environment()), list(call=names(match.call(expand.dots = TRUE)[-1]))))  131 2  class(g) <- "tmap"  132 2  g  133 }  134   135 #' Draw iso (contour) lines with labels  136 #'  137 #' This function is a wrapper of \code{\link{tm_lines}} and \code{\link{tm_text}} aimed to draw isopleths, which can be created with \code{\link[tmaptools:smooth_map]{smooth_map}}.  138 #'  139 #' @param col line color. See \code{\link{tm_lines}}.  140 #' @param text text to display. By default, it is the variable named \code{"level"} of the shape that is created with \code{\link[tmaptools:smooth_map]{smooth_map}}  141 #' @param size text size (see \code{\link{tm_text}})  142 #' @param remove.overlap see \code{\link{tm_text}}  143 #' @param along.lines see \code{\link{tm_text}}  144 #' @param overwrite.lines see \code{\link{tm_text}}  145 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}).  146 #' @param ... arguments passed on to \code{\link{tm_lines}} or \code{\link{tm_text}}  147 #' @export  148 #' @seealso \code{\link[tmaptools:smooth_map]{smooth_map}}  149 tm_iso <- function(col=NA, text="level", size=.5,  150  remove.overlap=TRUE, along.lines=TRUE, overwrite.lines=TRUE,  151  group = NA, ...) {  152 0  args <- list(...)  153 0  argsL <- args[intersect(names(formals("tm_lines")), names(args))]  154 0  argsT <- args[intersect(names(formals("tm_text")), names(args))]  155   156 0  do.call("tm_lines", c(list(col=col), argsL)) +  157 0  do.call("tm_text", c(list(text=text, size=size,  158 0  remove.overlap=remove.overlap,  159 0  along.lines=along.lines,  160 0  overwrite.lines = overwrite.lines),  161 0  argsT))  162 }  163 164 #' Draw spatial lines  165 #'  166 #' Creates a \code{\link{tmap-element}} that draw spatial lines.  167 #'  168 #' Small multiples can be drawn in two ways: either by specifying the \code{by} argument in \code{\link{tm_facets}}, or by defining multiple variables in the aesthetic arguments. The aesthetic arguments of \code{tm_lines} are \code{col} and \code{lwd}. In the latter case, the arguments, except for the ones starting with \code{legend.}, can be specified for small multiples as follows. If the argument normally only takes a single value, such as \code{n}, then a vector of those values can be specified, one for each small multiple. If the argument normally can take a vector, such as \code{palette}, then a list of those vectors (or values) can be specified, one for each small multiple.  169 #'  170 #' @param col color of the lines. Either a color value or a data variable name. If multiple values are specified, small multiples are drawn (see details).  171 #' @param lwd line width. Either a numeric value or a data variable. In the latter case, the class of the highest values (see \code{style}) will get the line width defined by \code{scale}. If multiple values are specified, small multiples are drawn (see details).  172 #' @param lty line type.  173 #' @param alpha transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{col} is used (normally 1).  174 #' @param scale line width multiplier number.  175 #' @param lwd.legend vector of line widths that are shown in the legend. By default, this is determined automatically.  176 #' @param lwd.legend.labels vector of labels for that correspond to \code{lwd.legend}.  177 #' @param n preferred number of color scale classes. Only applicable when \code{lwd} is the name of a numeric variable.  178 #' @param style method to process the color scale when \code{col} is a numeric variable. Discrete options are \code{"cat"}, \code{"fixed"}, \code{"sd"}, \code{"equal"}, \code{"pretty"}, \code{"quantile"}, \code{"kmeans"}, \code{"hclust"}, \code{"bclust"}, \code{"fisher"}, \code{"jenks"}, and \code{"log10_pretty"}. A numeric variable is processed as a categorical variable when using \code{"cat"}, i.e. each unique value will correspond to a distinct category. For the other discrete options (except \code{"log10_pretty"}), see the details in \code{\link[classInt:classIntervals]{classIntervals}}. Continuous options are \code{"cont"}, \code{"order"}, and \code{"log10"}. The first maps the values of \code{col} to a smooth gradient, the second maps the order of values of \code{col} to a smooth gradient, and the third uses a logarithmic transformation.  179 #' @param breaks in case \code{style=="fixed"}, breaks should be specified. The \code{breaks} argument can also be used when \code{style="cont"}. In that case, the breaks are mapped evenly to the sequential or diverging color palette.  180 #' @param interval.closure value that determines whether where the intervals are closed: \code{"left"} or \code{"right"}. Only applicable if \code{col} is a numeric variable.  181 #' @param palette a palette name or a vector of colors. See \code{tmaptools::palette_explorer()} for the named palettes. Use a \code{"-"} as prefix to reverse the palette. The default palette is taken from \code{\link{tm_layout}}'s argument \code{aes.palette}, which typically depends on the style. The type of palette from \code{aes.palette} is automatically determined, but can be overwritten: use \code{"seq"} for sequential, \code{"div"} for diverging, and \code{"cat"} for categorical.  182 #' @param labels labels of the classes  183 #' @param midpoint The value mapped to the middle color of a diverging palette. By default it is set to 0 if negative and positive values are present. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to \code{NA}, which means that the value that corresponds to the middle color class (see \code{style}) is mapped to the middle color. Only applies when \code{col} is a numeric variable. If it is specified for sequential color palettes (e.g. \code{"Blues"}), then this color palette will be treated as a diverging color palette.  184 #' @param stretch.palette Logical that determines whether the categorical color palette should be stretched if there are more categories than colors. If \code{TRUE} (default), interpolated colors are used (like a rainbow). If \code{FALSE}, the palette is repeated.  185 #' @param contrast vector of two numbers that determine the range that is used for sequential and diverging palettes (applicable when \code{auto.palette.mapping=TRUE}). Both numbers should be between 0 and 1. The first number determines where the palette begins, and the second number where it ends. For sequential palettes, 0 means the brightest color, and 1 the darkest color. For diverging palettes, 0 means the middle color, and 1 both extremes. If only one number is provided, this number is interpreted as the endpoint (with 0 taken as the start).  186 #' @param colorNA color used for missing values. Use \code{NULL} for transparency.  187 #' @param textNA text used for missing values.  188 #' @param showNA logical that determines whether missing values are named in the legend. By default (\code{NA}), this depends on the presence of missing values.  189 #' @param colorNULL colour for polygons that are shown on the map that are out of scope  190 #' @param title.col title of the legend element regarding the line colors  191 #' @param title.lwd title of the legend element regarding the line widths  192 #' @param legend.col.show logical that determines whether the legend for the line colors is shown  193 #' @param legend.lwd.show logical that determines whether the legend for the line widths is shown  194 #' @param legend.format list of formatting options for the legend numbers. Only applicable if \code{labels} is undefined. Parameters are:  195 #' \describe{  196 #' \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.}  197 #' \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.}  198 #' \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.}  199 #' \item{digits}{Number of digits after the decimal point if \code{format="f"}, and the number of significant digits otherwise.}  200 #' \item{big.num.abbr}{Vector that defines whether and which abbrevations are used for large numbers. It is a named numeric vector, where the name indicated the abbreviation, and the number the magnitude (in terms on numbers of zero). Numbers are only abbrevation when they are large enough. Set it to \code{NA} to disable abbrevations. The default is \code{c("mln" = 6, "bln" = 9)}. For layers where \code{style} is set to \code{log10} or \code{log10_pretty}, the default is \code{NA}.}  201 #' \item{text.separator}{Character string to use to separate numbers in the legend (default: "to").}  202 #' \item{text.less.than}{Character value(s) to use to translate "Less than". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  203 #' \item{text.or.more}{Character value(s) to use to translate "or more". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  204 #' \item{text.align}{Value that determines how the numbers are aligned, \code{"left"}, \code{"center"} or \code{"right"}}. By default \code{"left"} for legends in portrait format (\code{legend.is.protrait = TRUE}), and \code{"center"} otherwise.  205 #' \item{text.to.columns}{Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default \code{FALSE}.}  206 #' \item{...}{Other arguments passed on to \code{\link[base:formatC]{formatC}}}  207 #' }  208 #' @param legend.col.is.portrait logical that determines whether the legend element regarding the line colors is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  209 #' @param legend.lwd.is.portrait logical that determines whether the legend element regarding the line widths is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  210 #' @param legend.col.reverse logical that determines whether the items of the legend regarding the line colors sizes are shown in reverse order, i.e. from bottom to top when \code{legend.col.is.portrait = TRUE} and from right to left when \code{legend.col.is.portrait = FALSE}  211 #' @param legend.lwd.reverse logical that determines whether the items of the legend regarding the line widths are shown in reverse order, i.e. from bottom to top when \code{legend.lwd.is.portrait = TRUE} and from right to left when \code{legend.lwd.is.portrait = FALSE}  212 #' @param legend.hist logical that determines whether a histogram is shown regarding the line colors  213 #' @param legend.hist.title title for the histogram. By default, one title is used for both the histogram and the normal legend for line colors.  214 #' @param legend.col.z index value that determines the position of the legend element regarding the line colors with respect to other legend elements. The legend elements are stacked according to their z values. The legend element with the lowest z value is placed on top.  215 #' @param legend.lwd.z index value that determines the position of the legend element regarding the line widths. (See \code{legend.col.z})  216 #' @param legend.hist.z index value that determines the position of the legend element regarding the histogram. (See \code{legend.col.z})  217 #' @param id name of the data variable that specifies the indices of the lines. Only used for \code{"view"} mode (see \code{\link{tmap_mode}}).  218 #' @param popup.vars names of data variables that are shown in the popups in \code{"view"} mode. If \code{NA} (default), only aesthetic variables (i.e. specified by \code{col} and \code{lwd}) are shown). If they are not specified, all variables are shown. Set popup.vars to \code{FALSE} to disable popups. When a vector of variable names is provided, the names (if specified) are printed in the popups.  219 #' @param 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.  220 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}).  221 #' @param auto.palette.mapping deprecated. It has been replaced by \code{midpoint} for numeric variables and \code{stretch.palette} for categorical variables.  222 #' @param max.categories deprecated. It has moved to \code{\link{tmap_options}}.  223 #' @export  224 #' @seealso \href{../doc/tmap-getstarted.html}{\code{vignette("tmap-getstarted")}}  225 #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \href{https://doi.org/10.18637/jss.v084.i06}{DOI}  226 #' @example ./examples/tm_lines.R  227 #' @return \code{\link{tmap-element}}  228 tm_lines <- function(col=NA, lwd=1, lty="solid", alpha=NA,  229  scale=1,  230  lwd.legend = NULL,  231  lwd.legend.labels = NULL,  232  n = 5, style = ifelse(is.null(breaks), "pretty", "fixed"),  233  breaks = NULL,  234  interval.closure = "left",  235  palette = NULL,  236  labels = NULL,  237  midpoint = NULL,  238  stretch.palette = TRUE,  239  contrast = NA,  240  colorNA = NA,  241  textNA = "Missing",  242  showNA = NA,  243  colorNULL = NA,  244  title.col=NA,  245  title.lwd=NA,  246  legend.col.show=TRUE,  247  legend.lwd.show=TRUE,  248  legend.format=list(),  249  legend.col.is.portrait=TRUE,  250  legend.lwd.is.portrait=FALSE,  251  legend.col.reverse=FALSE,  252  legend.lwd.reverse=FALSE,  253  legend.hist=FALSE,  254  legend.hist.title=NA,  255  legend.col.z=NA,  256  legend.lwd.z=NA,  257  legend.hist.z=NA,  258  id=NA,  259  popup.vars=NA,  260  popup.format=list(),  261  group = NA,  262  auto.palette.mapping = NULL,  263  max.categories = NULL) {  264 2  midpoint <- check_deprecated_layer_fun_args(auto.palette.mapping, max.categories, midpoint)  265 2  g <- list(tm_lines=c(as.list(environment()), list(call=names(match.call(expand.dots = TRUE)[-1]))))  266 2  class(g) <- "tmap"  267 2  g  268 }  269 270 271 272 273 #' Draw polygons  274 #'  275 #' Creates a \code{\link{tmap-element}} that draws the polygons. \code{tm_fill} fills the polygons. Either a fixed color is used, or a color palette is mapped to a data variable. \code{tm_borders} draws the borders of the polygons. \code{tm_polygons} fills the polygons and draws the polygon borders.  276 #'  277 #' Small multiples can be drawn in two ways: either by specifying the \code{by} argument in \code{\link{tm_facets}}, or by defining multiple variables in the aesthetic arguments. The aesthetic argument of \code{tm_fill} (and \code{tm_polygons}) is \code{col}. In the latter case, the arguments, except for \code{thres.poly}, and the ones starting with \code{legend.}, can be specified for small multiples as follows. If the argument normally only takes a single value, such as \code{n}, then a vector of those values can be specified, one for each small multiple. If the argument normally can take a vector, such as \code{palette}, then a list of those vectors (or values) can be specified, one for each small multiple.  278 #'  279 #' @name tm_fill  280 #' @rdname tm_polygons  281 #' @param col For \code{tm_fill}, it is one of  282 #' \itemize{  283 #' \item a single color value  284 #' \item the name of a data variable that is contained in \code{shp}. Either the data variable contains color values, or values (numeric or categorical) that will be depicted by a color palette (see \code{palette}. In the latter case, a choropleth is drawn.  285 #' \item \code{"MAP_COLORS"}. In this case polygons will be colored such that adjacent polygons do not get the same color. See the underlying function \code{\link[tmaptools:map_coloring]{map_coloring}} for details.}  286 #' For \code{tm_borders}, it is a single color value that specifies the border line color. If multiple values are specified, small multiples are drawn (see details).  287 #' @param alpha transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{col} is used (normally 1).  288 #' @param palette a palette name or a vector of colors. See \code{tmaptools::palette_explorer()} for the named palettes. Use a \code{"-"} as prefix to reverse the palette. The default palette is taken from \code{\link{tm_layout}}'s argument \code{aes.palette}, which typically depends on the style. The type of palette from \code{aes.palette} is automatically determined, but can be overwritten: use \code{"seq"} for sequential, \code{"div"} for diverging, and \code{"cat"} for categorical.  289 #' @param convert2density boolean that determines whether \code{col} is converted to a density variable. Should be \code{TRUE} when \code{col} consists of absolute numbers. The area size is either approximated from the shape object, or given by the argument \code{area}.  290 #' @param area Name of the data variable that contains the area sizes in squared kilometer.  291 #' @param n preferred number of classes (in case \code{col} is a numeric variable).  292 #' @param style method to process the color scale when \code{col} is a numeric variable. Discrete options are \code{"cat"}, \code{"fixed"}, \code{"sd"}, \code{"equal"}, \code{"pretty"}, \code{"quantile"}, \code{"kmeans"}, \code{"hclust"}, \code{"bclust"}, \code{"fisher"}, \code{"jenks"}, and \code{"log10_pretty"}. A numeric variable is processed as a categorical variable when using \code{"cat"}, i.e. each unique value will correspond to a distinct category. For the other discrete options (except \code{"log10_pretty"}), see the details in \code{\link[classInt:classIntervals]{classIntervals}}. Continuous options are \code{"cont"}, \code{"order"}, and \code{"log10"}. The first maps the values of \code{col} to a smooth gradient, the second maps the order of values of \code{col} to a smooth gradient, and the third uses a logarithmic transformation.  293 #' @param breaks in case \code{style=="fixed"}, breaks should be specified. The \code{breaks} argument can also be used when \code{style="cont"}. In that case, the breaks are mapped evenly to the sequential or diverging color palette.  294 #' @param interval.closure value that determines whether where the intervals are closed: \code{"left"} or \code{"right"}. Only applicable if \code{col} is a numeric variable.  295 #' @param labels labels of the classes.  296 #' @param midpoint The value mapped to the middle color of a diverging palette. By default it is set to 0 if negative and positive values are present. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to \code{NA}, which means that the value that corresponds to the middle color class (see \code{style}) is mapped to the middle color. Only applies when \code{col} is a numeric variable. If it is specified for sequential color palettes (e.g. \code{"Blues"}), then this color palette will be treated as a diverging color palette.  297 #' @param stretch.palette Logical that determines whether the categorical color palette should be stretched if there are more categories than colors. If \code{TRUE} (default), interpolated colors are used (like a rainbow). If \code{FALSE}, the palette is repeated.  298 #' @param contrast vector of two numbers that determine the range that is used for sequential and diverging palettes (applicable when \code{auto.palette.mapping=TRUE}). Both numbers should be between 0 and 1. The first number determines where the palette begins, and the second number where it ends. For sequential palettes, 0 means the brightest color, and 1 the darkest color. For diverging palettes, 0 means the middle color, and 1 both extremes. If only one number is provided, this number is interpreted as the endpoint (with 0 taken as the start).  299 #' @param colorNA color used for missing values. Use \code{NULL} for transparency.  300 #' @param textNA text used for missing values.  301 #' @param showNA logical that determines whether missing values are named in the legend. By default (\code{NA}), this depends on the presence of missing values.  302 #' @param colorNULL colour for polygons that are shown on the map that are out of scope  303 #' @param thres.poly number that specifies the threshold at which polygons are taken into account. The number itself corresponds to the proportion of the area sizes of the polygons to the total polygon size. By default, all polygons are drawn. To ignore polygons that are not visible in a normal plot, a value like \code{1e-05} is recommended.  304 #' @param title title of the legend element  305 #' @param legend.show logical that determines whether the legend is shown  306 #' @param legend.format list of formatting options for the legend numbers. Only applicable if \code{labels} is undefined. Parameters are:  307 #' \describe{  308 #' \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.}  309 #' \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.}  310 #' \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.}  311 #' \item{digits}{Number of digits after the decimal point if \code{format="f"}, and the number of significant digits otherwise.}  312 #' \item{big.num.abbr}{Vector that defines whether and which abbrevations are used for large numbers. It is a named numeric vector, where the name indicated the abbreviation, and the number the magnitude (in terms on numbers of zero). Numbers are only abbrevation when they are large enough. Set it to \code{NA} to disable abbrevations. The default is \code{c("mln" = 6, "bln" = 9)}. For layers where \code{style} is set to \code{log10} or \code{log10_pretty}, the default is \code{NA}.}  313 #' \item{text.separator}{Character string to use to separate numbers in the legend (default: "to").}  314 #' \item{text.less.than}{Character value(s) to use to translate "Less than". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  315 #' \item{text.or.more}{Character value(s) to use to translate "or more". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  316 #' \item{text.align}{Value that determines how the numbers are aligned, \code{"left"}, \code{"center"} or \code{"right"}}. By default \code{"left"} for legends in portrait format (\code{legend.is.protrait = TRUE}), and \code{"center"} otherwise.  317 #' \item{text.to.columns}{Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default \code{FALSE}.}  318 #' \item{...}{Other arguments passed on to \code{\link[base:formatC]{formatC}}}  319 #' }  320 #' @param legend.is.portrait logical that determines whether the legend is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  321 #' @param legend.reverse logical that determines whether the items are shown in reverse order, i.e. from bottom to top when \code{legend.is.portrait = TRUE} and from right to left when \code{legend.is.portrait = FALSE}  322 #' @param legend.hist logical that determines whether a histogram is shown  323 #' @param legend.hist.title title for the histogram. By default, one title is used for both the histogram and the normal legend.  324 #' @param legend.z index value that determines the position of the legend element with respect to other legend elements. The legend elements are stacked according to their z values. The legend element with the lowest z value is placed on top.  325 #' @param legend.hist.z index value that determines the position of the histogram legend element  326 #' @param id name of the data variable that specifies the indices of the polygons. Only used for \code{"view"} mode (see \code{\link{tmap_mode}}).  327 #' @param popup.vars names of data variables that are shown in the popups in \code{"view"} mode. If \code{convert2density=TRUE}, the derived density variable name is suffixed with \code{_density}. If \code{NA} (default), only aesthetic variables (i.e. specified by \code{col} and \code{lwd}) are shown). If they are not specified, all variables are shown. Set popup.vars to \code{FALSE} to disable popups. When a vector of variable names is provided, the names (if specified) are printed in the popups.  328 #' @param 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.  329 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}).  330 #' @param auto.palette.mapping deprecated. It has been replaced by \code{midpoint} for numeric variables and \code{stretch.palette} for categorical variables.  331 #' @param max.categories deprecated. It has moved to \code{\link{tmap_options}}.  332 #' @param ... for \code{tm_polygons}, these arguments passed to either \code{tm_fill} or \code{tm_borders}. For \code{tm_fill}, these arguments are passed on to \code{\link[tmaptools:map_coloring]{map_coloring}}.  333 #' @keywords choropleth  334 #' @export  335 #' @example ./examples/tm_fill.R  336 #' @seealso \href{../doc/tmap-getstarted.html}{\code{vignette("tmap-getstarted")}}  337 #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \href{https://doi.org/10.18637/jss.v084.i06}{DOI}  338 #' @return \code{\link{tmap-element}}  339 tm_fill <- function(col=NA,  340  alpha=NA,  341  palette = NULL,  342  convert2density = FALSE,  343  area = NULL,  344  n = 5,  345  style = ifelse(is.null(breaks), "pretty", "fixed"),  346  breaks = NULL,  347  interval.closure = "left",  348  labels = NULL,  349  midpoint = NULL,  350  stretch.palette = TRUE,  351  contrast = NA,  352  colorNA = NA,  353  textNA = "Missing",  354  showNA = NA,  355  colorNULL = NA,  356  thres.poly = 0,  357  title=NA,  358  legend.show=TRUE,  359  legend.format=list(),  360  legend.is.portrait=TRUE,  361  legend.reverse=FALSE,  362  legend.hist=FALSE,  363  legend.hist.title=NA,  364  legend.z=NA,  365  legend.hist.z=NA,  366  id=NA,  367  popup.vars=NA,  368  popup.format=list(),  369  group = NA,  370  auto.palette.mapping = NULL,  371  max.categories = NULL,  372  ...) {  373 2  midpoint <- check_deprecated_layer_fun_args(auto.palette.mapping, max.categories, midpoint)  374 2  g <- list(tm_fill=c(as.list(environment()), list(map_coloring=list(...), call=names(match.call(expand.dots = TRUE)[-1]))))  375 2  class(g) <- "tmap"  376 2  g  377 }  378 379 380 #' @name tm_borders  381 #' @rdname tm_polygons  382 #' @param lwd border line width (see \code{\link[graphics:par]{par}})  383 #' @param lty border line type (see \code{\link[graphics:par]{par}})  384 #' @export  385 tm_borders <- function(col=NA, lwd=1, lty="solid", alpha=NA, group = NA) {  386 2  g <- list(tm_borders=as.list(environment()))  387 2  class(g) <- "tmap"  388 2  g  389 }  390 391 #' @name tm_polygons  392 #' @rdname tm_polygons  393 #' @param border.col border line color  394 #' @param border.alpha transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{col} is used (normally 1).  395 #' @export  396 tm_polygons <- function(col=NA,  397  alpha=NA,  398  border.col=NA,  399  border.alpha=NA,  400  group = NA,  401  ...) {  402 2  args <- list(...)  403 2  argsFill <- c(list(col=col, alpha=alpha, group=group), args[setdiff(names(args), c("lwd", "lty"))])  404 2  argsBorders <- c(list(col=border.col, alpha=border.alpha), args[intersect(names(args), names(formals("tm_borders")))])  405 2  g <- do.call("tm_fill", argsFill) + do.call("tm_borders", argsBorders)  406 2  g$tm_fill$call <- names(match.call(expand.dots = TRUE)[-1])  407 2  g  408 }  409 410 411 #' Draw a raster  412 #'  413 #' Creates a \code{\link{tmap-element}} that draws a raster. For coloring, there are three options: 1) a fixed color is used, 2) a color palette is mapped to a data variable, 3) RGB values are used. The function \code{tm_raster} is designed for options 1 and 2, while \code{tm_rgb} is used for option 3.  414 #'  415 #' Small multiples can be drawn in two ways: either by specifying the \code{by} argument in \code{\link{tm_facets}}, or by defining multiple variables in the aesthetic arguments. The aesthetic argument of \code{tm_raster} is \code{col}. In the latter case, the arguments, except for the ones starting with \code{legend.}, can be specified for small multiples as follows. If the argument normally only takes a single value, such as \code{n}, then a vector of those values can be specified, one for each small multiple. If the argument normally can take a vector, such as \code{palette}, then a list of those vectors (or values) can be specified, one for each small multiple.  416 #'  417 #' @param col three options: a single color value, the name of a data variable that is contained in \code{shp}, or the name of a variable in \code{shp} that contain color values. In the second case the values (numeric or categorical) that will be depicted by a color palette (see \code{palette}. If multiple values are specified, small multiples are drawn (see details). By default, it is a vector of the names of all data variables unless the \code{by} argument of \code{\link{tm_facets}} is defined (in that case, the default color of dots is taken from the tmap option \code{aes.color}). Note that the number of small multiples is limited by \code{tmap_options("limits")}).  418 #' @param r raster band for the red channel. It should be an integer between 1 and the number of raster layers.  419 #' @param g raster band for the green channel. It should be an integer between 1 and the number of raster layers.  420 #' @param b raster band for the blue channel. It should be an integer between 1 and the number of raster layers.  421 #' @param a raster band for the alpha channel. It should be an integer between 1 and the number of raster layers.  422 #' @param alpha transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{col} is used (normally 1).  423 #' @param palette a palette name or a vector of colors. See \code{tmaptools::palette_explorer()} for the named palettes. Use a \code{"-"} as prefix to reverse the palette. The default palette is taken from \code{\link{tm_layout}}'s argument \code{aes.palette}, which typically depends on the style. The type of palette from \code{aes.palette} is automatically determined, but can be overwritten: use \code{"seq"} for sequential, \code{"div"} for diverging, and \code{"cat"} for categorical.  424 #' @param n preferred number of classes (in case \code{col} is a numeric variable)  425 #' @param style method to process the color scale when \code{col} is a numeric variable. Discrete options are \code{"cat"}, \code{"fixed"}, \code{"sd"}, \code{"equal"}, \code{"pretty"}, \code{"quantile"}, \code{"kmeans"}, \code{"hclust"}, \code{"bclust"}, \code{"fisher"}, \code{"jenks"}, and \code{"log10_pretty"}. A numeric variable is processed as a categorical variable when using \code{"cat"}, i.e. each unique value will correspond to a distinct category. For the other discrete options (except \code{"log10_pretty"}), see the details in \code{\link[classInt:classIntervals]{classIntervals}}. Continuous options are \code{"cont"}, \code{"order"}, and \code{"log10"}. The first maps the values of \code{col} to a smooth gradient, the second maps the order of values of \code{col} to a smooth gradient, and the third uses a logarithmic transformation.  426 #' @param breaks in case \code{style=="fixed"}, breaks should be specified. The \code{breaks} argument can also be used when \code{style="cont"}. In that case, the breaks are mapped evenly to the sequential or diverging color palette.  427 #' @param interval.closure value that determines whether where the intervals are closed: \code{"left"} or \code{"right"}. Only applicable if \code{col} is a numeric variable.  428 #' @param labels labels of the classes  429 #' @param midpoint The value mapped to the middle color of a diverging palette. By default it is set to 0 if negative and positive values are present. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to \code{NA}, which means that the value that corresponds to the middle color class (see \code{style}) is mapped to the middle color. Only applies when \code{col} is a numeric variable. If it is specified for sequential color palettes (e.g. \code{"Blues"}), then this color palette will be treated as a diverging color palette.  430 #' @param stretch.palette Logical that determines whether the categorical color palette should be stretched if there are more categories than colors. If \code{TRUE} (default), interpolated colors are used (like a rainbow). If \code{FALSE}, the palette is repeated.  431 #' @param contrast vector of two numbers that determine the range that is used for sequential and diverging palettes (applicable when \code{auto.palette.mapping=TRUE}). Both numbers should be between 0 and 1. The first number determines where the palette begins, and the second number where it ends. For sequential palettes, 0 means the brightest color, and 1 the darkest color. For diverging palettes, 0 means the middle color, and 1 both extremes. If only one number is provided, this number is interpreted as the endpoint (with 0 taken as the start).  432 #' @param saturation Number that determines how much saturation (also known as chroma) is used: \code{saturation=0} is greyscale and \code{saturation=1} is normal. This saturation value is multiplied by the overall saturation of the map (see \code{\link{tm_layout}}).  433 #' @param interpolate Should the raster image be interpolated? By default \code{FALSE} for \code{tm_raster} and \code{TRUE} for \code{tm_rgb}.  434 #' @param colorNA color used for missing values. Use \code{NULL} for transparency.  435 #' @param textNA text used for missing values.  436 #' @param showNA logical that determines whether missing values are named in the legend. By default (\code{NA}), this depends on the presence of missing values.  437 #' @param colorNULL colour for polygons that are shown on the map that are out of scope  438 #' @param title title of the legend element  439 #' @param legend.show logical that determines whether the legend is shown  440 #' @param legend.format list of formatting options for the legend numbers. Only applicable if \code{labels} is undefined. Parameters are:  441 #' \describe{  442 #' \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.}  443 #' \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.}  444 #' \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.}  445 #' \item{digits}{Number of digits after the decimal point if \code{format="f"}, and the number of significant digits otherwise.}  446 #' \item{big.num.abbr}{Vector that defines whether and which abbrevations are used for large numbers. It is a named numeric vector, where the name indicated the abbreviation, and the number the magnitude (in terms on numbers of zero). Numbers are only abbrevation when they are large enough. Set it to \code{NA} to disable abbrevations. The default is \code{c("mln" = 6, "bln" = 9)}. For layers where \code{style} is set to \code{log10} or \code{log10_pretty}, the default is \code{NA}.}  447 #' \item{text.separator}{Character string to use to separate numbers in the legend (default: "to").}  448 #' \item{text.less.than}{Character value(s) to use to translate "Less than". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  449 #' \item{text.or.more}{Character value(s) to use to translate "or more". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  450 #' \item{text.align}{Value that determines how the numbers are aligned, \code{"left"}, \code{"center"} or \code{"right"}}. By default \code{"left"} for legends in portrait format (\code{legend.is.protrait = TRUE}), and \code{"center"} otherwise.  451 #' \item{text.to.columns}{Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default \code{FALSE}.}  452 #' \item{...}{Other arguments passed on to \code{\link[base:formatC]{formatC}}}  453 #' }  454 #' @param legend.is.portrait logical that determines whether the legend is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  455 #' @param legend.reverse logical that determines whether the items of the legend regarding the text sizes are shown in reverse order, i.e. from bottom to top when \code{legend.is.portrait = TRUE} and from right to left when \code{legend.is.portrait = FALSE}  456 #' @param legend.hist logical that determines whether a histogram is shown  457 #' @param legend.hist.title title for the histogram. By default, one title is used for both the histogram and the normal legend.  458 #' @param legend.z index value that determines the position of the legend element with respect to other legend elements. The legend elements are stacked according to their z values. The legend element with the lowest z value is placed on top.  459 #' @param legend.hist.z index value that determines the position of the histogram legend element  460 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}).  461 #' @param auto.palette.mapping deprecated. It has been replaced by \code{midpoint} for numeric variables and \code{stretch.palette} for categorical variables.  462 #' @param max.categories deprecated. It has moved to \code{\link{tmap_options}}.  463 #' @param max.value for \code{tm_rgb}, what is the maximum value per layer? By default 255.  464 #' @param ... arguments passed on from \code{tm_raster} to \code{tm_rgb}  465 #' @name tm_raster  466 #' @rdname tm_raster  467 #' @export  468 #' @example ./examples/tm_raster.R  469 #' @seealso \href{../doc/tmap-getstarted.html}{\code{vignette("tmap-getstarted")}}  470 #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \href{https://doi.org/10.18637/jss.v084.i06}{DOI}  471 #' @return \code{\link{tmap-element}}  472 tm_raster <- function(col=NA,  473  alpha = NA,  474  palette = NULL,  475  n = 5,  476  style = ifelse(is.null(breaks), "pretty", "fixed"),  477  breaks = NULL,  478  interval.closure = "left",  479  labels = NULL,  480  midpoint = NULL,  481  stretch.palette = TRUE,  482  contrast = NA,  483  saturation = 1,  484  interpolate = NA,  485  colorNA = NULL,  486  textNA = "Missing",  487  showNA = NA,  488  colorNULL = NULL,  489  title=NA,  490  legend.show=TRUE,  491  legend.format=list(),  492  legend.is.portrait=TRUE,  493  legend.reverse=FALSE,  494  legend.hist=FALSE,  495  legend.hist.title=NA,  496  legend.z=NA,  497  legend.hist.z=NA,  498  group = NA,  499  auto.palette.mapping = NULL,  500  max.categories = NULL,  501  max.value = 255) {  502 2  midpoint <- check_deprecated_layer_fun_args(auto.palette.mapping, max.categories, midpoint)  503 2  g <- list(tm_raster=as.list(environment()))  504 2  g$tm_raster$is.RGB <- FALSE  505 2  g$tm_raster$rbg.vars <- NULL  506 2  class(g) <- "tmap"  507 2  g  508 }  509 510 #' @name tm_rgb  511 #' @rdname tm_raster  512 #' @export  513 tm_rgb <- function(r = 1, g = 2, b = 3, alpha = NA, saturation = 1, interpolate=TRUE, max.value = 255, ...) {  514 0  h <- do.call("tm_raster", c(list(alpha=alpha, saturation=saturation, interpolate=interpolate, max.value=max.value), list(...)))  515 0  h$tm_raster$is.RGB <- TRUE  516 0  h$tm_raster$rgb.vars <- c(r, g, b)  517 0  class(h) <- "tmap"  518 0  h  519 }  520 521 #' @name tm_rgba  522 #' @rdname tm_raster  523 #' @export  524 tm_rgba <- function(r = 1, g = 2, b = 3, a = 4, alpha = NA, saturation = 1, interpolate=TRUE, max.value = 255, ...) {  525 0  h <- do.call("tm_raster", c(list(alpha=alpha, saturation=saturation, interpolate=interpolate, max.value=max.value), list(...)))  526 0  h$tm_raster$is.RGB <- TRUE  527 0  h$tm_raster$rgb.vars <- c(r, g, b, a)  528 0  class(h) <- "tmap"  529 0  h  530 }  531 532 533 #' Draw symbols  534 #'  535 #' Creates a \code{\link{tmap-element}} that draws symbols, including symbols and dots. The color, size, and shape of the symbols can be mapped to data variables.  536 #'  537 #' Small multiples can be drawn in two ways: either by specifying the \code{by} argument in \code{\link{tm_facets}}, or by defining multiple variables in the aesthetic arguments, which are \code{size}, \code{col}, and \code{shape}. In the latter case, the arguments, except for the ones starting with \code{legend.}, can be specified for small multiples as follows. If the argument normally only takes a single value, such as \code{n}, then a vector of those values can be specified, one for each small multiple. If the argument normally can take a vector, such as \code{palette}, then a list of those vectors (or values) can be specified, one for each small multiple.  538 #'  539 #' A shape specification is one of the following three options. To specify multiple shapes (needed for the \code{shapes} argument), a vector or list of these shape specification is required. The shape specification options can also be mixed. For the \code{shapes} argument, it is possible to use a named vector or list, where the names correspond to the value of the variable specified by the \code{shape} argument.  540 #' \enumerate{  541 #' \item{A numeric value that specifies the plotting character of the symbol. See parameter \code{pch} of \code{\link[graphics:points]{points}} and the last example to create a plot with all options.}  542 #' \item{A \code{\link[grid:grid.grob]{grob}} object, which can be a ggplot2 plot object created with \code{\link[ggplot2:ggplotGrob]{ggplotGrob}}. To specify multiple shapes, a list of grob objects is required. See example of a proportional symbol map with ggplot2 plots}.  543 #' \item{An icon specification, which can be created with \code{\link{tmap_icons}}.}  544 #' }  545 #' For small multiples, a list of these shape specification(s) should be provided.  546 #'  547 #' @name tm_symbols  548 #' @rdname tm_symbols  549 #' @param size a single value or a \code{shp} data variable that determines the symbol sizes. The reference value \code{size=1} corresponds to the area of symbols that have the same height as one line of text. If a data variable is provided, the symbol sizes are scaled proportionally (or perceptually, see \code{perceptual}) where by default the symbol with the largest data value will get \code{size=1} (see also \code{size.max}). If multiple values are specified, small multiples are drawn (see details).  550 #' @param col color(s) of the symbol. Either a color (vector), or categorical variable name(s). If multiple values are specified, small multiples are drawn (see details).  551 #' @param shape shape(s) of the symbol. Either direct shape specification(s) or a data variable name(s) that is mapped to the symbols specified by the \code{shapes} argument. See details for the shape specification.  552 #' @param alpha transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{col} is used (normally 1).  553 #' @param border.col color of the symbol borders.  554 #' @param border.lwd line width of the symbol borders. If \code{NA}, no symbol borders are drawn.  555 #' @param border.alpha transparency number, regarding the symbol borders, between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{col} is used (normally 1).  556 #' @param scale symbol size multiplier number.  557 #' @param perceptual logical that determines whether symbols are scales with a perceptually (\code{TRUE}) or mathematically (\code{FALSE}, default value). The perceived area of larger symbols is often underestimated. Flannery (1971) experimentally derived a method to compensate this for symbols, which is enabled by this argument.  558 #' @param clustering value that determines whether the symbols are clustered in \code{"view"} mode. It does not work proportional bubbles (i.e. \code{tm_bubbles}). One of: \code{TRUE}, \code{FALSE}, or the output of \code{\link[leaflet:markerClusterOptions]{markerClusterOptions}}.  559 #' @param size.max value that is mapped to \code{size=1}. By default (\code{NA}), the maximum data value is chosen. Only applicable when \code{size} is the name of a numeric variable of \code{shp}  560 #' @param size.lim vector of two limit values of the \code{size} variable. Only symbols are drawn whose value is greater than or equal to the first value. Symbols whose values exceed the second value are drawn at the size of the second value. Only applicable when \code{size} is the name of a numeric variable of \code{shp}  561 #' @param sizes.legend vector of symbol sizes that are shown in the legend. By default, this is determined automatically.  562 #' @param sizes.legend.labels vector of labels for that correspond to \code{sizes.legend}.  563 #' @param n preferred number of color scale classes. Only applicable when \code{col} is a numeric variable name.  564 #' @param style method to process the color scale when \code{col} is a numeric variable. Discrete options are \code{"cat"}, \code{"fixed"}, \code{"sd"}, \code{"equal"}, \code{"pretty"}, \code{"quantile"}, \code{"kmeans"}, \code{"hclust"}, \code{"bclust"}, \code{"fisher"}, \code{"jenks"}, and \code{"log10_pretty"}. A numeric variable is processed as a categorical variable when using \code{"cat"}, i.e. each unique value will correspond to a distinct category. For the other discrete options (except \code{"log10_pretty"}), see the details in \code{\link[classInt:classIntervals]{classIntervals}}. Continuous options are \code{"cont"}, \code{"order"}, and \code{"log10"}. The first maps the values of \code{col} to a smooth gradient, the second maps the order of values of \code{col} to a smooth gradient, and the third uses a logarithmic transformation.  565 #' @param breaks in case \code{style=="fixed"}, breaks should be specified. The \code{breaks} argument can also be used when \code{style="cont"}. In that case, the breaks are mapped evenly to the sequential or diverging color palette.  566 #' @param interval.closure value that determines whether where the intervals are closed: \code{"left"} or \code{"right"}. Only applicable if \code{col} is a numeric variable.  567 #' @param palette a palette name or a vector of colors. See \code{tmaptools::palette_explorer()} for the named palettes. Use a \code{"-"} as prefix to reverse the palette. The default palette is taken from \code{\link{tm_layout}}'s argument \code{aes.palette}, which typically depends on the style. The type of palette from \code{aes.palette} is automatically determined, but can be overwritten: use \code{"seq"} for sequential, \code{"div"} for diverging, and \code{"cat"} for categorical.  568 #' @param labels labels of the classes  569 #' @param midpoint The value mapped to the middle color of a diverging palette. By default it is set to 0 if negative and positive values are present. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to \code{NA}, which means that the value that corresponds to the middle color class (see \code{style}) is mapped to the middle color. Only applies when \code{col} is a numeric variable. If it is specified for sequential color palettes (e.g. \code{"Blues"}), then this color palette will be treated as a diverging color palette.  570 #' @param stretch.palette Logical that determines whether the categorical color palette should be stretched if there are more categories than colors. If \code{TRUE} (default), interpolated colors are used (like a rainbow). If \code{FALSE}, the palette is repeated.  571 #' @param contrast vector of two numbers that determine the range that is used for sequential and diverging palettes (applicable when \code{auto.palette.mapping=TRUE}). Both numbers should be between 0 and 1. The first number determines where the palette begins, and the second number where it ends. For sequential palettes, 0 means the brightest color, and 1 the darkest color. For diverging palettes, 0 means the middle color, and 1 both extremes. If only one number is provided, this number is interpreted as the endpoint (with 0 taken as the start).  572 #' @param colorNA colour for missing values. Use \code{NULL} for transparency.  573 #' @param textNA text used for missing values of the color variable.  574 #' @param showNA logical that determines whether missing values are named in the legend. By default (\code{NA}), this depends on the presence of missing values.  575 #' @param colorNULL colour for polygons that are shown on the map that are out of scope  576 #' @param shapes palette of symbol shapes. Only applicable if \code{shape} is a (vector of) categorical variable(s). See details for the shape specification. By default, the filled symbols 21 to 25 are taken.  577 #' @param shapes.legend symbol shapes that are used in the legend (instead of the symbols specified with \code{shape}. Especially useful when \code{shapes} consist of grobs that have to be represented by neutrally colored shapes (see also \code{shapes.legend.fill}.  578 #' @param shapes.legend.fill Fill color of legend shapes (see \code{shapes.legend})  579 #' @param shapes.labels Legend labels for the symbol shapes  580 #' @param shapeNA the shape (a number or grob) for missing values. By default a cross (number 4). Set to \code{NA} to hide symbols for missing values.  581 #' @param shape.textNA text used for missing values of the shape variable.  582 #' @param shape.showNA logical that determines whether missing values are named in the legend. By default (\code{NA}), this depends on the presence of missing values.  583 #' @param shapes.n preferred number of shape classes. Only applicable when \code{shape} is a numeric variable name.  584 #' @param shapes.style method to process the shape scale when \code{shape} is a numeric variable. See \code{style} argument for options  585 #' @param shapes.breaks in case \code{shapes.style=="fixed"}, breaks should be specified  586 #' @param shapes.interval.closure value that determines whether where the intervals are closed: \code{"left"} or \code{"right"}. Only applicable if \code{shape} is a numeric variable.  587 #' @param legend.max.symbol.size Maximum size of the symbols that are drawn in the legend. For circles and bubbles, a value larger than one is recommended (and used for \code{tm_bubbles})  588 #' @param just justification of the symbols 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 is \code{c("center", "center")}. For icons, this value may already be speficied (see \code{\link{tmap_icons}}). The \code{just}, if specified, will overrides this.  589 #' @param jitter number that determines the amount of jittering, i.e. the random noise added to the position of the symbols. 0 means no jittering is applied, any positive number means that the random noise has a standard deviation of \code{jitter} times the height of one line of text line.  590 #' @param xmod horizontal position modification of the symbols, in terms of the height of one line of text. Either a single number for all polygons, or a numeric variable in the shape data specifying a number for each polygon. Together with \code{ymod}, it determines position modification of the symbols. See also \code{jitter} for random position modifications. In most coordinate systems (projections), the origin is located at the bottom left, so negative \code{xmod} move the symbols to the left, and negative \code{ymod} values to the bottom.  591 #' @param ymod vertical position modification. See xmod.  592 #' @param icon.scale scaling number that determines how large the icons (or grobs) are in plot mode in comparison to proportional symbols (such as bubbles). In view mode, the size is determined by the icon specification (see \code{\link{tmap_icons}}) or, if grobs are specified by \code{grob.width} and \code{grob.heigth}  593 #' @param grob.dim vector of four values that determine how grob objects (see details) are shown in view mode. The first and second value are the width and height of the displayed icon. The third and fourth value are the width and height of the rendered png image that is used for the icon. Generally, the third and fourth value should be large enough to render a ggplot2 graphic successfully. Only needed for the view mode.  594 #' @param title.size title of the legend element regarding the symbol sizes  595 #' @param title.col title of the legend element regarding the symbol colors  596 #' @param title.shape title of the legend element regarding the symbol shapes  597 #' @param legend.size.show logical that determines whether the legend for the symbol sizes is shown  598 #' @param legend.col.show logical that determines whether the legend for the symbol colors is shown  599 #' @param legend.shape.show logical that determines whether the legend for the symbol shapes is shown  600 #' @param legend.format list of formatting options for the legend numbers. Only applicable if \code{labels} is undefined. Parameters are:  601 #' \describe{  602 #' \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.}  603 #' \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.}  604 #' \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.}  605 #' \item{digits}{Number of digits after the decimal point if \code{format="f"}, and the number of significant digits otherwise.}  606 #' \item{big.num.abbr}{Vector that defines whether and which abbrevations are used for large numbers. It is a named numeric vector, where the name indicated the abbreviation, and the number the magnitude (in terms on numbers of zero). Numbers are only abbrevation when they are large enough. Set it to \code{NA} to disable abbrevations. The default is \code{c("mln" = 6, "bln" = 9)}. For layers where \code{style} is set to \code{log10} or \code{log10_pretty}, the default is \code{NA}.}  607 #' \item{text.separator}{Character string to use to separate numbers in the legend (default: "to").}  608 #' \item{text.less.than}{Character value(s) to use to translate "Less than". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  609 #' \item{text.or.more}{Character value(s) to use to translate "or more". When a character vector of length 2 is specified, one for each word, these words are aligned when \code{text.to.columns = TRUE}}  610 #' \item{text.align}{Value that determines how the numbers are aligned, \code{"left"}, \code{"center"} or \code{"right"}}. By default \code{"left"} for legends in portrait format (\code{legend.is.protrait = TRUE}), and \code{"center"} otherwise.  611 #' \item{text.to.columns}{Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default \code{FALSE}.}  612 #' \item{...}{Other arguments passed on to \code{\link[base:formatC]{formatC}}}  613 #' }  614 #' @param legend.size.is.portrait logical that determines whether the legend element regarding the symbol sizes is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  615 #' @param legend.col.is.portrait logical that determines whether the legend element regarding the symbol colors is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  616 #' @param legend.shape.is.portrait logical that determines whether the legend element regarding the symbol shapes is in portrait mode (\code{TRUE}) or landscape (\code{FALSE})  617 #' @param legend.size.reverse logical that determines whether the items of the legend regarding the symbol sizes are shown in reverse order, i.e. from bottom to top when \code{legend.size.is.portrait = TRUE} and from right to left when \code{legend.size.is.portrait = FALSE}  618 #' @param legend.col.reverse logical that determines whether the items of the legend regarding the symbol colors are shown in reverse order, i.e. from bottom to top when \code{legend.col.is.portrait = TRUE} and from right to left when \code{legend.col.is.portrait = FALSE}  619 #' @param legend.shape.reverse logical that determines whether the items of the legend regarding the symbol shapes are shown in reverse order, i.e. from bottom to top when \code{legend.shape.is.portrait = TRUE} and from right to left when \code{legend.shape.is.portrait = FALSE}  620 #' @param legend.hist logical that determines whether a histogram is shown regarding the symbol colors  621 #' @param legend.hist.title title for the histogram. By default, one title is used for both the histogram and the normal legend for symbol colors.  622 #' @param legend.size.z index value that determines the position of the legend element regarding the symbol sizes with respect to other legend elements. The legend elements are stacked according to their z values. The legend element with the lowest z value is placed on top.  623 #' @param legend.col.z index value that determines the position of the legend element regarding the symbol colors. (See \code{legend.size.z})  624 #' @param legend.shape.z index value that determines the position of the legend element regarding the symbol shapes. (See \code{legend.size.z})  625 #' @param legend.hist.z index value that determines the position of the histogram legend element. (See \code{legend.size.z})  626 #' @param id name of the data variable that specifies the indices of the symbols. Only used for \code{"view"} mode (see \code{\link{tmap_mode}}).  627 #' @param popup.vars names of data variables that are shown in the popups in \code{"view"} mode. If \code{NA} (default), only aesthetic variables (i.e. specified by \code{col} and \code{lwd}) are shown). If they are not specified, all variables are shown. Set popup.vars to \code{FALSE} to disable popups. When a vector of variable names is provided, the names (if specified) are printed in the popups.  628 #' @param 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.  629 #' @param title shortcut for \code{title.col} for \code{tm_dots}  630 #' @param legend.show shortcut for \code{legend.col.show} for \code{tm_dots}  631 #' @param legend.is.portrait shortcut for \code{legend.col.is.portrait} for \code{tm_dots}  632 #' @param legend.z shortcut for \code{legend.col.z shortcut} for \code{tm_dots}  633 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}).  634 #' @param auto.palette.mapping deprecated. It has been replaced by \code{midpoint} for numeric variables and \code{stretch.palette} for categorical variables.  635 #' @param max.categories deprecated. It has moved to \code{\link{tmap_options}}.  636 #' @keywords symbol map  637 #' @export  638 #' @example ./examples/tm_symbols.R  639 #' @references Flannery J (1971). The Relative Effectiveness of Some Common Graduated Point Symbols in the Presentation of Quantitative Data. Canadian Cartographer, 8(2), 96-109.  640 #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \href{https://doi.org/10.18637/jss.v084.i06}{DOI}  641 #' @seealso \href{../doc/tmap-getstarted.html}{\code{vignette("tmap-getstarted")}}  642 #' @return \code{\link{tmap-element}}  643 tm_symbols <- function(size=1, col=NA,  644  shape=21,  645  alpha=NA,  646  border.col=NA,  647  border.lwd=1,  648  border.alpha=NA,  649  scale=1,  650  perceptual=FALSE,  651  clustering=FALSE,  652  size.max=NA,  653  size.lim=NA,  654  sizes.legend = NULL,  655  sizes.legend.labels = NULL,  656  n = 5, style = ifelse(is.null(breaks), "pretty", "fixed"),  657  breaks = NULL,  658  interval.closure = "left",  659  palette = NULL,  660  labels = NULL,  661  midpoint = NULL,  662  stretch.palette = TRUE,  663  contrast = NA,  664  colorNA = NA,  665  textNA = "Missing",  666  showNA = NA,  667  colorNULL = NA,  668  shapes = 21:25,  669  shapes.legend = NULL,  670  shapes.legend.fill = NA,  671  shapes.labels = NULL,  672  shapeNA = 4,  673  shape.textNA = "Missing",  674  shape.showNA = NA,  675  shapes.n = 5, shapes.style = ifelse(is.null(shapes.breaks), "pretty", "fixed"),  676  shapes.breaks = NULL,  677  shapes.interval.closure = "left",  678  legend.max.symbol.size = .8,  679  just=NA,  680  jitter=0,  681  xmod = 0,  682  ymod = 0,  683  icon.scale = 3,  684  grob.dim = c(width=48, height=48, render.width=256, render.height=256),  685  title.size = NA,  686  title.col = NA,  687  title.shape=NA,  688  legend.size.show=TRUE,  689  legend.col.show=TRUE,  690  legend.shape.show=TRUE,  691  legend.format=list(),  692  legend.size.is.portrait=FALSE,  693  legend.col.is.portrait=TRUE,  694  legend.shape.is.portrait=TRUE,  695  legend.size.reverse=FALSE,  696  legend.col.reverse=FALSE,  697  legend.shape.reverse=FALSE,  698  legend.hist=FALSE,  699  legend.hist.title=NA,  700  legend.size.z=NA,  701  legend.col.z=NA,  702  legend.shape.z=NA,  703  legend.hist.z=NA,  704  id=NA,  705  popup.vars=NA,  706  popup.format=list(),  707  group = NA,  708  auto.palette.mapping = NULL,  709  max.categories = NULL) {  710 2  midpoint <- check_deprecated_layer_fun_args(auto.palette.mapping, max.categories, midpoint)  711 2  g <- list(tm_symbols=c(as.list(environment()), list(are.dots=FALSE, are.markers=FALSE, call=names(match.call(expand.dots = TRUE)[-1]))))  712 2  class(g) <- "tmap"  713 2  g  714   715 }  716 717 #' @rdname tm_symbols  718 #' @export  719 tm_squares <- function(size=1,  720  col=NA,  721  shape=22,  722  scale=4/3,  723  ...) {  724 0  g <- do.call("tm_symbols", c(list(size=size, col=col, shape=shape, scale=scale), list(...)))  725 0  g  726 }  727 728 #' @rdname tm_symbols  729 #' @export  730 tm_bubbles <- function(size=1,  731  col=NA,  732  shape=21,  733  scale=4/3,  734  legend.max.symbol.size=1,  735  ...) {  736 2  g <- do.call("tm_symbols", c(list(size=size, col=col, shape=shape, scale=scale, legend.max.symbol.size=legend.max.symbol.size), list(...)))  737 2  g  738 }  739 740 741 742 #' @rdname tm_symbols  743 #' @export  744 tm_dots <- function(col=NA,  745  size=.02,  746  shape=16,  747  title = NA,  748  legend.show=TRUE,  749  legend.is.portrait=TRUE,  750  legend.z=NA, ...) {  751 0  g <- do.call("tm_symbols", c(list(size=size, col=col, shape=shape,  752 0  title.col=title,  753 0  legend.col.show=legend.show,  754 0  legend.col.is.portrait=legend.is.portrait,  755 0  legend.col.z=legend.z), list(...)))  756 0  g$tm_symbols$are.dots <- TRUE  757 0  g  758 }  759 760 761 #' @rdname tm_symbols  762 #' @param text text of the markers. Shown in plot mode, and as popup text in view mode.  763 #' @param text.just justification of marker text (see \code{just} argument of \code{\link{tm_text}}). Only applicable in plot mode.  764 #' @param markers.on.top.of.text For \code{tm_markers}, should the markers be drawn on top of the text labels?  765 #' @param ... arguments passed on to \code{tm_symbols}. For \code{tm_markers}, arguments can also be passed on to \code{tm_text}. In that case, they have to be prefixed with \code{text.}, e.g. the \code{col} argument should be names \code{text.col}  766 #' @export  767 tm_markers <- function(shape=marker_icon(),  768  col=NA,  769  border.col=NULL,  770  clustering=TRUE,  771  text=NULL,  772  text.just="top",  773  markers.on.top.of.text=TRUE,  774  group = NA,  775  ...) {  776 0  args <- list(...)  777 0  argsS <- args[intersect(names(formals("tm_symbols")), names(args))]  778 779  # all text label items are preceeded with "text."  780 0  argsT <- args[intersect(paste("text", names(formals("tm_text")), sep="."), names(args))]  781 0  argsT[c("text.text", "text.text.just")] <- NULL # already explicit arguments  782 0  argsT_names <- names(argsT)  783   784 0  names(argsT) <- substr(argsT_names, 6, nchar(argsT_names))  785   786 0  if (is.null(text)) {  787 0  tmT <- NULL  788 0  } else {  789 0  tmT <- do.call("tm_text", c(list(text=text, just=text.just, clustering = clustering), argsT))  790 0  }  791   792 0  tmS <- do.call("tm_symbols", c(list(shape=shape, col=col, border.col=border.col, clustering = clustering), argsS))  793   794 0  g <- if (markers.on.top.of.text) {  795 0  tmS + tmT  796 0  } else {  797 0  tmT + tmS  798 0  }  799 0  g$tm_symbols$are.markers <- TRUE  800 0  g  801 }  802 803 #' Draw simple features  804 #'  805 #' Creates a \code{\link{tmap-element}} that draws simple features. Basically, it is a stack of \code{\link{tm_polygons}}, \code{\link{tm_lines}} and \code{\link{tm_dots}}. In other words, polygons are plotted as polygons, lines as lines and points as dots.  806 807 #' @param col color of the simple features. See the \code{col} argument of \code{\link{tm_polygons}}, \code{\link{tm_lines}} and \code{\link{tm_symbols}}.  808 #' @param size size of the dots. See the \code{size} argument \code{\link{tm_symbols}}. By default, the size is similar to dot size (see \code{\link{tm_dots}})  809 #' @param shape shape of the dots. See the \code{shape} argument \code{\link{tm_symbols}}. By default, dots are shown.  810 #' @param lwd width of the lines. See the \code{lwd} argument of \code{\link{tm_lines}}  811 #' @param lty type of the lines. See the \code{lty} argument of \code{\link{tm_lines}}  812 #' @param alpha transparency number. See \code{alpha} argument of \code{\link{tm_polygons}}, \code{\link{tm_lines}} and \code{\link{tm_symbols}}  813 #' @param palette palette. See \code{palette} argument of \code{\link{tm_polygons}}, \code{\link{tm_lines}} and \code{\link{tm_symbols}}  814 #' @param border.col color of the borders. See \code{border.col} argument of \code{\link{tm_polygons}} and \code{\link{tm_symbols}}.  815 #' @param border.lwd line width of the borders. See \code{border.lwd} argument of \code{\link{tm_polygons}} and \code{\link{tm_symbols}}.  816 #' @param border.lty line type of the borders. See \code{border.lwd} argument of \code{\link{tm_polygons}} and \code{\link{tm_symbols}}.  817 #' @param border.alpha transparency of the borders. See \code{border.alpha} argument of \code{\link{tm_polygons}} and \code{\link{tm_symbols}}.  818 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}).  819 #' @param ... other arguments passed on to \code{\link{tm_polygons}}, \code{\link{tm_lines}} and \code{\link{tm_symbols}}  820 #' @keywords simple features  821 #' @export  822 #' @example ./examples/tm_sf.R  823 #' @seealso \href{../doc/tmap-getstarted.html}{\code{vignette("tmap-getstarted")}}  824 #' @return \code{\link{tmap-element}}  825 tm_sf <- function(col=NA, size=.02, shape = 16, lwd=1, lty = "solid", alpha=NA, palette=NULL, border.col=NA, border.lwd=1, border.lty = "solid", border.alpha=NA, group = NA, ...) {  826 2  args <- list(...)  827   828 2  argsFill <- c(list(col = col, alpha = alpha, palette = palette), args[intersect(names(args), names(formals("tm_fill")))])  829 2  argsBorders <- c(list(col = border.col, alpha = border.alpha, lty = border.lty))  830 2  argsLines <- c(list(col = col, lwd = lwd, lty = lty, alpha = alpha, palette = palette), args[intersect(names(args), names(formals("tm_lines")))])  831 2  argsSymbols <- c(list(col = col, size = size, shape = shape, alpha = alpha, palette = palette, border.col = border.col, border.lwd = border.lwd, border.alpha = border.alpha), args[intersect(names(args), names(formals("tm_symbols")))])  832   833 2  g <- do.call("tm_fill", argsFill) + do.call("tm_borders", argsBorders) + do.call("tm_lines", argsLines) + do.call("tm_symbols", argsSymbols)  834   835 2  called_names <- names(match.call(expand.dots = TRUE)[-1])  836   837   838   839 2  g$tm_fill$call <- called_names  840 2  g$tm_fill$from_tm_sf <- TRUE  841   842 2  g$tm_lines$call <- called_names  843 2  g$tm_symbols$call <- called_names  844 845 2  g  846 }  847 848 #' @rdname tm_tiles  849 #' @export  850 tm_basemap <- function(server=NA, group = NA, alpha = NA) {  851 2  g <- list(tm_basemap=c(as.list(environment()), list(grouptype = "base")))  852 2  class(g) <- "tmap"  853 2  g  854 }  855 856 #' Draw a tile layer  857 #'  858 #' Creates a \code{\link{tmap-element}} that draws a tile layer. This feature is only available in view mode. For plot mode, a tile image can be retrieved by \code{\link[tmaptools:read_osm]{read_osm}}. The function \code{tm_basemap} draws the tile layer as basemap (i.e. as bottom layer), whereas \code{tm_tiles} draws the tile layer as overlay layer (where the stacking order corresponds to the order in which this layer is called). Note that basemaps are shown by default (see details).  859 #'  860 #' When \code{tm_basemap} is not specified, the default basemaps are shown, which can be configured by the \code{basemaps} arugument in \code{\link{tmap_options}}. By default (for style \code{"white"}) three basemaps are drawn: \code{c("Esri.WorldGrayCanvas", "OpenStreetMap", "Esri.WorldTopoMap")}. To disable basemaps, add \code{tm_basemap(NULL)} to the plot, or set \code{tmap_options(basemaps = NULL)}. Similarly, when \code{tm_tiles} is not specified, the overlay maps specified by the \code{overlays} argument in in \code{\link{tmap_options}} are shown as front layer. By default, this argument is set to \code{NULL}, so no overlay maps are shown by default. See examples.  861 #'  862 #' @param server name of the provider or an URL. The list of available providers can be obtained with \code{leaflet::providers}. See \url{http://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{"http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"}. Use \code{NULL} in \code{tm_basemap} to disable the basemaps.  863 #' @param group name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set \code{group = NULL} to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in \code{\link{tm_shape}}). Tile layers generated with \code{tm_basemap} will be base groups whereas tile layers generated with \code{tm_tiles} will be overlay groups.  864 #' @param alpha alpha  865 #' @export  866 #' @rdname tm_tiles  867 #' @name tm_tiles  868 #' @example ./examples/tm_tiles.R  869 tm_tiles <- function(server, group = NA, alpha = 1) {  870 2  if (missing(server)) stop("Please specify server (name or url)")  871 2  g <- list(tm_tiles=c(as.list(environment()), list(grouptype = "overlay")))  872 2  class(g) <- "tmap"  873 2  g  874 } 

Read our documentation on viewing source code .