% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tm_layers_polygons.R
\name{tm_polygons}
\alias{tm_polygons}
\alias{tm_fill}
\alias{tm_borders}
\alias{opt_tm_polygons}
\title{Map layer: polygons}
\usage{
tm_polygons(
  fill = tm_const(),
  fill.scale = tm_scale(),
  fill.legend = tm_legend(),
  fill.chart = tm_chart_none(),
  fill.free = NA,
  col = tm_const(),
  col.scale = tm_scale(),
  col.legend = tm_legend(),
  col.chart = tm_chart_none(),
  col.free = NA,
  lwd = tm_const(),
  lwd.scale = tm_scale(),
  lwd.legend = tm_legend(),
  lwd.chart = tm_chart_none(),
  lwd.free = NA,
  lty = tm_const(),
  lty.scale = tm_scale(),
  lty.legend = tm_legend(),
  lty.chart = tm_chart_none(),
  lty.free = NA,
  fill_alpha = tm_const(),
  fill_alpha.scale = tm_scale(),
  fill_alpha.legend = tm_legend(),
  fill_alpha.chart = tm_chart_none(),
  fill_alpha.free = NA,
  col_alpha = tm_const(),
  col_alpha.scale = tm_scale(),
  col_alpha.legend = tm_legend(),
  col_alpha.chart = tm_chart_none(),
  col_alpha.free = NA,
  linejoin = "round",
  lineend = "round",
  plot.order = tm_plot_order("lwd", reverse = TRUE, na.order = "bottom"),
  zindex = NA,
  group = NA,
  group.control = "check",
  popup = tm_popup(),
  popup.vars = NA,
  popup.format = tm_label_format(),
  hover = NA,
  id = "",
  blend = "over",
  options = opt_tm_polygons(),
  ...
)

tm_fill(...)

tm_borders(col = tm_const(), ...)

opt_tm_polygons(polygons.only = "ifany")
}
\arguments{
\item{fill, fill.scale, fill.legend, fill.chart, fill.free}{Visual variable that determines the fill color. See details. \emph{Unit:} Color -- a color name, hex string.}

\item{col, col.scale, col.legend, col.chart, col.free}{Visual variable that determines the color. See details. \emph{Unit:} Color -- a color name, hex string.}

\item{lwd, lwd.scale, lwd.legend, lwd.chart, lwd.free}{Visual variable that determines the line width. See details. \emph{Unit:} Base R line-width units; 1 lwd is approx. 0.75 pt at 96 dpi.}

\item{lty, lty.scale, lty.legend, lty.chart, lty.free}{Visual variable that determines the line type. See details. \emph{Unit:} Integer (1-6) or name: "solid", "dashed", "dotted", "dotdash", "longdash", "twodash".}

\item{fill_alpha, fill_alpha.scale, fill_alpha.chart, fill_alpha.legend, fill_alpha.free}{Visual variable that determines the fill color transparency. See details. \emph{Unit:} Proportion -- numeric 0-1 (0 = fully transparent, 1 = fully opaque).}

\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.chart, col_alpha.free}{Visual variable that determines the color transparency. See details. \emph{Unit:} Proportion -- numeric 0-1 (0 = fully transparent, 1 = fully opaque).}

\item{linejoin, lineend}{Line join and line end. See \link[grid:gpar]{gpar()} for details.}

\item{plot.order}{Specification in which order the spatial features are drawn.
See \code{\link[=tm_plot_order]{tm_plot_order()}} for details.}

\item{zindex}{Controls the stacking order of map layers. Should be set to a
value above 400. By default, layers are stacked in call order, starting
at 401. See details.}

\item{group}{Name of the group to which this layer belongs. This is only
relevant in view mode, where layer groups can be switched (see \code{group.control})}

\item{group.control}{In view mode, the group control determines how layer groups
can be switched on and off. Options: \code{"radio"} for radio buttons
(meaning only one group can be shown), \code{"check"} for check boxes
(so multiple groups can be shown), and \code{"none"} for no control
(the group cannot be (de)selected).}

