diff --git a/DESCRIPTION b/DESCRIPTION index 1d55b331..2b3c7038 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -60,8 +60,6 @@ Suggests: terra, testthat (>= 3.2.0), tidyr -VignetteBuilder: - knitr Config/Needs/check: Nowosad/spDataLarge, lwgeom Config/Needs/coverage: Nowosad/spDataLarge, lwgeom Config/testthat/edition: 3 diff --git a/R/pkg.R b/R/pkg.R index 6ac41c2e..51299e9e 100644 --- a/R/pkg.R +++ b/R/pkg.R @@ -4,9 +4,8 @@ #' This package offers a flexible, layer-based, and easy to use approach to create #' thematic maps, such as choropleths and bubble maps. It is based on the grammar #' of graphics, and resembles the syntax of ggplot2. -#' +#' #' This page provides a brief overview of all package functions. -#' See `vignette("tmap_sneak_peek")` for a short introduction with examples. #' #' @section Quick plotting method: #' \tabular{ll}{ @@ -19,7 +18,7 @@ #' \tabular{ll}{ #' [tm_shape()]\tab Specify a shape object \cr #' } -#' +#' #' Aesthetics base layers: #' \tabular{ll}{ #' [tm_polygons()]\tab Create a polygon layer (with borders) \cr @@ -30,7 +29,7 @@ #' [tm_basemap()]\tab Create a layer of basemap tiles \cr #' [tm_tiles()]\tab Create a layer of overlay tiles \cr #' } -#' +#' #' Aesthetics derived layers: #' \tabular{ll}{ #' [tm_fill()]\tab Create a polygon layer (without borders) \cr @@ -42,12 +41,12 @@ #' [tm_iso()]\tab Create a layer of iso/contour lines \cr #' [tm_rgb()]\tab Create a raster layer of an image \cr #' } -#' +#' #' Faceting (small multiples) #' \tabular{ll}{ #' [tm_facets()]\tab Define facets \cr #' } -#' +#' #' Attributes: #' \tabular{ll}{ #' [tm_grid()]\tab Create grid lines \cr @@ -58,7 +57,7 @@ #' [tm_xlab()] and [tm_ylab()]\tab Create axis labels \cr #' [tm_minimap()]\tab Create a minimap (view mode only) \cr #' } -#' +#' #' Layout element: #' \tabular{ll}{ #' [tm_layout()]\tab Adjust the layout (main function)\cr @@ -67,7 +66,7 @@ #' [tm_style()]\tab Apply a predefined style \cr #' [tm_format()]\tab Apply a predefined format \cr #' } -#' +#' #' Change options: #' \tabular{ll}{ #' [tmap_mode()]\tab Set the tmap mode: `"plot"` or `"view"`\cr @@ -75,14 +74,14 @@ #' [tmap_options()]\tab Set global tmap options (from [tm_layout()], [tm_view()], and a couple of others) \cr #' [tmap_style()]\tab Set the default style \cr #' } -#' +#' #' Create icons: #' \tabular{ll}{ #' [tmap_icons()]\tab Specify icons for markers or proportional symbols \cr #' } -#' -#' -#' @section Output functions: +#' +#' +#' @section Output functions: #' \tabular{ll}{ #' [print()]\tab Plot in graphics device or view interactively in web browser or RStudio's viewer pane \cr #' [tmap_last()]\tab Redraw the last map \cr @@ -91,8 +90,8 @@ #' [tmap_arrange()]\tab Create small multiples of separate maps \cr #' [tmap_save()]\tab Save thematic maps (either as image or HTML file) \cr #' } -#' -#' @section Spatial datasets: +#' +#' @section Spatial datasets: #' \tabular{ll}{ #' [`World`]\tab World country data ([`sf`][`sf::sf`] object of polygons) \cr #' [`NLD_prov`]\tab Netherlands province data ([`sf`][`sf::sf`] object of polygons) \cr @@ -101,13 +100,12 @@ #' [`rivers`]\tab Rivers ([`sf`][`sf::sf`] object of lines) \cr #' [`land`]\tab Global land cover ([`stars`][stars::st_as_stars()] object)\cr #' } -#' +#' #' @author Martijn Tennekes \email{mtennekes@@gmail.com} #' @concept GIS #' @concept thematic maps #' @concept statistical maps #' @concept choropleth #' @concept bubble map -#' @seealso `vignette("tmap_sneak_peek")`, #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} "_PACKAGE" diff --git a/R/qtm.R b/R/qtm.R index a0cff29a..ecabc883 100644 --- a/R/qtm.R +++ b/R/qtm.R @@ -62,7 +62,6 @@ #' called without prefix. #' @return A [`tmap-element`] #' @example ./examples/qtm.R -#' @seealso `vignette("tmap_sneak_peek")` #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, #' Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} #' @export diff --git a/R/tmap_mode.R b/R/tmap_mode.R index 8b7f1a35..46b5906a 100644 --- a/R/tmap_mode.R +++ b/R/tmap_mode.R @@ -1,5 +1,5 @@ #' Set tmap mode to static plotting or interactive viewing -#' +#' #' Set tmap mode to static plotting or interactive viewing. #' The global option `tmap.mode` determines the whether thematic maps are plot #' in the graphics device, or shown as an interactive leaflet map (see also [tmap_options()]. @@ -9,25 +9,25 @@ #' toggle thematic map and print last map: it does the same as `ttm()` followed #' by [tmap_last()]; in order words, it shows the last map in the other mode. #' It is recommended to use `tmap_mode()` in scripts and `ttm()`/`ttmp()` in the console. -#' +#' #' # mode = "plot" -#' +#' #' Thematic maps are shown in the graphics device. #' This is the default mode, and supports all tmap's features, #' such as small multiples (see [tm_facets()]) and extensive layout settings (see [tm_layout()]). #' It is recommended to use [tmap_save()] for saving static maps. -#' +#' #' # mode = "view" -#' +#' #' Thematic maps are viewed interactively in the web browser or RStudio's Viewer pane. #' Maps are fully interactive with tiles from OpenStreetMap or other map providers #' (see [tm_tiles()]). See also [tm_view()] for options related to the `"view"` mode. #' This mode generates a [leaflet::leaflet()] widget, which can also be directly #' obtained with [tmap_leaflet()]. -#' With R Markdown, it is possible to publish it to an HTML page. -#' +#' With R Markdown, it is possible to publish it to an HTML page. +#' #' However, there are a couple of constraints in comparison to `"plot"`: -#' +#' #' * The map is always projected according to the Web Mercator projection. #' Although this projection is the de facto standard for interactive web-based mapping, #' it lacks the equal-area property, which is important for many thematic maps, @@ -37,12 +37,11 @@ #' * Text labels are not supported (yet) #' * The layout options set with [tm_layout()]) regarding map format are not used. #' However, the styling options still apply. -#' -#' @param mode One of `"plot"` or `"view"`. See Details for more info. +#' +#' @param mode One of `"plot"` or `"view"`. See Details for more info. #' @return The previous tmap mode before switching. #' @example ./examples/tmap_mode.R -#' @seealso -#' * `vignette("tmap_sneak_peek")` +#' @seealso #' * [tmap_last()] to show the last map #' * [tm_view()] for viewing options #' * [tmap_leaflet()] for obtaining a leaflet widget @@ -52,10 +51,10 @@ #' @export tmap_mode = function(mode = NULL) { current.mode = getOption("tmap.mode") - + tOpt = get("tmapOptions", envir = .TMAP) show.messages = tOpt$show.messages - + modes = get_modes() if (is.null(mode)) { @@ -69,13 +68,13 @@ tmap_mode = function(mode = NULL) { if (show.messages) cli::cli_inform(c(i = "tmap mode set to {.val {mode}}.")) } invisible(current.mode) -} +} # tmap_graphics = function(mode = NULL) { # if (is.null(mode)) mode = getOption("tmap.mode") # get("tmapOptions", envir = .TMAP)$graphics[[mode]] # } -# +# # tmap_graphics_name = function(mode = NULL) { # tmap_graphics(mode = mode)$name # } @@ -85,13 +84,13 @@ get_modes = function() { } #' Set the design mode -#' +#' #' When the so-called "design mode" is enabled, inner and outer margins, #' legend position, and aspect ratio are shown explicitly in plot mode. #' Also, information about aspect ratios is printed in the console. #' This function sets the global option `tmap.design.mode`. #' It can be used as toggle function without arguments. -#' +#' #' @seealso [tmap_options()] #' @param design.mode Logical value that determines the design mode. #' If omitted then the design mode is toggled. @@ -103,7 +102,7 @@ tmap_design_mode = function(design.mode) { if (!is.logical(design.mode)) stop("design.mode is not a logical") design.mode[1] } - + options(tmap.design.mode = dm) message( "design.mode: ", if (!dm) "OFF" else "ON", @@ -111,10 +110,10 @@ tmap_design_mode = function(design.mode) { } #' Set the development mode -#' +#' #' When the so-called "development mode" is enabled, helpful messages and timings #' are printed in the console -#' +#' #' @param devel.mode logical value that determines the development mode. #' If omitted then the development mode is toggled. #' @export @@ -125,7 +124,7 @@ tmap_devel_mode = function(devel.mode) { if (!is.logical(devel.mode)) stop("devel.mode is not a logical") devel.mode[1] } - + options(tmap.devel.mode = dm) message("devel.mode: ", if (!dm) "OFF" else "ON") } @@ -137,10 +136,10 @@ pm = function(message) { po = function(...) { e = substitute(list(...)) - nms = sapply(e, deparse)[-1] - + nms = sapply(e, deparse)[-1] + x = list(...) - + for (i in seq_along(x)) { cat("<==================== ", nms[i], "===============>\n") print(x[[i]]) @@ -148,16 +147,16 @@ po = function(...) { cat("\n") } } - + invisible() } so = function(...) { e = substitute(list(...)) - nms = sapply(e, deparse)[-1] - + nms = sapply(e, deparse)[-1] + x = list(...) - + for (i in seq_along(x)) { cat("<==================== ", nms[i], "===============>\n") str(x[[i]]) @@ -165,7 +164,7 @@ so = function(...) { cat("\n") } } - + invisible() } @@ -173,12 +172,12 @@ so = function(...) { #' @export ttm = function() { current.mode = getOption("tmap.mode") - + modes = get_modes() - + id = match(current.mode, modes) + 1L if (id > length(modes)) id = 1L - + tmap_mode(modes[id]) invisible(current.mode) } diff --git a/man/qtm.Rd b/man/qtm.Rd index e0880184..1b556b76 100644 --- a/man/qtm.Rd +++ b/man/qtm.Rd @@ -167,6 +167,3 @@ qtm("Amsterdam") Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} } -\seealso{ -\code{vignette("tmap_sneak_peek")} -} diff --git a/man/tmap-package.Rd b/man/tmap-package.Rd index 6e3f28f0..40e465f5 100644 --- a/man/tmap-package.Rd +++ b/man/tmap-package.Rd @@ -13,7 +13,6 @@ of graphics, and resembles the syntax of ggplot2. } \details{ This page provides a brief overview of all package functions. -See \code{vignette("tmap_sneak_peek")} for a short introduction with examples. } \section{Quick plotting method}{ @@ -120,7 +119,13 @@ Create icons: Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} } \seealso{ -\code{vignette("tmap_sneak_peek")}, \url{https://r-tmap.github.io/tmap/} +Useful links: +\itemize{ + \item \url{https://github.com/r-tmap/tmap} + \item \url{https://r-tmap.github.io/tmap/} + \item Report bugs at \url{https://github.com/r-tmap/tmap/issues} +} + } \author{ Martijn Tennekes \email{mtennekes@gmail.com} diff --git a/man/tmap_mode.Rd b/man/tmap_mode.Rd index 29d3352f..e9b279f7 100644 --- a/man/tmap_mode.Rd +++ b/man/tmap_mode.Rd @@ -79,7 +79,6 @@ Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} } \seealso{ \itemize{ -\item \code{vignette("tmap_sneak_peek")} \item \code{\link[=tmap_last]{tmap_last()}} to show the last map \item \code{\link[=tm_view]{tm_view()}} for viewing options \item \code{\link[=tmap_leaflet]{tmap_leaflet()}} for obtaining a leaflet widget diff --git a/vignettes/01_tmap_intro_v4.Rmd b/vignettes/01_tmap_intro_v4.Rmd index 7b57cf0a..0caca171 100644 --- a/vignettes/01_tmap_intro_v4.Rmd +++ b/vignettes/01_tmap_intro_v4.Rmd @@ -1,23 +1,47 @@ --- title: "Introducing tmap 4" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` + + ```{r, echo = FALSE, message = FALSE} library(tmap) data(World, metro) @@ -473,29 +497,7 @@ For instance, legends will be placed outside of the maps by default, and there w In order to keep the layout as close as possible to **tmap v3**, there will be a style which will set the options back to the settings used by default in **tmap v3**. This can be set with just one command: `tmap_style("tmap_v3")` -## Color palettes - -There will be a huge number of directly available color palettes. -We have not settled on the exact details, e.g. which palettes to include, and how they can be obtained. -Ideas are welcome (https://github.com/r-tmap/tmap/issues/566). - -In the current development version, there is a function similar to `tmaptools::palette_explorer()`, which renders a long png in the viewer pane of RStudio or the browser: - -```{r, eval = FALSE, class.source='bg-success'} -# tmap v4 -tmap_show_palettes() -``` - -[![](https://user-images.githubusercontent.com/2444081/122732106-3ad8da80-d27c-11eb-98fd-1aafd6d7a52b.png)](https://user-images.githubusercontent.com/2444081/122725374-352bc680-d275-11eb-9a1c-0a88e4a97848.png) - -(click on the image to see the full png) - -It is also possible to render this for color blindness simulation, e.g.: `tmap_show_palettes(color_vision_deficiency = "deutan")`. - -All default palettes that we use will be usable for color blind people. - - ## Suggestions -Do you have any suggestions? Please let us know! Via https://github.com/r-tmap/tmap/issues, and please use the **tmap_v4** tag. +Do you have any suggestions? Please let us know! Via https://github.com/r-tmap/tmap/issues. diff --git a/vignettes/02_tmap_diff_v3.Rmd b/vignettes/02_tmap_diff_v3.Rmd index afe94250..9cba2892 100644 --- a/vignettes/02_tmap_diff_v3.Rmd +++ b/vignettes/02_tmap_diff_v3.Rmd @@ -1,21 +1,43 @@ --- title: "tmap: diff(v4, v3)" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` ```{r, echo = FALSE, message = FALSE} diff --git a/vignettes/03_tmap_vv.Rmd b/vignettes/03_tmap_vv.Rmd index ddce8560..a3d8c35e 100644 --- a/vignettes/03_tmap_vv.Rmd +++ b/vignettes/03_tmap_vv.Rmd @@ -1,23 +1,47 @@ --- title: "tmap: visual variables" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` + + ```{r, echo = FALSE, message = FALSE} library(tmap) #devtools::load_all() diff --git a/vignettes/04_tmap_scales.Rmd b/vignettes/04_tmap_scales.Rmd index 944cdae9..6f6e8757 100644 --- a/vignettes/04_tmap_scales.Rmd +++ b/vignettes/04_tmap_scales.Rmd @@ -1,23 +1,46 @@ --- title: "tmap: scales" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` + ```{r, echo = FALSE, message = FALSE} library(tmap) #devtools::load_all() diff --git a/vignettes/05_tmap_facets.Rmd b/vignettes/05_tmap_facets.Rmd index f1055737..eb9d7c57 100644 --- a/vignettes/05_tmap_facets.Rmd +++ b/vignettes/05_tmap_facets.Rmd @@ -1,12 +1,13 @@ --- title: "tmap: facets" -author: "Martijn Tennekes" output: bookdown::html_vignette2: pkgdown: as_is: true template: math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- ```{r, include = FALSE} @@ -14,8 +15,7 @@ knitr::opts_chunk$set( collapse = TRUE, fig.width=6, fig.height=3, - comment = "#>", - fig.path = "man/figures" + comment = "#>" ) hook_output <- knitr::knit_hooks$get("output") knitr::knit_hooks$set(output = function(x, options) { @@ -40,7 +40,6 @@ knitr::knit_hooks$set(output = function(x, options) { ``` - ```{r, echo = FALSE, message = FALSE} library(tmap) #devtools::load_all() diff --git a/vignettes/06_tmap_legends.Rmd b/vignettes/06_tmap_legends.Rmd index f73e483d..c7414ba4 100644 --- a/vignettes/06_tmap_legends.Rmd +++ b/vignettes/06_tmap_legends.Rmd @@ -1,27 +1,46 @@ --- -title: "tmap: charts" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" +title: "tmap: legends" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -vignette: > - \usepackage[utf8]{inputenc} - %\VignetteIndexEntry{tmap: charts} - %\VignetteEngine{knitr::rmarkdown} -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` + ```{r, echo = FALSE, message = FALSE} library(tmap) #devtools::load_all() diff --git a/vignettes/07_tmap_charts.Rmd b/vignettes/07_tmap_charts.Rmd index c33b3b5c..ed031462 100644 --- a/vignettes/07_tmap_charts.Rmd +++ b/vignettes/07_tmap_charts.Rmd @@ -1,21 +1,43 @@ --- title: "tmap: charts" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` ```{r, echo = FALSE, message = FALSE} diff --git a/vignettes/09_tmap_basemaps.Rmd b/vignettes/09_tmap_basemaps.Rmd deleted file mode 100644 index 834a428a..00000000 --- a/vignettes/09_tmap_basemaps.Rmd +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "tmap: visual variables" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" -output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -vignette: > - \usepackage[utf8]{inputenc} - %\VignetteIndexEntry{tmap: charts} - %\VignetteEngine{knitr::rmarkdown} -editor_options: - chunk_output_type: console ---- - -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) -``` - -```{r, echo = FALSE, message = FALSE} -library(tmap) -#devtools::load_all() -data(World, metro, rivers, land) -#tmap_design_mode() -``` - - -A **visual variable** describes a certain visual property of a drawn object, such as color, size, shape, line width, line stroke, transparency, fill pattern (in **ggplot2** these are called aesthetics). A visual variable can be specified using a constant value (e.g. `fill = "blue"`) or be **data-driven** (more on this later). If it can *only* be specified with a constant value, it is called a **visual constant**. - -The following table shows which visual variables are used in standard map layers. - -| Map layer | Visual variables | Visual constant | -|- |--- |-- | -| `tm_basemap()` | none | `alpha` | -| `tm_polygons()` | `fill` (fill color), `col` (border color), `lwd` (border line width) `lty` (border line type), `fill_alpha` (fill transparency), `col_alpha` (border color transparency) | `linejoin` (line join) and `lineend` (line end) | -| `tm_symbols()` | `fill` (fill color), `col` (border color), `size`, `shape`, `lwd` (border line width) `lty` (border line type), `fill_alpha` fill transparency, `col_alpha` border color transparency | `linejoin` (line join) and `lineend` (line end) | -| `tm_lines()` | `col` (color), `lwd` (line width) `lty` (line type), `alpha` transparency | `linejoin` (line join) and `lineend` (line end) | -| `tm_raster()` | `col` (color), `alpha` (transparency) | | -| `tm_text()` | `size`, `col` | | - -New in **tmap 4.0** is that users can write their own custom map layer functions; more on this in another vignette. Important for now is that map layers and their visual variables can be extended if needed. - -### Constant visual values - -The following code draws gold country polygons. - -```{r} -tm_shape(World) + - tm_polygons("gold") -``` - -All the visual variables mentioned in the previous table are used, but with constant values. For instance, polygon borders are drawn with width `lwd` and colored with `col`. Each of these visual variables has a default value, in case of the border width and color respectively `1` and `"black"`. The only visual variable for which we have specified a different value is `fill`, which we have set to `"gold"`. - -For those who are completely new to **tmap**: the function `tm_shape()` specifies the spatial data object, which can be any spatial data object from the packages `sf`, `stars`, `terra`, `sp`, and `raster`. The subsequent map layer functions (stacked with the `+` operator) specify how this spatial data is visualized. - -In the next example we have three layers: a basemap from OpenTopoMap, country polygon boundaries, and dots for metropolitan areas: - -```{r} -if (requireNamespace("maptiles")) { -tm_basemap(server = "OpenTopoMap", zoom = 2, alpha = 0.5) + -tm_shape(World, bbox = sf::st_bbox(c(xmin = -180, xmax = 180, ymin = -86, ymax = 86))) + - tm_polygons(fill = NA, col = "black") + -tm_shape(metro) + - tm_symbols(size = 0.1, col = "red") + -tm_layout(inner.margins = rep(0, 4)) -} -``` - -Each visual variable argument can also be specified with a data variable (e.g., a column name). What happens in that case is that the values of data variable are mapped to values of the corresponding visual variable. - -```{r} -tm_shape(World) + - tm_polygons("life_exp") -``` - -In this example, life expectancy per country is shown, or to put it more precisely: the *data variable* life expectancy is mapped to the *visual variable* polygon fill. - -To understand this data mapping, consider the following schematic dataset: - -```{r, echo=FALSE} -df = data.frame(geom = c("polygon1", "polygon2", "polygon3", "polygon4", "..."), x1 = c("72", "58", "52", "73", "..."), vv1 = c("blue6", "blue3", "blue2", "blue7", "...")) -print(df) -``` - -The first column contains spatial geometries (in this case polygons, but they can also be points, lines, and raster tiles). The second column is the data variable that we would like to show. The third column contains the visual values, in this case colors. - -Important to note is that there are many ways to scale data values to visual values. In this example data values are put into 5 year intervals and a sequential discrete blue scale is used to show these. With the `tm_scale_*()` family of functions, users are free to create other scales. - -```{r} -tm_shape(World) + - tm_polygons("life_exp", fill.scale = tm_scale_continuous(values = "-carto.earth"), fill.legend = tm_legend("Life\nExpectancy")) -``` - -This map uses a continuous color scale with colors from CARTO. More on scales later. - -## Transformation variables - -Besides visual variables, map layer may use spatial transformation variables. - -```{r} -if (requireNamespace("cartogram")) { -tm_shape(World, crs = 8857) + - tm_cartogram(size = "pop_est", fill = "income_grp") -} -``` - -We used two variables: `size` to deform the polygons using a continuous cartogram and `fill` to color the polygons. -The former is an example of a *transformation variable*. In our example schematic dataset: - -```{r, echo=FALSE} -df = data.frame(geom = c("polygon1", "polygon2", "polygon3", "polygon4", "..."), x1 = c("491,775", "2,231,503", "34,859,364", "4,320,748", "..."), x_scaled = c("0.0007", "0.0033", "0.0554", "0.0067", "..."), geom_transformed = c("polygon1'", "polygon2'", "polygon3'", "polygon4'", "...")) -print(df) -``` - -The data variable `x1`, in the example `pop_est` (population estimation), is scaled to `x1_scaled` which is in this case a normalization using a continuous scale. Next, the geometries are distorted such that the areas are proportional to `x1_scaled` (as much as the cartogram algorithm is able to achieve). diff --git a/vignettes/09_tmap_shiny.Rmd b/vignettes/09_tmap_shiny.Rmd index 2db94709..fcd9e926 100644 --- a/vignettes/09_tmap_shiny.Rmd +++ b/vignettes/09_tmap_shiny.Rmd @@ -1,23 +1,46 @@ --- title: "tmap: shiny integration" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` + ```{r, echo = FALSE, message = FALSE} library(tmap) library(shiny) diff --git a/vignettes/10_tmap_export.Rmd b/vignettes/10_tmap_export.Rmd index ff6b6646..daf250c7 100644 --- a/vignettes/10_tmap_export.Rmd +++ b/vignettes/10_tmap_export.Rmd @@ -1,21 +1,43 @@ --- title: "tmap: exporting maps" -author: "Martijn Tennekes" -date: "`r Sys.Date()`" output: - html_document: - toc: true - toc_float: - collapsed: false - smooth_scroll: false - toc_depth: 2 -link-citations: yes -editor_options: - chunk_output_type: console + bookdown::html_vignette2: +pkgdown: + as_is: true +template: + math-rendering: mathjax +bibliography: '`r system.file("tmap.bib", package="tmap")`' +csl: "`r system.file('ieee.csl', package = 'tmap')`" --- -```{r setup, include=FALSE} -knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + fig.width=6, + fig.height=3, + comment = "#>" +) +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(more, x[lines], more) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + ``` ```{r, echo = FALSE, message = FALSE}