From 62b0c912c602cdc1fb92f75b118766cb57bf544a Mon Sep 17 00:00:00 2001 From: Jakub Nowosad Date: Wed, 29 May 2024 18:31:25 +0200 Subject: [PATCH] improves docs --- R/tm_element.R | 6 --- R/tm_layers_sf.R | 3 -- R/tm_layers_symbols.R | 2 - R/tm_legend.R | 80 +++++++++++++++++++++++++++++++-------- R/tm_pos.R | 2 - R/tm_scale_.R | 2 +- R/tm_scale_bivariate.R | 1 + R/tmap_animation.R | 2 +- R/tmap_arrange.R | 2 +- R/tmap_leaflet.R | 4 +- R/tmap_options.R | 4 -- man/tm_legend.Rd | 32 ++++++++-------- man/tm_scale.Rd | 2 +- man/tm_scale_bivariate.Rd | 3 ++ 14 files changed, 90 insertions(+), 55 deletions(-) diff --git a/R/tm_element.R b/R/tm_element.R index a5442869..540f0885 100644 --- a/R/tm_element.R +++ b/R/tm_element.R @@ -62,7 +62,6 @@ save_last_map = function() { assign("last_map_new", NULL, envir = .TMAP) } - replace_last_tmap_by_correct_call = function(mc, lt) { if (is.symbol(mc)) { mc @@ -77,11 +76,6 @@ replace_last_tmap_by_correct_call = function(mc, lt) { } } - - - - - #' Print tm_element #' #' @param x x diff --git a/R/tm_layers_sf.R b/R/tm_layers_sf.R index 9695943a..b575faa2 100644 --- a/R/tm_layers_sf.R +++ b/R/tm_layers_sf.R @@ -19,9 +19,6 @@ opt_tm_sf = function(polygons.only = "yes", } - - - #' Map layer: simple features #' #' Map layer that draws simple features as they are. Supported visual variables diff --git a/R/tm_layers_symbols.R b/R/tm_layers_symbols.R index f5ee7092..bed11dbf 100644 --- a/R/tm_layers_symbols.R +++ b/R/tm_layers_symbols.R @@ -26,8 +26,6 @@ opt_tm_bubbles = opt_tm_symbols #' @export opt_tm_squares = opt_tm_symbols - - #' Map layer: symbols #' #' Map layer that draws symbols Supported visual variables are: diff --git a/R/tm_legend.R b/R/tm_legend.R index 81d4ae45..b2c1a459 100644 --- a/R/tm_legend.R +++ b/R/tm_legend.R @@ -2,34 +2,34 @@ #' #' Legend specification #' -#' @param title PARAM_DESCRIPTION -#' @param show PARAM_DESCRIPTION -#' @param orientation PARAM_DESCRIPTION +#' @param title Legend title +#' @param show Show legend? +#' @param orientation Orientation of the legend: `"portrait"` or `"landscape"` #' @param design PARAM_DESCRIPTION -#' @param reverse PARAM_DESCRIPTION +#' @param reverse Should the legend be reversed? #' @param na.show PARAM_DESCRIPTION #' @param position PARAM_DESCRIPTION -#' @param width PARAM_DESCRIPTION -#' @param height PARAM_DESCRIPTION +#' @param width Width of the legend +#' @param height Height of the legend #' @param stack PARAM_DESCRIPTION #' @param z PARAM_DESCRIPTION #' @param group.frame PARAM_DESCRIPTION #' @param resize.as.group PARAM_DESCRIPTION -#' @param title.color PARAM_DESCRIPTION -#' @param title.size PARAM_DESCRIPTION -#' @param title.fontface PARAM_DESCRIPTION -#' @param title.fontfamily PARAM_DESCRIPTION +#' @param title.color Color of the legend title +#' @param title.size Size of the legend title +#' @param title.fontface Font face of the legend title +#' @param title.fontfamily Font family of the legend title #' @param title.padding PARAM_DESCRIPTION -#' @param text.color PARAM_DESCRIPTION -#' @param text.size PARAM_DESCRIPTION -#' @param text.fontface PARAM_DESCRIPTION -#' @param text.fontfamily PARAM_DESCRIPTION +#' @param text.color Color of the legend text +#' @param text.size Size of the legend text +#' @param text.fontface Font face of the legend text +#' @param text.fontfamily Font family of the legend text #' @param format PARAM_DESCRIPTION #' @param frame PARAM_DESCRIPTION #' @param frame.lwd PARAM_DESCRIPTION #' @param frame.r PARAM_DESCRIPTION -#' @param bg.color PARAM_DESCRIPTION -#' @param bg.alpha PARAM_DESCRIPTION +#' @param bg.color Background color of the legend +#' @param bg.alpha Background transparency of the legend #' @param item.height PARAM_DESCRIPTION #' @param item.width PARAM_DESCRIPTION #' @param item.space PARAM_DESCRIPTION @@ -139,3 +139,51 @@ tm_legend_bivariate = function(xlab, structure(args, class = c("tm_legend", "tm_component", "list")) } +#' @param legend.show Logical that determines whether the legend is shown. +#' @param legend.only logical. Only draw the legend (without map)? Particularly useful for small multiples with a common legend. +#' @param legend.outside Logical that determines whether the legend is plot outside of the map/facets. Especially useful when using facets that have a common legend (i.e. with \code{free.scales=FALSE}). +#' @param legend.outside.position Character that determines the outside position of the legend. Only applicable when \code{legend.outside=TRUE}. One of: \code{"right"}, \code{"left"}, \code{"top"}, or \code{"bottom"}. +#' @param legend.outside.size Numeric value that determines the relative size of the legend, when \code{legend.outside=TRUE}. If the first value of \code{legend.outside.position} is \code{"top"} or \code{"bottom"}, then it is the width of the legend, else it is the height of the legend. Note that the actual height or width of the legend is determined by the content of the legend (and the used font sizes). This argument specifies the upperbound of the width or height. +#' @param legend.position Position of the legend. Vector of two values, specifying the x and y coordinates. Either this vector contains \code{"left"}, \code{"LEFT"}, \code{"center"}, \code{"right"}, or \code{"RIGHT"} for the first value and \code{"top"}, \code{"TOP"}, \code{"center"}, \code{"bottom"}, or \code{"BOTTOM"} for the second value, or this vector contains two numeric values between 0 and 1 that specifies the x and y coordinates of the left bottom corner of the legend. The uppercase values correspond to the position without margins (so tighter to the frame). By default, it is automatically placed in the corner with most space based on the (first) shape object. If \code{legend.outside=TRUE}, this argument specifies the legend position within the outside panel. +#' @param legend.stack Value that determines how different legends are stacked: \code{"vertical"} or \code{"horizontal"}. To stack items within a same legend, look at \code{"legend.is.portrait"} in the specific layer calls. +#' @param legend.just Justification of the legend 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/bottom alignment and 1 right/top alignment. This option is only used, if \code{legend.position} is specified by numeric coordinates. +#' @param legend.width width of the legend. This number is relative to the map area (so 1 means the whole map width). If it is a negative number, it will be the exact legend width. If it is a positive number (by default), it will be the maximum legend width; the actual legend width will be decreased automatically based on the legend content and font sizes.or Default color value for map attributes +#' @param legend.height height of the legend. If it is a negative number, it will be the exact legend height. If it is a positive number (by default), it will be the maximum legend height; the actual legend height will be decreased automatically based on the legend content and font sizes. +#' @param legend.hist.height height of the histogram. This height is initial. If the total legend is downscaled to \code{legend.height}, the histogram is downscaled as well. +#' @param legend.hist.width width of the histogram. By default, it is equal to the \code{legend.width}. +#' @param legend.title.color color of the legend titles +#' @param legend.title.size Relative font size for the legend title +#' @param legend.title.fontface font face for the legend title. By default, set to the global parameter \code{fontface}. +#' @param legend.title.fontfamily font family for the legend title. By default, set to the global parameter \code{fontfamily}. +#' @param legend.text.color color of the legend text +#' @param legend.text.size Relative font size for the legend text elements +#' @param legend.text.fontface font face for the legend text labels. By default, set to the global parameter \code{fontface}. +#' @param legend.text.fontfamily font family for the legend text labels. By default, set to the global parameter \code{fontfamily}. +#' @param legend.hist.size Relative font size for the choropleth histogram +#' @param legend.format list of formatting options for the legend numbers. Only applicable for layer functions (such as \code{\link{tm_fill}}) where \code{labels} is undefined. Parameters are: +#' \describe{ +#' \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.} +#' \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}, \code{text.or.more}, and \code{big.num.abbr} are used. Also, the numbers are automatically rounded to millions or billions if applicable.} +#' \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.} +#' \item{digits}{Number of digits after the decimal point if \code{format="f"}, and the number of significant digits otherwise.} +#' \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}.} +#' \item{text.separator}{Character string to use to separate numbers in the legend (default: "to").} +#' \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}} +#' \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}} +#' \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. +#' \item{text.to.columns}{Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default \code{FALSE}.} +#' \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. +#' \item{text.to.columns}{Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default \code{FALSE}.} +#' \item{html.escape}{Logical that determins whther HTML code is escaped in the popups in view mode. By default \code{TRUE}. If set to \code{FALSE} HTML code can be added, e.g. to added white space via \code{ }.} +#' \item{...}{Other arguments passed on to \code{\link[base:formatC]{formatC}}} +#' } +#' @param legend.hist.bg.color Background color of the histogram +#' @param legend.hist.bg.alpha Transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the \code{legend.hist.bg.color} is used (normally 1). +#' @param title.snap.to.legend Logical that determines whether the title is part of the legend. By default \code{FALSE}, unless the legend is drawn outside the map (see \code{legend.outside}). +#' @param title.position Position of the title. Vector of two values, specifying the x and y coordinates. Either this vector contains "left", "LEFT", "center", "right", or "RIGHT" for the first value and "top", "TOP", "center", "bottom", or "BOTTOM" for the second value, or this vector contains two numeric values between 0 and 1 that specifies the x and y coordinates of the tile. The uppercase values correspond to the position without margins (so tighter to the frame). +#' By default the title is placed on top of the legend (determined by \code{legend.position}). +#' @param title.color color of the title +#' @param title.fontface font face for the title. By default, set to the global parameter \code{fontface}. +#' @param title.fontfamily font family for the title. By default, set to the global parameter \code{fontfamily}. +#' @param legend.frame either a logical that determines whether the legend is placed inside a frame, or a color that directly specifies the frame border color. +#' @param legend.frame.lwd line width of the legend frame (applicable if \code{legend.frame} is \code{TRUE} or a color) diff --git a/R/tm_pos.R b/R/tm_pos.R index 0ed2bde4..9a27c944 100644 --- a/R/tm_pos.R +++ b/R/tm_pos.R @@ -151,12 +151,10 @@ tm_pos_auto_in = function(align.h, align.v, just.h, just.v) { structure(args, class = "tm_pos") } - str2pos = function(x) { tm_pos_in(x[1], x[2]) } - num2pos = function(x) { tm_pos_in(x[1], x[2]) } diff --git a/R/tm_scale_.R b/R/tm_scale_.R index 51541e0c..f614f7b2 100644 --- a/R/tm_scale_.R +++ b/R/tm_scale_.R @@ -30,7 +30,7 @@ tm_shape_vars = function() { #' [tm_scale_intervals()], [tm_scale_discrete()], [tm_scale_continuous()], #' [tm_scale_rank()], [tm_scale_continuous_log()], [tm_scale_continuous_log2()], #' [tm_scale_continuous_log10()], [tm_scale_continuous_log1p()], [tm_scale_continuous_sqrt()], -#' [tm_scale_continuous_pseudo_log()], [tm_scale_rgb()] +#' [tm_scale_continuous_pseudo_log()], [tm_scale_rgb()], [tm_scale_bivariate()] #' @export tm_scale = function(...) { # maybe add the generic scales parameters after ... here? diff --git a/R/tm_scale_bivariate.R b/R/tm_scale_bivariate.R index 0d84dfb6..cd9d4ded 100644 --- a/R/tm_scale_bivariate.R +++ b/R/tm_scale_bivariate.R @@ -16,6 +16,7 @@ #' @param labels (generic scale argument) Labels #' @param label.na (generic scale argument) Label for missing values #' @param label.null (generic scale argument) Label for null (out-of-scope) values +#' @seealso [tm_scale()] #' @export #' @name tm_scale_bivariate #' @rdname tm_scale_bivariate diff --git a/R/tmap_animation.R b/R/tmap_animation.R index 5034acac..f7fdfb70 100644 --- a/R/tmap_animation.R +++ b/R/tmap_animation.R @@ -37,7 +37,7 @@ #' @import tmaptools #' @importFrom utils browseURL #' @export -tmap_animation <- function(tm, filename = NULL, width = NA, height = NA, dpi = NA, delay = 40, fps = NA, loop = TRUE, outer.margins=NA, asp=NULL, scale=NA, restart.delay = NULL, ...) { +tmap_animation <- function(tm, filename = NULL, width = NA, height = NA, dpi = NA, delay = 40, fps = NA, loop = TRUE, outer.margins = NA, asp = NULL, scale = NA, restart.delay = NULL, ...) { .tmapOptions <- get("tmapOptions", envir = .TMAP) showAni = missing(filename) diff --git a/R/tmap_arrange.R b/R/tmap_arrange.R index 589b54ae..e842cce3 100644 --- a/R/tmap_arrange.R +++ b/R/tmap_arrange.R @@ -33,7 +33,7 @@ #' @param options options passed on to [knitr::knit_print()] #' @example ./examples/tmap_arrange.R #' @export -tmap_arrange <- function(..., ncol=NA, nrow=NA, widths=NA, heights = NA, sync=FALSE, asp=0, outer.margins=.02) { +tmap_arrange <- function(..., ncol = NA, nrow = NA, widths = NA, heights = NA, sync = FALSE, asp = 0, outer.margins = .02) { tms <- list(...) if (!inherits(tms[[1]], "tmap")) { if (!is.list(tms[[1]])) stop("The first argument of tmap_arrange is neither a tmap object nor a list.") diff --git a/R/tmap_leaflet.R b/R/tmap_leaflet.R index 4929c734..fef116f9 100644 --- a/R/tmap_leaflet.R +++ b/R/tmap_leaflet.R @@ -25,7 +25,7 @@ tmap_leaflet = function(x, options(tmap.mode = current_mode) }) options(tmap.mode = "view") - print.tmap(x, show=show, ...) + print.tmap(x, show = show, ...) } #' @name tmap_grid @@ -39,5 +39,5 @@ tmap_grid = function(x, options(tmap.mode = current_mode) }) options(tmap.mode = "plot") - print.tmap(x, show=show, ...) + print.tmap(x, show = show, ...) } diff --git a/R/tmap_options.R b/R/tmap_options.R index b053701f..6d063eb1 100644 --- a/R/tmap_options.R +++ b/R/tmap_options.R @@ -1245,10 +1245,6 @@ tmapAddLayerOptions = function(option, id, value) { tmap_options(o2) } - - - - #' @rdname tmap_options #' @export tmap_options_diff <- function() { diff --git a/man/tm_legend.Rd b/man/tm_legend.Rd index c43674f2..ee6146ec 100644 --- a/man/tm_legend.Rd +++ b/man/tm_legend.Rd @@ -57,23 +57,23 @@ tm_legend_hide() tm_legend_combine(variable) } \arguments{ -\item{title}{PARAM_DESCRIPTION} +\item{title}{Legend title} -\item{show}{PARAM_DESCRIPTION} +\item{show}{Show legend?} -\item{orientation}{PARAM_DESCRIPTION} +\item{orientation}{Orientation of the legend: \code{"portrait"} or \code{"landscape"}} \item{design}{PARAM_DESCRIPTION} -\item{reverse}{PARAM_DESCRIPTION} +\item{reverse}{Should the legend be reversed?} \item{na.show}{PARAM_DESCRIPTION} \item{position}{PARAM_DESCRIPTION} -\item{width}{PARAM_DESCRIPTION} +\item{width}{Width of the legend} -\item{height}{PARAM_DESCRIPTION} +\item{height}{Height of the legend} \item{stack}{PARAM_DESCRIPTION} @@ -83,23 +83,23 @@ tm_legend_combine(variable) \item{resize.as.group}{PARAM_DESCRIPTION} -\item{title.color}{PARAM_DESCRIPTION} +\item{title.color}{Color of the legend title} -\item{title.size}{PARAM_DESCRIPTION} +\item{title.size}{Size of the legend title} -\item{title.fontface}{PARAM_DESCRIPTION} +\item{title.fontface}{Font face of the legend title} -\item{title.fontfamily}{PARAM_DESCRIPTION} +\item{title.fontfamily}{Font family of the legend title} \item{title.padding}{PARAM_DESCRIPTION} -\item{text.color}{PARAM_DESCRIPTION} +\item{text.color}{Color of the legend text} -\item{text.size}{PARAM_DESCRIPTION} +\item{text.size}{Size of the legend text} -\item{text.fontface}{PARAM_DESCRIPTION} +\item{text.fontface}{Font face of the legend text} -\item{text.fontfamily}{PARAM_DESCRIPTION} +\item{text.fontfamily}{Font family of the legend text} \item{format}{PARAM_DESCRIPTION} @@ -109,9 +109,9 @@ tm_legend_combine(variable) \item{frame.r}{PARAM_DESCRIPTION} -\item{bg.color}{PARAM_DESCRIPTION} +\item{bg.color}{Background color of the legend} -\item{bg.alpha}{PARAM_DESCRIPTION} +\item{bg.alpha}{Background transparency of the legend} \item{item.height}{PARAM_DESCRIPTION} diff --git a/man/tm_scale.Rd b/man/tm_scale.Rd index 06a15458..0b79ab98 100644 --- a/man/tm_scale.Rd +++ b/man/tm_scale.Rd @@ -22,5 +22,5 @@ which scale is applied when. \code{\link[=tm_scale_intervals]{tm_scale_intervals()}}, \code{\link[=tm_scale_discrete]{tm_scale_discrete()}}, \code{\link[=tm_scale_continuous]{tm_scale_continuous()}}, \code{\link[=tm_scale_rank]{tm_scale_rank()}}, \code{\link[=tm_scale_continuous_log]{tm_scale_continuous_log()}}, \code{\link[=tm_scale_continuous_log2]{tm_scale_continuous_log2()}}, \code{\link[=tm_scale_continuous_log10]{tm_scale_continuous_log10()}}, \code{\link[=tm_scale_continuous_log1p]{tm_scale_continuous_log1p()}}, \code{\link[=tm_scale_continuous_sqrt]{tm_scale_continuous_sqrt()}}, -\code{\link[=tm_scale_continuous_pseudo_log]{tm_scale_continuous_pseudo_log()}}, \code{\link[=tm_scale_rgb]{tm_scale_rgb()}} +\code{\link[=tm_scale_continuous_pseudo_log]{tm_scale_continuous_pseudo_log()}}, \code{\link[=tm_scale_rgb]{tm_scale_rgb()}}, \code{\link[=tm_scale_bivariate]{tm_scale_bivariate()}} } diff --git a/man/tm_scale_bivariate.Rd b/man/tm_scale_bivariate.Rd index db9663af..509bdb4c 100644 --- a/man/tm_scale_bivariate.Rd +++ b/man/tm_scale_bivariate.Rd @@ -48,3 +48,6 @@ Such function should be used for the input of the \code{.scale} arguments in the layer functions (e.g. \code{fill.scale} in \code{\link[=tm_polygons]{tm_polygons()}}). The function \code{tm_scale_bivariate()} is used for \code{bivariate.scales}. } +\seealso{ +\code{\link[=tm_scale]{tm_scale()}} +}