% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/leg.R
\name{leg}
\alias{leg}
\title{Plot a single map legend}
\usage{
leg(
  type,
  val,
  pos = "left",
  pal = "Inferno",
  alpha = NULL,
  col = "tomato4",
  inches = 0.3,
  val_max = NULL,
  symbol = "circle",
  self_adjust = FALSE,
  lwd = 0.7,
  border = "#333333",
  pch = seq_along(val),
  cex = rep(1, length(val)),
  title = "Legend Title",
  title_cex = 0.8 * size,
  val_cex = 0.6 * size,
  val_rnd = 0,
  val_dec = ".",
  val_big = "",
  col_na = "white",
  cex_na = 1,
  pch_na = 4,
  no_data = FALSE,
  no_data_txt = "No Data",
  box_border = "#333333",
  box_cex = c(1, 1),
  horiz = FALSE,
  frame_border = fg,
  frame = FALSE,
  bg = "#f7f7f7",
  fg = "#333333",
  size = 1,
  return_bbox = FALSE,
  mar = par("mar"),
  adj = c(0, 0)
)
}
\arguments{
\item{type}{type of legend:
\itemize{
\item \strong{prop} for proportional symbols,
\item \strong{choro} for choropleth maps,
\item \strong{cont} for continuous maps (e.g. raster),
\item \strong{typo} for typology maps,
\item \strong{symb} for symbols maps,
\item \strong{prop_line} for proportional lines maps,
\item \strong{grad_line} for graduated lines maps,
\item \strong{histo} for histograms,
\item \strong{choro_point} for choropleth points maps,
\item \strong{choro_line} for choropleth lines maps,
\item \strong{choro_symb} for choropleth on symbols maps
\item \strong{typo_line} for typology lines maps.
}}

\item{val}{vector of value(s) (for "prop" and "prop_line", at least c(min, max)
for "cont"),
vector of categories (for "symb", "typo", "typo_line"),
break labels (for "choro", "choro_point", "choro_line", "choro_symb",
and "grad_line"),
histogram parameters (for "histo").}

\item{pos}{position of the legend. It can be one of 'topleft', 'top',
'topright', 'right', 'bottomright', 'bottom','bottomleft',
'left', 'interactive' or a vector of two coordinates
in map units (c(x, y)).}

\item{pal}{a color palette name or a vector of colors}

\item{alpha}{opacity, in the range [0,1]}

\item{col}{color of the symbols (for "prop") or color of the lines (for
"prop_line" and "grad_line")}

\item{inches}{size of the largest symbol (radius for circles, half width
for squares) in inches}

\item{val_max}{maximum value corresponding to the largest symbol}

\item{symbol}{type of symbols, 'circle' or 'square'}

\item{self_adjust}{if TRUE values are self-adjusted to keep min, max and
intermediate rounded values}

\item{lwd}{width(s) of the symbols borders (for "prop", "symb",
"choro_point", "choro_symb"),
width of the largest line (for "prop_line"), line width (for "choro_line"
and "typo_line"), vector of line widths (for "grad_line")}

\item{border}{symbol border color(s)}

\item{pch}{type(s) of the symbols (0:25)}

\item{cex}{size(s) of the symbols}

\item{title}{title of the legend}

\item{title_cex}{size of the legend title}

\item{val_cex}{size of the values in the legend}

\item{val_rnd}{number of decimal places of the values in
the legend}

\item{val_dec}{decimal separator}

\item{val_big}{thousands separator}

\item{col_na}{color for missing values}

\item{cex_na}{size of the symbols for missing values}

\item{pch_na}{type of the symbols for missing values}

\item{no_data}{if TRUE a "missing value" box is plotted}

\item{no_data_txt}{label for missing values}

\item{box_border}{border color of legend boxes}

\item{box_cex}{width and height size expansion for boxes, histogram
circles, squares or lines}

\item{horiz}{if TRUE plot an horizontal legend}

\item{frame_border}{border color of the frame}

\item{frame}{if TRUE the legend is plotted within a frame}

\item{bg}{background color of the legend}

\item{fg}{foreground color of the legend}

\item{size}{size of the legend; 2 means two times bigger}

\item{return_bbox}{return only bounding box of the legend.
No legend is plotted.}

\item{mar}{plot margins}

\item{adj}{adjust the postion of the legend in x and y directions.}
}
\value{
No value is returned, a legend is displayed.
}
\description{
Plot different types of legend. The "type" argument defines the
legend type.
Please note that some arguments are available for all types of legend and
some others are only relevant for specific legend types (see Details).
}
\details{
Some arguments are available for all types of legend: \code{val}, \code{pos}, \code{title},
\code{title_cex}, \code{val_cex}, \code{frame}, \code{bg}, \code{fg}, \code{size}, \code{adj}, \code{alpha},
\code{return_bbox} and \code{mar}).