\item{popup}{popup specification for \code{"view"} mode, the output of \code{\link[=tm_popup]{tm_popup()}}.
It determines the data variables shown in the popup table, the popup title,
and (in the future) the popup layout. This replaces the deprecated
arguments \code{popup.vars} and \code{popup.format}.}

\item{popup.vars}{(Deprecated.) Use \code{popup} with
\code{\link[=tm_popup]{tm_popup()}} instead (via its \code{vars} argument). Names of data variables that
are shown in the popups in \code{"view"} mode. Set \code{popup.vars} to \code{TRUE} to show
all variables in the shape object. Set \code{popup.vars} to \code{FALSE} to disable
popups. Set \code{popup.vars} to a character vector of variable names to show
those variables in the popups. The default (\code{NA}) depends on whether visual
variables (e.g. \code{fill}) are used. If so, only those are shown. If not, all
variables in the shape object are shown.}

\item{popup.format}{(Deprecated.) Use \code{popup} with
\code{\link[=tm_popup]{tm_popup()}} instead (via its \code{format} argument). List of formatting options
for the popup values. Output of \code{\link[=tm_label_format]{tm_label_format()}}. Only applicable for
numeric data variables. If one list of formatting options is provided,
it is applied to all numeric variables of \code{popup.vars}. Also, a (named)
list of lists can be provided. In that case, each list of formatting options
is applied to the named variable.}

\item{hover}{name of the data variable that specifies the hover labels (view mode only). Set to \code{FALSE} to disable hover labels. By default \code{FALSE}, unless \code{id} is specified. In that case, it is set to \code{id},}

\item{id}{name of the data variable that specifies the indices of the spatial
features. Only used for \code{"view"} mode.}

\item{blend}{Compositing operator for layer blending. Default \code{"over"} applies
no blending. See the "Layer blending" section for the supported values.}

\item{options}{options passed on to the corresponding \verb{opt_<layer_function>} function}

\item{...}{to catch deprecated arguments from version < 4.0}

