% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tm_layers_circles.R
\name{tm_circles}
\alias{tm_circles}
\alias{opt_tm_circles}
\title{Map layer: geographic circles}
\usage{
tm_circles(
  size = tm_const(),
  size.scale = tm_scale(),
  size.legend = tm_legend(),
  size.chart = tm_chart_none(),
  size.free = NA,
  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,
  plot.order = tm_plot_order("size"),
  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_circles(),
  ...
)

opt_tm_circles(
  points_only = "ifany",
  point_per = "feature",
  on_surface = FALSE
)
}
\arguments{
\item{size, size.scale, size.legend, size.chart, size.free}{Visual variable that determines the size. See details. \emph{Unit:} Meters. Accepts a plain numeric vector (values already in meters) or a \code{units} object from the \strong{units} package (any linear unit, e.g. \code{units::as_units(50, "km")}), which is converted to meters automatically.
\emph{Unit:} Meters. Accepts a plain numeric vector (values already in meters) or a \code{units} object from the \strong{units} package (any linear unit, e.g. \code{units::as_units(50, "km")}), which is converted to meters automatically.}

\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.legend, fill_alpha.chart, 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{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 \code{\link[=opt_tm_circles]{opt_tm_circles()}}.}

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

\item{points_only}{Should only point geometries of the shape object be
plotted? Default \code{"ifany"} means \code{TRUE} whenever the geometry collection
contains points.}

\item{point_per}{How spatial points are generated for non-point geometries.
One of \code{"feature"} (one point per feature, default), \code{"segment"} (one per
sub-feature), or \code{"largest"} (only the largest sub-feature).}

\item{on_surface}{For polygon inputs, should the centroid be guaranteed to
lie on the surface? If \code{TRUE} (slower), centroids outside the polygon are
replaced via \code{\link[sf:st_point_on_surface]{sf::st_point_on_surface()}}.}
}
\description{
Map layer that draws circles with geographically fixed radii — i.e. the
radius is expressed in meters and the circles scale with zoom in interactive
(view) mode. This is in contrast to \code{\link[=tm_bubbles]{tm_bubbles()}}, where the symbol size
is a fixed number of screen pixels.
}
\details{
Supported visual variables: \code{fill} (fill colour), \code{col} (border colour),
\code{size} (radius in meters), \code{lwd} (line width), \code{lty} (line type),
\code{fill_alpha} (fill transparency), \code{col_alpha} (border transparency).
}
\examples{
## Three concentric layers of geographic circles at different administrative
## levels, each with a fixed radius that corresponds to a real-world distance.
## Because the radius is in meters the circles scale with zoom in view mode.
tm_shape(NLD_prov) +
	tm_circles(size = 5000, fill = "#0033ff", col = NULL) +
tm_shape(NLD_muni) +
	tm_circles(size = 2000, fill = "#99dd99", col = NULL) +
tm_shape(NLD_dist) +
	tm_circles(size = 1000, fill = "#ff8833", col = NULL)

## Use a units object — any linear unit is accepted and converted to meters
NLD_prov$one_mile <- units::as_units(1:12, "mi")
tm_shape(NLD_prov) +
	tm_circles(size = "one_mile", size.scale = tm_scale_asis())
}
\seealso{
\itemize{
\item \code{\link[=tm_bubbles]{tm_bubbles()}} for screen-fixed proportional circles (pixel radius).
\item \code{\link[=tm_symbols]{tm_symbols()}} for the general symbol layer with configurable shapes.
\item \code{\link[=tm_scale_asis]{tm_scale_asis()}} to pass data values directly as metre radii.
}
}