Relevant arguments for each specific legend types:
\itemize{
\item \code{leg(type = "prop", val, inches, val_max, symbol, col, lwd, border, val_rnd, val_big, val_dec, self_adjust, horiz)}
\item \code{leg(type = "choro", val, pal, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt, box_border, box_cex, horiz)}
\item \code{leg(type = "cont", val, pal, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt, box_border, box_cex, horiz)}
\item \code{leg(type = "typo", val, pal, col_na, no_data, no_data_txt, box_border, box_cex)}
\item \code{leg(type = "symb", val, pal, pch, cex, lwd, pch_na, cex_na, col_na, no_data, no_data_txt)}
\item \code{leg(type = "prop_line", val, col, lwd, val_rnd, val_big, val_dec)}
\item \code{leg(type = "grad_line", val, col, lwd, val_rnd, val_big, val_dec)}
\item \code{leg(type = "histo", val, pal, box_border, val_rnd, val_big, val_dec)}
\item \code{leg(type = "choro_point", val, pal, symbol, border, cex, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt, horiz)}
\item \code{leg(type = "choro_line", val, pal, lwd, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt)}
\item \code{leg(type = "choro_symb", val, pal, pch, lwd, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt)}
\item \code{leg(type = "typo_line", val, pal, lwd, col_na, no_data, no_data_txt, box_cex)}
}
}
\examples{
# minimal example
plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1), asp = 1)
box()
leg(type = "prop", val = c(10, 50, 100), pos = "topleft")
leg(type = "choro", val = c(10, 20, 30, 40, 50), pos = "bottomleft")
leg(type = "typo", val = c("A", "B", "C"), pos = "top")
leg(type = "symb", val = c("A", "B", "C"), pos = "topright")
leg(type = "prop_line", val = c(5, 50, 100), pos = "bottom", lwd = 20)
leg(
  type = "grad_line", val = c(1, 4, 10, 15), pos = "bottomright",
  lwd = c(1, 5, 10)
)
plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1), asp = 1)
leg(type = "prop", val = c(10, 50, 100), pos = "topleft", horiz = TRUE)
leg(type = "choro", val = c(10, 20, 30, 40, 50), pos = "left", horiz = TRUE)
leg(
  type = "cont", val = c(10, 20, 30, 40, 50), pos = "bottomleft",
  horiz = TRUE
)
leg(type = "choro_point", val = c(10, 20, 30, 40, 50), pos = "top")
leg(
  type = "choro_point", val = c(10, 20, 30, 40, 50), pos = "right",
  horiz = TRUE
)
leg(
  type = "cont", val = c(10, 20, 30, 40, 50), pos = "topright",
  horiz = FALSE
)
set.seed(46)
leg(
  type = "histo", val = hist(rnorm(1000), breaks = 5, plot = FALSE),
  pos = "bottomright"
)
box()

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1), asp = 1)
leg(type = "choro_line", val = c(10, 20, 30, 40, 50), pos = "topleft")
leg(type = "typo_line", val = c("A", "B", "C"), pal = "Set 2", pos = "top")
leg(type = "choro_symb", val = c(10, 20, 30, 40, 50), pos = "topright")


