From b45d1186bc7e3ae460b11f474cdc5a719f094b66 Mon Sep 17 00:00:00 2001
From: Jakub Nowosad <tupiszakaczki@gmail.com>
Date: Wed, 29 May 2024 18:06:04 +0200
Subject: [PATCH] improves tm_scale docs

---
 R/tm_layout.R               |  2 +-
 R/tm_scale_.R               | 28 +++++++++++++++++++---------
 man/opt_tm_donuts.Rd        | 18 ------------------
 man/tm_layout.Rd            |  2 +-
 man/tm_pos.Rd               |  2 +-
 man/tm_raster.Rd            |  4 ++--
 man/tm_scale.Rd             |  7 +++++++
 man/tm_scale_asis.Rd        |  5 ++++-
 man/tm_scale_categorical.Rd |  5 ++++-
 man/tm_scale_continuous.Rd  |  7 +++++--
 man/tm_scale_discrete.Rd    |  5 ++++-
 man/tm_scale_intervals.Rd   |  5 ++++-
 man/tm_scale_rank.Rd        |  5 ++++-
 man/tm_scale_rgb.Rd         |  3 +++
 14 files changed, 59 insertions(+), 39 deletions(-)
 delete mode 100644 man/opt_tm_donuts.Rd

diff --git a/R/tm_layout.R b/R/tm_layout.R
index 59ec1c98..cf27f9f5 100644
--- a/R/tm_layout.R
+++ b/R/tm_layout.R
@@ -20,7 +20,7 @@
 #' @param grid.show,grid.labels.pos,grid.x,grid.y,grid.n.x,grid.n.y,grid.crs,grid.col,grid.lwd,grid.alpha,grid.labels.show,grid.labels.size,grid.labels.col,grid.labels.rot,grid.labels.format,grid.labels.cardinal,grid.labels.margin.x,grid.labels.margin.y,grid.labels.space.x,grid.labels.space.y,grid.labels.inside.frame,grid.ticks,grid.lines,grid.ndiscr See [tmap_options()]
 #' @param mouse_coordinates.stack,mouse_coordinates.position,mouse_coordinates.show,panel.show,panel.labels,panel.label.size,panel.label.color,panel.label.fontface,panel.label.fontfamily,panel.label.bg.color,panel.label.height,panel.label.rot,qtm.scalebar,qtm.minimap,qtm.mouse.coordinates See [tmap_options()]
 #' @param earth.boundary,earth.boundary.color,earth.boundary.lwd,earth.datum,space.color,attr.color,max.categories,legend.hist.bg.color,legend.hist.bg.alpha,legend.hist.size,legend.hist.height,legend.hist.width,attr.outside,attr.outside.position,attr.outside.size,attr.position,attr.just,basemap.server,basemap.alpha,basemap.zoom,overlays,overlays.alpha,alpha,colorNA,symbol.size.fixed,dot.size.fixed,text.size.variable,bbox,check.and.fix,set.bounds,set.view,set.zoom.limits,name,basemap.show See [tmap_options()]
-#' @param title,main.title deprecated
+#' @param title,main.title deprecated See [tm_title()]
 #' @param ... used to catch other deprecated arguments
 #' @example ./examples/tm_layout.R 
 #' @name tm_layout
