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 .

Loading