# full example
plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "prop",
  val = c(5, 100),
  pos = "top",
  inches = .4,
  symbol = "circle",
  col = "#940000",
  lwd = 1,
  border = "#9494ff",
  val_rnd = 1,
  self_adjust = TRUE,
  title = "Proportional Symbols",
  title_cex = 1,
  val_cex = .8,
  bg = "grey10",
  fg = "yellow",
  frame = TRUE
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "choro",
  alpha = 1,
  val = c(10, 20, 30, 40, 50),
  pos = "top",
  pal = c("#7F000D", "#B56C6F", "#DBBABB", "#F1F1F1"),
  val_rnd = 2,
  col_na = "grey",
  no_data = TRUE,
  no_data_txt = "No data",
  box_border = "cornsilk",
  box_cex = c(2, 1),
  title = "Choropleth (sequential)"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "typo",
  val = c("A", "B", "C"),
  pos = "top",
  pal = "Dynamic",
  col_na = "grey",
  no_data = TRUE,
  no_data_txt = "No data",
  box_cex = c(1.2, 1),
  title = "Typology (categories)"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "symb",
  val = c("A", "B", "C"),
  pos = "top",
  pch = 21:23,
  cex = c(4, 4, 2),
  pal = "Inferno",
  lwd = 2,
  border = "red",
  col_na = "grey",
  pch_na = 3,
  cex_na = 1,
  no_data = TRUE,
  no_data_txt = "No data",
  title = "Symbols"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "cont",
  val = c(1, 2, 3, 4, 5),
  pos = "top",
  pal = "Inferno",
  alpha = .7,
  val_rnd = 2,
  horiz = TRUE,
  box_cex = c(2, 1),
  title = "Continuous"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "prop_line",
  val = c(54, 505, 1025),
  pos = "top",
  lwd = 15,
  col = "green",
  val_rnd = -1,
  box_cex = c(2, .5),
  title = "Proportional Lines",
  bg = "black",
  fg = "white",
  frame = TRUE
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "grad_line",
  val = c(1.25, 4.07, 10.001, 15.071),
  pos = "top",
  lwd = c(1, 7, 15),
  col = "#C130ff",
  val_rnd = 3,
  box_cex = c(2, 1),
  title = "Graduated Lines"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
set.seed(46)
x <- rnorm(10000) * 1000
val <- hist(x, breaks = quantile(x, 0:10 / 10), plot = FALSE)
leg(
  type = "histo",
  alpha = 1,
  val = val,
  pos = "top",
  pal = "Teal",
  val_rnd = 0,
  val_big = " ",
  box_border = "cornsilk",
  box_cex = c(1, 2),
  title = "Histogram"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "choro_point",
  alpha = 1,
  val = c(10, 20, 30, 40, 50),
  pos = "top",
  pal = c("#7F000D", "#B56C6F", "#DBBABB", "#F1F1F1"),
  val_rnd = 2,
  col_na = "grey",
  no_data = TRUE,
  no_data_txt = "No data",
  border = "tomato4",
  cex = 1.5,
  title = "Choropleth (sequential)"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "choro_line",
  alpha = 1,
  val = c(10, 20, 30, 40, 50),
  pos = "top",
  pal = c("#7F000D", "#B56C6F", "#DBBABB", "#F1F1F1"),
  val_rnd = 1,
  lwd = 4,
  col_na = "grey",
  no_data = TRUE,
  no_data_txt = "No data",
  title = "Choropleth (sequential)"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "choro_symb",
  alpha = 1,
  val = c(10, 20, 30, 40, 50),
  pch = 23,
  pos = "top",
  pal = c("#7F000D", "#B56C6F", "#DBBABB", "#F1F1F1"),
  val_rnd = 1,
  lwd = 1,
  col_na = "grey",
  no_data = TRUE,
  no_data_txt = "No data",
  title = "Choropleth (sequential)"
)

plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1))
leg(
  type = "typo_line",
  val = c("A", "B", "C"),
  lwd = 3,
  pos = "top",
  pal = c("red", "yellow", "green"),
  col_na = "black",
  no_data = TRUE,
  no_data_txt = "No data",
  box_cex = c(2, 1),
  frame = TRUE,
  title = "Typology (categories)"
)


# Positions
plot.new()
plot.window(xlim = c(0, 1), ylim = c(0, 1), asp = 1)
leg(
  type = "prop", val = c(10, 60, 100), pos = "bottomleft", adj = c(0, 4),
  title = "adj = c(0, 4)", frame = TRUE
)
leg(
  type = "choro", val = c(10, 50, 100), pos = "bottomright",
  adj = c(0, 8), title = "adj = c(0, 8)", frame = TRUE
)
leg(
  type = "prop", val = c(10, 50, 100), pos = "topleft",
  adj = c(0, -8), title = "adj = c(0, -8)"
)
box()
mtext(
  text = "A text on 1 line", side = 1, adj = .01,
  line = -1, cex = 1
)
mtext(
  text = "A text\non 2 lines", side = 1, adj = .99,
  line = -1, cex = 1
)
mtext(
  text = "A large text on 1 line", side = 3, adj = .01,
  line = -2, cex = 2
)
}