diff --git a/R/tm_scale_.R b/R/tm_scale_.R
index da3850dd..51541e0c 100644
--- a/R/tm_scale_.R
+++ b/R/tm_scale_.R
@@ -26,6 +26,11 @@ tm_shape_vars = function() {
 #' which scale is applied when.
 #' 
 #' @param ... arguments passed on to the applied scale function `tm_scale_*()`
+#' @seealso [tm_scale_asis()], [tm_scale_ordinal()], [tm_scale_categorical()],
+#' [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()]
 #' @export
 tm_scale = function(...) {
 	# maybe add the generic scales parameters after ... here?
@@ -37,11 +42,12 @@ tm_scale = function(...) {
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the
 #' layer functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The function `tm_scale_asis()` is used to take data values as they are and use them as such for the visual variable.
+#' The function [tm_scale_asis()] is used to take data values as they are and use them as such for the visual variable.
 #' 
 #' @param values.scale (generic scale argument) Scaling of the values. Only useful for size-related visual variables, such as `size` of [tm_symbols()] and `lwd` of [tm_lines()].
 #' @param value.neutral (generic scale argument) Value that can be considered neutral. This is used for legends of other visual variables of the same map layer. E.g. when both `fill` and `size` are used for [tm_symbols()] (using filled circles), the size legend items are filled with the `value.neutral` color from the `fill.scale` scale, and fill legend items are bubbles of size `value.neutral` from the `size.scale` scale.
 #' @param ... Arguments caught (and not used) from the automatic function [tm_scale()]
+#' @seealso [tm_scale()]
 #' @export
 tm_scale_asis = function(values.scale = NA, value.neutral = NA, ...) {
 	structure(c(list(FUN = "tmapScaleAsIs"), c(list(values.scale = values.scale, value.neutral = value.neutral), list(...))), class = c("tm_scale_asis", "tm_scale", "list"))
@@ -72,7 +78,7 @@ tm_scale_ordinal = function(n.max = 30,
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the
 #' layer functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The functions `tm_scale_categorical()` and `tm_scale_ordinal()` are used
+#' The functions [tm_scale_categorical()] and [tm_scale_ordinal()] are used
 #' for categorical data. The only difference between these functions is that the
 #' former assumes unordered categories whereas the latter assumes ordered categories.
 #' For colors (the visual variable `fill` or `col`), different default color
@@ -92,6 +98,7 @@ tm_scale_ordinal = function(n.max = 30,
 #' @param label.na (generic scale argument) Label for missing values
 #' @param label.null (generic scale argument) Label for null (out-of-scope) values
 #' @param label.format (generic scale argument) Label formatting (similar to `legend.format` in tmap3)
+#' @seealso [tm_scale()]
 #' @export
 #' @name tm_scale_categorical
 #' @rdname tm_scale_categorical
@@ -117,7 +124,7 @@ tm_scale_categorical = function(n.max = 30,
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the
 #' layer functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The function `tm_scale_interval()` is used for numerical data.
+#' The function [tm_scale_interval()] is used for numerical data.
 #' 
 #' @param n Number of intervals. For some styles (see argument `style` below) it is the preferred number rather than the exact number.
 #' @param style Method to create intervals. Options are `"cat"`, `"fixed"`, `"sd"`, `"equal"`, `"pretty"`, `"quantile"`, `"kmeans"`, `"hclust"`, `"bclust"`, `"fisher"`, `"jenks"`, `"dpih"`, `"headtails"`, and `"log10_pretty"`. See the details in [classInt::classIntervals()] (extra arguments can be passed on via `style.args`).
@@ -137,6 +144,7 @@ tm_scale_categorical = function(n.max = 30,
 #' @param label.na (generic scale argument) Label for missing values
 #' @param label.null (generic scale argument) Label for null (out-of-scope) values
 #' @param label.format (generic scale argument) Label formatting (similar to legend.format in tmap3)
+#' @seealso [tm_scale()]
 #' @export
 tm_scale_intervals = function(n = 5, 
 							  style = ifelse(is.null(breaks), "pretty", "fixed"),
@@ -164,7 +172,7 @@ tm_scale_intervals = function(n = 5,
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the
 #' layer functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The function `tm_scale_discrete()` is used for discrete numerical data, such as integers.
+#' The function [tm_scale_discrete()] is used for discrete numerical data, such as integers.
 #' 
 #' @param ticks Discrete values. If not specified, it is determined automatically: unique values are put on a discrete scale.
 #' @param midpoint The data value that is interpreted as the midpoint. By default it is set to 0 if negative and positive values are present. Useful when values are diverging colors. 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 `NA`, which means that the value that corresponds to the middle color class (see `style`) is mapped to the middle color. If it is specified for sequential color palettes (e.g. `"Blues"`), then this color palette will be treated as a diverging color palette.
@@ -179,6 +187,7 @@ tm_scale_intervals = function(n = 5,
 #' @param label.na (generic scale argument) Label for missing values
 #' @param label.null (generic scale argument) Label for null (out-of-scope) values
 #' @param label.format (generic scale argument) Label formatting (similar to `legend.format` in tmap3)
+#' @seealso [tm_scale()]
 #' @export
 tm_scale_discrete = function(ticks = NA,
 							 #step = NA,
@@ -202,7 +211,7 @@ tm_scale_discrete = function(ticks = NA,
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the layer
 #' functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The function `tm_scale_continuous()` is used for continuous data.
+#' The function [tm_scale_continuous()] is used for continuous data.
 #' The functions `tm_scale_continuous_<x>()` use transformation functions x.
 #' 
 #' @param n Preferred number of tick labels. Only used if `ticks` is not specified
@@ -224,6 +233,7 @@ tm_scale_discrete = function(ticks = NA,
 #' @param label.format (generic scale argument) Label formatting (similar to `legend.format` in tmap3)
 #' @param trans.args list of additional argument for the transformation (generic transformation arguments)
 #' @inheritParams scales::transform_pseudo_log
+#' @seealso [tm_scale()]
 #' @export
 #' @rdname tm_scale_continuous
 #' @name tm_scale_continuous
@@ -255,7 +265,7 @@ tm_scale_continuous = function(n = NULL,
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the layer
 #' functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The function `tm_scale_rank()` is used to rank numeric data.
+#' The function [tm_scale_rank()] is used to rank numeric data.
 #' 
 #' @param n Preferred number of tick labels. Only used if `ticks` is not specified
 #' @param ticks Tick values. If not specified, it is determined automatically with `n`
@@ -271,6 +281,7 @@ tm_scale_continuous = function(n = NULL,
 #' @param label.null (generic scale argument) Label for null (out-of-scope) values
 #' @param label.format (generic scale argument) Label formatting (similar to `legend.format` in tmap3)
 #' @param unit unit the unit name of the values. By default `"rank"`.
+#' @seealso [tm_scale()]
 #' @export
 tm_scale_rank = function(n = NULL,
 						 ticks = NULL,
@@ -298,7 +309,7 @@ tm_scale_rank = function(n = NULL,
 #' }
 
 #' @export
-#' @param ... passed on to `tm_scale_continuous`
+#' @param ... passed on to [tm_scale_continuous()]
 #' @rdname tm_scale_continuous
 #' @name tm_scale_continuous_log
 tm_scale_continuous_log = function(..., base = exp(1)) {
@@ -341,8 +352,6 @@ tm_scale_continuous_pseudo_log = function(..., base = exp(1), sigma = 1) {
 	tm_scale_continuous(trans = "pseudo_log", trans.args = list(base = base, sigma = sigma), ...)
 }
 
-
-
 # 
 # #' @export
 # #' @rdname tm_scale_continuous
@@ -358,6 +367,7 @@ tm_scale_continuous_pseudo_log = function(..., base = exp(1), sigma = 1) {
 #'
 #' @param value.na value for missing values
 #' @param maxValue maximum value
+#' @seealso [tm_scale()]
 #' @export
 tm_scale_rgb = function(value.na = NA,
 						maxValue = 255) {
diff --git a/man/opt_tm_donuts.Rd b/man/opt_tm_donuts.Rd
deleted file mode 100644
index e710a48a..00000000
--- a/man/opt_tm_donuts.Rd
+++ /dev/null
@@ -1,18 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/tm_layer_donuts.R
-\name{opt_tm_donuts}
-\alias{opt_tm_donuts}
-\title{Options for tm_donuts}
-\usage{
-opt_tm_donuts()
-}
-\arguments{
-\item{type}{cartogram type, one of: "cont" for contiguous cartogram, "ncont" for non-contiguous cartogram and "dorling" for Dorling cartograms}
-
-\item{itermax, }{maximum number of iterations (see \code{\link[cartogram:cartogram_cont]{cartogram::cartogram_cont()}})}
-
-\item{...}{arguments passed on to \code{\link[cartogram:cartogram_cont]{cartogram::cartogram_cont()}}}
-}
-\description{
-Options for tm_donuts
-}
diff --git a/man/tm_layout.Rd b/man/tm_layout.Rd
index aab9c6e2..eb3709ce 100644
--- a/man/tm_layout.Rd
+++ b/man/tm_layout.Rd
@@ -294,7 +294,7 @@ tm_layout(
 
 \item{earth.boundary, earth.boundary.color, earth.boundary.lwd, earth.datum, space.color, attr.color, max.categories, legend.hist.bg.color, legend.hist.bg.alpha, legend.hist.size, legend.hist.height, legend.hist.width, attr.outside, attr.outside.position, attr.outside.size, attr.position, attr.just, basemap.server, basemap.alpha, basemap.zoom, overlays, overlays.alpha, alpha, colorNA, symbol.size.fixed, dot.size.fixed, text.size.variable, bbox, check.and.fix, set.bounds, set.view, set.zoom.limits, name, basemap.show}{See \code{\link[=tmap_options]{tmap_options()}}}
 
-\item{title, main.title}{deprecated}
+\item{title, main.title}{deprecated See \code{\link[=tm_title]{tm_title()}}}
 }
 \description{
 Set of tmap options that are directly related to the layout.
diff --git a/man/tm_pos.Rd b/man/tm_pos.Rd
index 7784df40..e29c4081 100644
--- a/man/tm_pos.Rd
+++ b/man/tm_pos.Rd
@@ -50,7 +50,7 @@ Set the position of map components, such as legends, title, compass, scale bar,
 \code{tm_pos_out()} places the components outside the map area and \code{tm_pos_in()} inside the map area.
 Each \code{position} argument of a map layer or component should be specified with
 one of these functions. The functions \code{tm_pos_auto_out()} and \code{tm_pos_auto_in()}
-are used to set the components automatically, and are recommended to use globally,
+are used to set the components automatically, and should be used
 via \code{\link[=tmap_options]{tmap_options()}}. See Details how the positioning works.
 }
 \details{
diff --git a/man/tm_raster.Rd b/man/tm_raster.Rd
index 80782f18..f8f44eb1 100644
--- a/man/tm_raster.Rd
+++ b/man/tm_raster.Rd
@@ -6,7 +6,7 @@
 \alias{opt_tm_rgb}
 \title{Map layer: raster}
 \usage{
-opt_tm_raster(interpolate = FALSE)
+opt_tm_raster(interpolate = TRUE)
 
 tm_raster(
   col = tm_shape_vars(),
@@ -26,7 +26,7 @@ tm_raster(
   ...
 )
 
-opt_tm_rgb(interpolate = TRUE)
+opt_tm_rgb(interpolate = FALSE)
 }
 \arguments{
 \item{interpolate}{Should the raster image be interpolated? Currently only applicable in view mode (passed on to \code{\link[grid:grid.raster]{grid}})}
diff --git a/man/tm_scale.Rd b/man/tm_scale.Rd
index 472ee8b2..06a15458 100644
--- a/man/tm_scale.Rd
+++ b/man/tm_scale.Rd
@@ -17,3 +17,10 @@ is a scale that is set automatically given by the data type (factor, numeric, an
 and the visual variable. The tmap option \code{scales.var} contains information
 which scale is applied when.
 }
+\seealso{
+\code{\link[=tm_scale_asis]{tm_scale_asis()}}, \code{\link[=tm_scale_ordinal]{tm_scale_ordinal()}}, \code{\link[=tm_scale_categorical]{tm_scale_categorical()}},
+\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()}}
+}
diff --git a/man/tm_scale_asis.Rd b/man/tm_scale_asis.Rd
index 17d77d56..30178162 100644
--- a/man/tm_scale_asis.Rd
+++ b/man/tm_scale_asis.Rd
@@ -17,5 +17,8 @@ tm_scale_asis(values.scale = NA, value.neutral = NA, ...)
 Scales in tmap are configured by the family of functions with prefix \code{tm_scale}.
 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_asis()} is used to take data values as they are and use them as such for the visual variable.
+The function \code{\link[=tm_scale_asis]{tm_scale_asis()}} is used to take data values as they are and use them as such for the visual variable.
+}
+\seealso{
+\code{\link[=tm_scale]{tm_scale()}}
 }
diff --git a/man/tm_scale_categorical.Rd b/man/tm_scale_categorical.Rd
index 92d06187..9cdf7fb0 100644
--- a/man/tm_scale_categorical.Rd
+++ b/man/tm_scale_categorical.Rd
@@ -72,9 +72,12 @@ tm_scale_categorical(
 Scales in tmap are configured by the family of functions with prefix \code{tm_scale}.
 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 functions \code{tm_scale_categorical()} and \code{tm_scale_ordinal()} are used
+The functions \code{\link[=tm_scale_categorical]{tm_scale_categorical()}} and \code{\link[=tm_scale_ordinal]{tm_scale_ordinal()}} are used
 for categorical data. The only difference between these functions is that the
 former assumes unordered categories whereas the latter assumes ordered categories.
 For colors (the visual variable \code{fill} or \code{col}), different default color
 palettes are used (see the tmap option \code{values.var}).
 }
+\seealso{
+\code{\link[=tm_scale]{tm_scale()}}
+}
diff --git a/man/tm_scale_continuous.Rd b/man/tm_scale_continuous.Rd
index 9a92ec6f..4b18cfec 100644
--- a/man/tm_scale_continuous.Rd
+++ b/man/tm_scale_continuous.Rd
@@ -80,7 +80,7 @@ tm_scale_continuous_pseudo_log(..., base = exp(1), sigma = 1)
 
 \item{trans.args}{list of additional argument for the transformation (generic transformation arguments)}
 
-\item{...}{passed on to \code{tm_scale_continuous}}
+\item{...}{passed on to \code{\link[=tm_scale_continuous]{tm_scale_continuous()}}}
 
 \item{base}{base of logarithm}
 
@@ -90,6 +90,9 @@ tm_scale_continuous_pseudo_log(..., base = exp(1), sigma = 1)
 Scales in tmap are configured by the family of functions with prefix \code{tm_scale}.
 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_continuous()} is used for continuous data.
+The function \code{\link[=tm_scale_continuous]{tm_scale_continuous()}} is used for continuous data.
 The functions \verb{tm_scale_continuous_<x>()} use transformation functions x.
 }
+\seealso{
+\code{\link[=tm_scale]{tm_scale()}}
+}
diff --git a/man/tm_scale_discrete.Rd b/man/tm_scale_discrete.Rd
index b8107e6b..789f21fb 100644
--- a/man/tm_scale_discrete.Rd
+++ b/man/tm_scale_discrete.Rd
@@ -51,5 +51,8 @@ tm_scale_discrete(
 Scales in tmap are configured by the family of functions with prefix \code{tm_scale}.
 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_discrete()} is used for discrete numerical data, such as integers.
+The function \code{\link[=tm_scale_discrete]{tm_scale_discrete()}} is used for discrete numerical data, such as integers.
+}
+\seealso{
+\code{\link[=tm_scale]{tm_scale()}}
 }
diff --git a/man/tm_scale_intervals.Rd b/man/tm_scale_intervals.Rd
index a9bbd443..7b0678c3 100644
--- a/man/tm_scale_intervals.Rd
+++ b/man/tm_scale_intervals.Rd
@@ -66,5 +66,8 @@ tm_scale_intervals(
 Scales in tmap are configured by the family of functions with prefix \code{tm_scale}.
 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_interval()} is used for numerical data.
+The function \code{\link[=tm_scale_interval]{tm_scale_interval()}} is used for numerical data.
+}
+\seealso{
+\code{\link[=tm_scale]{tm_scale()}}
 }
diff --git a/man/tm_scale_rank.Rd b/man/tm_scale_rank.Rd
index 49e7110e..6e585740 100644
--- a/man/tm_scale_rank.Rd
+++ b/man/tm_scale_rank.Rd
@@ -54,5 +54,8 @@ tm_scale_rank(
 Scales in tmap are configured by the family of functions with prefix \code{tm_scale}.
 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_rank()} is used to rank numeric data.
+The function \code{\link[=tm_scale_rank]{tm_scale_rank()}} is used to rank numeric data.
+}
+\seealso{
+\code{\link[=tm_scale]{tm_scale()}}
 }
diff --git a/man/tm_scale_rgb.Rd b/man/tm_scale_rgb.Rd
index 4b308bae..71143273 100644
--- a/man/tm_scale_rgb.Rd
+++ b/man/tm_scale_rgb.Rd
@@ -14,3 +14,6 @@ tm_scale_rgb(value.na = NA, maxValue = 255)
 \description{
 Scales: RGB
 }
+\seealso{
+\code{\link[=tm_scale]{tm_scale()}}
+}