\item{polygons.only}{should only polygon geometries of the shape object (defined in \code{\link[=tm_shape]{tm_shape()}}) be plotted? By default \code{"ifany"}, which means \code{TRUE} in case a geometry collection is specified.}
}
\description{
Map layer that draws polygons. Supported visual variables are: \code{fill} (the fill color),
\code{col} (the border color), \code{lwd} (line width), \code{lty} (line type),
\code{fill_alpha} (fill color alpha transparency) and \code{col_alpha} (border color alpha transparency).
}
\details{
The visual variable arguments (e.g. \code{col}) can be specified with a data
variable name (e.g., a spatial vector attribute or a raster layer of the object
specified in \code{\link[=tm_shape]{tm_shape()}}), with a visual value (for \code{col}, a color is expected), or with a geometry-derived variable (see below).
See vignette: \href{https://r-tmap.github.io/tmap/articles/basics_vv}{Visual variables}.

Multiple values can be specified: in that case facets are created.
These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}.
See vignette: \href{https://r-tmap.github.io/tmap/articles/basics_facets}{Facets}.
\itemize{
\item The \verb{*.scale} arguments determine the used scale to map the data values to
visual variable values. These can be specified with one of the available
\verb{tm_scale_*()} functions. The default is specified by the tmap option (\code{\link[=tm_options]{tm_options()}}) \code{scales.var}.
See `rvignette: \href{https://r-tmap.github.io/tmap/articles/basics_scales}{Scales}
\item The \verb{*.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}.
The default legend and its settings are determined by the tmap options (\code{\link[=tm_options]{tm_options()}}) \code{legend.} .
See `rvignette: \href{https://r-tmap.github.io/tmap/articles/basics_legends}{Legends}
\item The \verb{*.chart} arguments specify additional charts, specified with \code{tm_chart_}, e.g. \code{\link[=tm_chart_histogram]{tm_chart_histogram()}}.
See `rvignette: \href{https://r-tmap.github.io/tmap/articles/basics_charts}{Charts}
\item The \verb{*.free} arguments determine whether scales are applied freely across facets, or shared.
A logical value is required. They can also be specified with a vector of three
logical values; these determine whether scales are applied freely per facet dimension.
This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}).
There are maximally three facet dimensions: rows, columns, and pages. This only
applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)}
means that for the visual variable \code{col}, each row of facets will have its own
scale, and therefore its own legend. For facet wraps and stacks
(\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension,
so the \verb{*.free} argument requires only one logical value.
}

Currently, three geometry-derived variables are implemented:
\itemize{
\item \code{"AREA"} (polygons only), which uses the feature area;
\item \code{"LENGTH"} (lines only), which uses the feature length; and
\item \code{"MAP_COLORS"}, which assigns values so that adjacent features receive
different values, making it particularly suitable for coloring
neighbouring polygons.
}

Note that geometry-derived variables do not generate a legend automatically.
If a legend is required, compute the corresponding variable explicitly,
for example with \code{\link[sf:st_area]{sf::st_area()}}, \code{\link[sf:st_length]{sf::st_length()}}, or
\code{\link[tmaptools:map_coloring]{tmaptools::map_coloring()}}, and use the resulting values instead.
\subsection{Visual variable units}{

Every visual variable maps data values to a specific output unit.
Knowing the unit matters when supplying constant values via \code{\link[=tm_const]{tm_const()}},
or output ranges via \code{values.range} / \code{values.scale} in the scale
functions.\tabular{lll}{
   Variable \tab Output unit \tab Notes \cr
   \code{fill}, \code{col}, \code{bgcol} \tab color \tab name, hex, or palette string \cr
   \code{fill_alpha}, \code{col_alpha}, \code{bgcol_alpha} \tab proportion 0-1 \tab 0 = transparent, 1 = opaque \cr
   \code{size} (symbols, bubbles, squares, dots) \tab typographic lines \tab 1 line approx. 1/6 inch; scaled by \code{values.scale} \cr
   \code{size} (circles) \tab meters \tab plain numeric or a \code{units} object \cr
   \code{size} (text, labels) \tab multiplier \tab 1 = 12 pt (plot) / 12 px (view) \cr
   \code{lwd} \tab lwd \tab base R units; 1 lwd approx. 0.75 pt at 96 dpi \cr
   \code{lty} \tab -- \tab integer 1-6 or name ("solid", "dashed", ...) \cr
   \code{shape} \tab -- \tab integer \code{pch} 1-25 or single character \cr
   \code{angle} \tab degrees \tab 0-360, clockwise from north \cr
   \code{fontface} \tab -- \tab "plain", "bold", "italic", "bold.italic" \cr
}

\subsection{Symbol size (\code{size} in \code{tm_symbols}, \code{tm_bubbles}, \code{tm_squares}, \code{tm_dots})}{

"Lines" is a typographic unit: one line is approximately 1/6 inch (the
default base line-height in R graphics). The global multiplier
\code{tmap_options(values.scale = list(size.bubbles = 1.5))} scales all symbol
sizes without changing the data mapping.
}

\subsection{Circle size (\code{size} in \code{tm_circles})}{

The value is a geographic radius in meters. A plain numeric vector is
interpreted as meters; a \code{units} object (from the \strong{units} package) is
automatically converted, so \code{units::as_units(1, "mi")} gives a 1-mile
radius. Because the radius is geographic, circles scale with zoom in
interactive (view) mode -- unlike bubble symbols which keep a fixed screen
size.
}

\subsection{Text size (\code{size} in \code{tm_text}, \code{tm_labels})}{

The value is a multiplier of the base font size. \code{size = 1} renders at
12 pt in plot mode (R's default \code{par("ps")}) and at 12 px in view
mode (\code{gp$cex * 12} px, see \code{tmapLeafletDataPlot.tm_data_text}); the two
modes are consistent by design.
}

}

\subsection{Layer blending (\code{blend})}{

Blend modes control how a layer's pixels are combined with the pixels
beneath it. For each pixel, let \eqn{S} be the source (top layer) RGB
value and \eqn{D} be the destination (bottom layer) RGB value, both
normalised to \eqn{[0, 1]}.\tabular{lll}{
   \code{blend} \tab Formula \tab Use case \cr
   \code{"over"} \tab \eqn{S \cdot \alpha + D \cdot (1 - \alpha)} \tab Standard alpha compositing (default) \cr
   \code{"multiply"} \tab \eqn{S \times D} \tab Hillshading over colour raster; both layers darken each other \cr
   \code{"screen"} \tab \eqn{1 - (1 - S)(1 - D)} \tab Inverse of multiply; brightens \cr
   \code{"overlay"} \tab multiply if \eqn{D < 0.5}, screen if \eqn{D \geq 0.5} \tab Boosts contrast; preserves midtones \cr
   \code{"darken"} \tab \eqn{\min(S, D)} \tab Keeps the darker of the two layers per channel \cr
   \code{"lighten"} \tab \eqn{\max(S, D)} \tab Keeps the lighter of the two layers per channel \cr
}


Requires R >= 4.2 and a compatible graphics device (e.g.
\code{png(type = "cairo")}, \code{svg()}). In view mode, blending is applied via
CSS \code{mix-blend-mode}. See \code{\link[grid:groupGrob]{grid::groupGrob()}} for the full list of
supported operators.
}

\subsection{zindex and pane names}{

In view mode, each layer is rendered in a Leaflet pane named \code{"tmap{zindex}"}
(e.g., \code{"tmap401"}, \code{"tmap402"}), with base tile layers placed in the
standard \code{"tile"} pane.
}
}
\examples{
# load Africa country data
data(World)
Africa = World[World$continent == "Africa", ]
Africa_border = sf::st_make_valid(sf::st_union(sf::st_buffer(Africa, 0.001))) # slow and ugly

# without specifications
tm_shape(Africa_border) + tm_polygons()
tm_shape(Africa_border) + tm_fill()
tm_shape(Africa_border) + tm_borders()

# specification with visual variable values
tm_shape(Africa) +
  tm_polygons(fill = "limegreen", col = "purple", lwd = 2, lty = "solid", col_alpha = 0.3) +
  tm_text("name", options = opt_tm_text(remove_overlap = TRUE)) +
tm_shape(Africa_border) +
  tm_borders("darkred", lwd = 3)

# specification with a data variable
tm_shape(Africa) +
  tm_polygons(fill = "income_grp", fill.scale = tm_scale_categorical(values = "-tol.muted"))


# continuous color scale with landscape legend
tm_shape(Africa) +
  tm_polygons(fill = "inequality",
    fill.scale = tm_scale_continuous(values = "-scico.roma"),
    fill.legend = tm_legend(
    	title = "", orientation = "landscape",
    	position = tm_pos_out("center", "bottom"), frame = FALSE
    	)) +
tm_shape(Africa_border) +
	tm_borders(lwd = 2) +
tm_title("Inequality index", position = tm_pos_in("right", "TOP"), frame = FALSE) +
tm_layout(frame = FALSE)

# bivariate scale
tm_shape(World) +
	tm_polygons(tm_vars(c("inequality", "well_being"), multivariate = TRUE))
}
\seealso{
\href{https://r-tmap.github.io/tmap/articles/basics_vv}{Visual variables}, \href{https://r-tmap.github.io/tmap/articles/basics_scales}{Scales}, \href{https://r-tmap.github.io/tmap/articles/basics_legends}{Legends}, \href{https://r-tmap.github.io/tmap/articles/basics_facets}{Facets}, \href{https://r-tmap.github.io/tmap/articles/foundations_units}{Units}, \href{https://r-tmap.github.io/tmap/articles/adv_blend}{Layer blending}, \href{https://r-tmap.github.io/tmap/articles/examples_choro_World}{Choropleth (World)}, \href{https://r-tmap.github.io/tmap/articles/examples_choro_NLD}{Choropleth (Netherlands)}, \href{https://r-tmap.github.io/tmap/articles/examples_biv_choro}{Bivariate choropleth}, \href{https://r-tmap.github.io/tmap/articles/examples_gridmaps}{Gridmap}
}
