From d59c3f97d5e3a566741b5f8c5f7c813fb9cfe4a5 Mon Sep 17 00:00:00 2001 From: olivroy Date: Tue, 19 Sep 2023 09:17:17 -0400 Subject: [PATCH 1/4] Rename files so they follow https://r-pkgs.org/data.html#sec-data-data usethis::use_data_raw() --- .Rbuildignore | 2 +- build/create_NLD.R => data-raw/NLD_muni_NLD_prov.R | 0 build/fix_world.R => data-raw/World-fix.R | 0 build/create_world.R => data-raw/World.R | 0 {build => data-raw}/compass_png.R | 0 build/create_land.R => data-raw/land.R | 0 build/create_metro.R => data-raw/metro.R | 0 build/create_rivers.R => data-raw/rivers.R | 0 build/create_palette_set.R => data-raw/tmap.pal.info.R | 2 +- 9 files changed, 2 insertions(+), 2 deletions(-) rename build/create_NLD.R => data-raw/NLD_muni_NLD_prov.R (100%) rename build/fix_world.R => data-raw/World-fix.R (100%) rename build/create_world.R => data-raw/World.R (100%) rename {build => data-raw}/compass_png.R (100%) rename build/create_land.R => data-raw/land.R (100%) rename build/create_metro.R => data-raw/metro.R (100%) rename build/create_rivers.R => data-raw/rivers.R (100%) rename build/create_palette_set.R => data-raw/tmap.pal.info.R (99%) diff --git a/.Rbuildignore b/.Rbuildignore index db7a017d..c70f6985 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -12,7 +12,6 @@ local LICENSE README .Rprofile -build/ gdal-2.1.0 gdal-2.1.0.tar.gz ubuntu_16_installation.sh @@ -23,3 +22,4 @@ ubuntu_17_installation.sh ^docs$ ^pkgdown$ ^\.github$ +^data-raw$ diff --git a/build/create_NLD.R b/data-raw/NLD_muni_NLD_prov.R similarity index 100% rename from build/create_NLD.R rename to data-raw/NLD_muni_NLD_prov.R diff --git a/build/fix_world.R b/data-raw/World-fix.R similarity index 100% rename from build/fix_world.R rename to data-raw/World-fix.R diff --git a/build/create_world.R b/data-raw/World.R similarity index 100% rename from build/create_world.R rename to data-raw/World.R diff --git a/build/compass_png.R b/data-raw/compass_png.R similarity index 100% rename from build/compass_png.R rename to data-raw/compass_png.R diff --git a/build/create_land.R b/data-raw/land.R similarity index 100% rename from build/create_land.R rename to data-raw/land.R diff --git a/build/create_metro.R b/data-raw/metro.R similarity index 100% rename from build/create_metro.R rename to data-raw/metro.R diff --git a/build/create_rivers.R b/data-raw/rivers.R similarity index 100% rename from build/create_rivers.R rename to data-raw/rivers.R diff --git a/build/create_palette_set.R b/data-raw/tmap.pal.info.R similarity index 99% rename from build/create_palette_set.R rename to data-raw/tmap.pal.info.R index 522c6b1f..14d4d816 100644 --- a/build/create_palette_set.R +++ b/data-raw/tmap.pal.info.R @@ -132,6 +132,6 @@ tmap_pals = local({ }) -usethis::use_data(tmap_pals, internal = FALSE) +usethis::use_data(tmap.pal.info, internal = FALSE) From 861994c830e87be4b999b44e7a8962add655cbf3 Mon Sep 17 00:00:00 2001 From: olivroy Date: Tue, 19 Sep 2023 09:36:51 -0400 Subject: [PATCH 2/4] Add new information of geospatial data. --- data-raw/land.R | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/data-raw/land.R b/data-raw/land.R index ecbbdc16..db201817 100644 --- a/data-raw/land.R +++ b/data-raw/land.R @@ -3,7 +3,9 @@ library(raster) library(RColorBrewer) #http://www.iscgm.org/gm/glcnmo.html - +# archived in 2016 +# World maps now hosted by UN geospatial +# https://www.un.org/geospatial/mapsgeo/generalmaps data(World) library(rgdal) From 4f53c2beafbe432a1756c7a863b0f164de7e3b00 Mon Sep 17 00:00:00 2001 From: olivroy Date: Wed, 20 Sep 2023 05:51:34 -0400 Subject: [PATCH 3/4] Fix sneak peek typo --- R/pkg.R | 4 ++-- R/qtm.R | 2 +- R/tmap_mode.R | 2 +- man/qtm.Rd | 2 +- man/tmap-package.Rd | 4 ++-- man/tmap_mode.Rd | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/R/pkg.R b/R/pkg.R index 98fd110c..d2c90223 100644 --- a/R/pkg.R +++ b/R/pkg.R @@ -2,7 +2,7 @@ #' #' Thematic maps are geographical maps in which spatial data distributions are visualized. 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_sneek_peek")` for a short introduction with examples. +#' 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}{ @@ -113,6 +113,6 @@ #' @concept statistical maps #' @concept choropleth #' @concept bubble map -#' @seealso `vignette("tmap_sneek_peek")`, +#' @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 5e05019e..25143051 100644 --- a/R/qtm.R +++ b/R/qtm.R @@ -28,7 +28,7 @@ #' @param ... arguments passed on to the `tm_*` functions. The prefix of these arguments should be with the layer function name without `"tm_"` and a period. For instance, the palette for polygon fill color is called `fill.palette`. The following prefixes are supported: `shape.`, `fill.`, `borders.`, `polygons.`, `symbols.`, `dots.`, `lines.`, `raster.`, `text.`, `layout.`, `grid.`, `facets.`, and `view.`. Arguments that have a unique name, i.e. that does not exist in any other layer function, e.g. `convert2density`, can also be called without prefix. #' @return [tmap-element()] #' @example ./examples/qtm.R -#' @seealso `vignette("tmap_sneek_peek")` +#' @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 qtm <- function(shp, diff --git a/R/tmap_mode.R b/R/tmap_mode.R index 308cf9a6..4173d3b6 100644 --- a/R/tmap_mode.R +++ b/R/tmap_mode.R @@ -16,7 +16,7 @@ #' }} #' @return The mode before changing #' @example ./examples/tmap_mode.R -#' @seealso `vignette("tmap_sneek_peek")`, [tmap_last()] to show the last map, [tm_view()] for viewing options, and [tmap_leaflet()] for obtaining a leaflet widget, and [tmap_options()] for tmap options. +#' @seealso `vignette("tmap_sneak_peek")`, [tmap_last()] to show the last map, [tm_view()] for viewing options, and [tmap_leaflet()] for obtaining a leaflet widget, and [tmap_options()] for tmap options. #' @references Tennekes, M., 2018, {tmap}: Thematic Maps in {R}, Journal of Statistical Software, 84(6), 1-39, \doi{10.18637/jss.v084.i06} #' @export tmap_mode = function(mode=NULL) { diff --git a/man/qtm.Rd b/man/qtm.Rd index 464d9212..10373ebb 100644 --- a/man/qtm.Rd +++ b/man/qtm.Rd @@ -127,5 +127,5 @@ 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_sneek_peek")} +\code{vignette("tmap_sneak_peek")} } diff --git a/man/tmap-package.Rd b/man/tmap-package.Rd index 80787613..c2bfc884 100644 --- a/man/tmap-package.Rd +++ b/man/tmap-package.Rd @@ -9,7 +9,7 @@ Thematic maps are geographical maps in which spatial data distributions are visualized. 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. } \details{ -This page provides a brief overview of all package functions. See \code{vignette("tmap_sneek_peek")} for a short introduction with examples. +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}{ @@ -125,7 +125,7 @@ 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_sneek_peek")}, \url{https://r-tmap.github.io/tmap/} +\code{vignette("tmap_sneak_peek")}, \url{https://r-tmap.github.io/tmap/} } \author{ Martijn Tennekes \email{mtennekes@gmail.com} diff --git a/man/tmap_mode.Rd b/man/tmap_mode.Rd index dbedef61..6583f478 100644 --- a/man/tmap_mode.Rd +++ b/man/tmap_mode.Rd @@ -51,5 +51,5 @@ tm_shape(World) + tm_polygons("HPI") 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_sneek_peek")}, \code{\link[=tmap_last]{tmap_last()}} to show the last map, \code{\link[=tm_view]{tm_view()}} for viewing options, and \code{\link[=tmap_leaflet]{tmap_leaflet()}} for obtaining a leaflet widget, and \code{\link[=tmap_options]{tmap_options()}} for tmap options. +\code{vignette("tmap_sneak_peek")}, \code{\link[=tmap_last]{tmap_last()}} to show the last map, \code{\link[=tm_view]{tm_view()}} for viewing options, and \code{\link[=tmap_leaflet]{tmap_leaflet()}} for obtaining a leaflet widget, and \code{\link[=tmap_options]{tmap_options()}} for tmap options. } From c1b8314e31683634f69ff417459f6e19549ac2c9 Mon Sep 17 00:00:00 2001 From: olivroy Date: Wed, 20 Sep 2023 07:19:19 -0400 Subject: [PATCH 4/4] Spell check for American English. --- NEWS.md | 176 +++++++++++++++++----------------- R/qtm.R | 12 +-- R/shapeTM.R | 6 +- R/tm_facets.R | 4 +- R/tm_layers_aux.R | 2 +- R/tm_layers_cartogram.R | 2 +- R/tm_layout.R | 2 +- R/tm_scale_.R | 8 +- R/tmap_options.R | 48 +++++----- R/tmap_save.R | 2 +- README.md | 10 +- examples/tm_polygons.R | 2 +- man/qtm.Rd | 12 +-- man/shapeTM.Rd | 6 +- man/tm_cartogram.Rd | 20 +++- man/tm_facets.Rd | 4 +- man/tm_grid.Rd | 2 +- man/tm_polygons.Rd | 2 +- man/tm_scale_categorical.Rd | 2 +- man/tm_scale_continuous.Rd | 2 +- man/tm_scale_discrete.Rd | 2 +- man/tm_scale_intervals.Rd | 2 +- man/tm_view.Rd | 2 +- man/tmap_options.Rd | 44 ++++----- man/tmap_save.Rd | 2 +- tests/testthat/test-v3.R | 2 +- tmap.Rproj | 2 + vignettes/tmap_sneak_peek.Rmd | 71 +++++++------- vignettes/tmap_vv.Rmd | 34 +++---- 29 files changed, 253 insertions(+), 232 deletions(-) diff --git a/NEWS.md b/NEWS.md index ff5f9b59..f43be66a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -7,26 +7,26 @@ # tmap 3.3-3 - added device to `tmap_save()` -- fixed many small bugs (see github issue list) +- fixed many small bugs (see GitHub issue list) # tmap 3.3-2 -- `World`s has been fixed (it is now 's2' proof, see github issue #564) +- `World`s has been fixed (it is now 's2' proof, see GitHub issue #564) # tmap 3.3-1 - fixed view titles - added html.escape to `popup.format` to control whether html code is escaped in view popups -- fixed many small bugs (see github issue list) +- fixed many small bugs (see GitHub issue list) # tmap 3.3 -- `tmap_grob()` added, which exports tmap plots to grob objects (grid package) +- `tmap_grob()` added, which exports tmap plots to `grob` objects (grid package) - `SpatRaster` objects (terra package) supported -- fixed many small bugs (see github issue list) +- fixed many small bugs (see GitHub issue list) # tmap 3.2 - `tmap_animation()` improved: now using av and gifski under the hood; added progress bar; lists of tmap objects supported; improved default settings - improved `tmapOutput()`; it now works with reactive shiny objects - improved internally used margins; also small exported maps look good (see example `tmap_save()`) -- improved `tmap_design_mode()`; tmap.design.mode is now a global option (and not a tmap option anymore) +- improved `tmap_design_mode()`; `tmap.design.mode` is now a global option (and not a tmap option anymore) - reexported providers from `leafet` - added `show.warnings` to `tmap_options()` - added `width` argument to `tm_credits()` @@ -40,26 +40,26 @@ - added in.iframe and `selfcontained` to `tmap_save()` - improved `tm_add_legend()`: added `type = "title"` for title only legend elements - added `ttmp()` which shows the last map in the other mode. -- fixed many small bugs (see github issue list) +- fixed many small bugs (see GitHub issue list) # tmap 3.0 - [!] spatial rasters/arrays now implemented using the stars package (instead of the raster package) - `as.count` argument added to layer functions; numeric variables can be treated as count variables (integers) - drop.levels argument added to layer functions which allows to drop unused levels -- new style added for color classes: "dpih" and "headtails"; also added style.args to pass on arguments to classIntervals +- new style added for color classes: "dpih" and "headtails"; also added style.args to pass on arguments to `classInt::classIntervals()` - grid labels specification per axis - fixed bug with geometry collection # tmap 2.3-2 - probably last version before release of tmap 3.0 -- many small improvements and bug fixes (see github) +- many small improvements and bug fixes (see GitHub) - first stars supported (full support expected in tmap 3.0) -- replaced projection shortcuts with epsg/proj4strings in examples +- replaced projection shortcuts with `"epsg/proj4strings"` in examples # tmap 2.3-1 - improved popups in view mode - added validity checks for `sf` objects -- minor bugs fixed: see github issue list +- minor bugs fixed: see GitHub issue list # tmap 2.3 - [!] shiny integration: added `tmapOutput()`, `renderTmap()`, `tmapProxy()`, and, `tm_remove_layer()` @@ -69,14 +69,14 @@ - supported TMS servers - in view mode, layers can be hidden from the legend with `group = NULL` - replaced `mapview` by `leafsync` -- minor bugs fixed: see github issue list +- minor bugs fixed: see GitHub issue list # tmap 2.2 - improved `tm_rgb()` - improved breaks in interactive maps - added `bbox` argument to `qtm()` - improved projection shortcut codes (using EPSG database) -- fixed several bugs (see github) +- fixed several bugs (see GitHub) # tmap 2.1-1 - fixed two small bugs @@ -90,15 +90,15 @@ # tmap 2.0 - [!] tmap migrated from sp to sf. sp objects are still supported, but all internal functions are based on sf -- [!] added tm_sf which draws sf objects -- [!] renamed all xxx_tmap functions (e.g. save_tmap) to tmap_xxx for consistency +- [!] added `tm_sf()` which draws sf objects +- [!] renamed all `*_tmap()` functions (e.g. `save_tmap()`) to `tmap_*()` for consistency - [!] added `tm_basemap()` and `tm_tiles()`: now, multiple (overlay) tiled maps can be shown - [!] rearranged tmap options, styles and formats. See `tmap_options()`, `tmap_style()`, `tmap_format()`, `tm_style()` and `tm_format()` - [!] added `filter` argument to `tm_shape()` and added `colorNULL` to layer functions - added `tm_minimap()` -- added remove.NA.facets to tm_facets +- added `remove.NA.facets` to `tm_facets()` - units data columns are supported -- tmap_animation enhanced with loop options +- `tmap_animation()` enhanced with loop options - added `tmap_tips()` - all changes are backwards compatible with 1.11-2 - vignettes rewritten, including a vignette that describes the changes of 2.0 @@ -113,144 +113,144 @@ - improved popup width in view mode # tmap 1.11 -- added text.align and text.to.columns to legend.format -- legend.(aes).reverse added to the layer functions +- added `text.align` and `text.to.columns` to `legend.format` +- `legend.(aes).reverse` added to the layer functions - symbol shapes can be put in a list for small multiples, and named according the values of the variable specified with the shape argument - grid labels can now be rotated and formatted -- changed default values of free.coords and drop.units in tm_facets -- fixed bug with all NA's in view mode -- fixed bug with dismo::gmap raster shapes +- changed default values of `free.coords` and `drop.units` in `tm_facets()` +- fixed bug with all NAs in view mode +- fixed bug with `dismo::gmap()` raster shapes - fixed bug for ambiguous values for aesthetics (e.g. when "blue" is also a variable name) - NOTE: this will be the last version before the major update (in which sf fully replaces sp) # tmap 1.10 -- [!] tm_scale_bar, tm_text, and tm_grid now supported in view mode (required leaflet 1.1.0) -- added along argument to tm_facets, which enables facetting along multiple pages (or animation frames) -- added main.title argument to tm_layout -- added tmap_options, including the new option tmap.unit ("metric" or "imperial"") -- improved automatic labeling of breaks +- [!] `tm_scale_bar()`, `tm_text()`, and `tm_grid()` now supported in view mode (requires leaflet 1.1.0) +- added `along` argument to `tm_facets()`, which enables faceting along multiple pages (or animation frames) +- added `main.title` argument to tm_layout +- added `tmap_options()`, including the new option `tmap.unit` ("metric" or "imperial"") +- improved automatic labelling of breaks - improved legend in view mode: missing values are shown by default (like in plot mode) - improved bubble scaling in view mode - fixed bug aspect ratio bug # tmap 1.8-1 -- added tm_rgb (shortcut for rgb rasters) -- fixed interactive maps in rmarkdown -- fixed bug in qtm called without arguments +- added `tm_rgb()` (shortcut for rgb rasters) +- fixed interactive maps in R Markdown +- fixed bug in `qtm()` called without arguments # tmap 1.8 - [!] package split: non-plotting functions migrated to tmaptools -- added tmap_arrange for arranging custom small multiples -- added simplify argument to tm_shape +- added `tmap_arrange()` for arranging custom small multiples +- added `simplify` argument to `tm_shape()` - added error message for NA-projected shapes in view mode - improved unit handling, which now can be set to metric or imperial - NA values allowed in direct color variables - sf (simple features) objects supported # tmap 1.6-1 -- improved projections: code is more efficient now and shortcuts are renewed. Also, CRS objects are now supported for all project arguments (e.g. tm_shape, set_projection), and as.CRS is added to get_projection and get_proj4. +- improved projections: code is more efficient now and shortcuts are renewed. Also, CRS objects are now supported for all project arguments (e.g. `tm_shape()`, set_projection), and as.CRS is added to get_projection and get_proj4. - Rscript works: methods is moved from imports to depends # tmap 1.6 -- [!] tm_symbols added, to create proportional symbol maps: besides bubbles, it also supports other symbol shapes, png icons, and small ggplot2 plots -- [!] imported cartogram function from cartogram package (tnx Sebastian!) -- [!] reverse geocoding function rev_geocode_OSM added +- [!] `tm_symbols()` added, to create proportional symbol maps: besides bubbles, it also supports other symbol shapes, png icons, and small ggplot2 plots +- [!] imported cartogram function from cartogram package (thanks Sebastian!) +- [!] reverse geocoding function `tmaptools::rev_geocode_OSM()` added - [!] `tm_logo()` added -- added popup.vars to base layer functions -- bounding box (argument bbox in tm_shape) working in view mode -- geocode_OSM improved: a SpatialPointsDataFrame can now be returned +- added `popup.vars` to base layer functions +- bounding box (argument `bbox` in `tm_shape()`) working in view mode +- `tmaptools::geocode_OSM()` improved: a `SpatialPointsDataFrame` can now be returned - `last_tmap()` added, which retrieves the last produced map - crop_shape can also handle polygons as cropping area - append_data improved; the under and over coverage information can be retrieved with under_coverage and over_coverage -- interpolate parameter added to tm_rasters -- added support for custom legend formating functions +- interpolate parameter added to `tm_raster()` +- added support for custom legend formatting functions - legend items can now be stacked horizontally -- legend width and height can be determined fully manually (with negative values for legend.height and legend.width) -- argument interval.closure added to layer functions to determine where intervals are closed +- legend width and height can be determined fully manually (with negative values for `legend.height` and `legend.width`) +- argument `interval.closure` added to layer functions to determine where intervals are closed - added warnings for non-supported elements in view mode - fixed raster brick bug -- fixed save_tmap/get_asp_ratio bug +- fixed save_tmap/get_asp_ratifo bug # tmap 1.4-1 -- add just argument as anchor for text labels, legend and attributes position +- add `just` argument as anchor for text labels, legend and attributes position - map attributes (such as scale bar) can be placed outside the frame -- added tm_xlab and tm_ylab +- added `tm_xlab()` and `tm_ylab()` - RGB raster support, see tm_raster - static text (i.e titles, credits, legend titles, labels) support expressions -- updated Europe shape: projection and boundig box are now consistent with Eurostat publications -- added crop_shape, a convenient wrapper around raster::crop +- updated Europe shape: projection and bounding box are now consistent with Eurostat publications +- added crop_shape, a convenient wrapper around `raster::crop()` # tmap 1.4 - [!] interactive mapping added. Now, tmap has two modes: "plot" (graphics device) and "view" (interactive viewer, which is a leaflet widget) - [!] facets (small multiples) improved: group by two variables possible, panel layout added, missing data can be shown separately -- added geocode_OSM, a function to find coordinates +- added `geocode_OSM()`, a function to find coordinates (now `tmaptools::geocode_OSM()`) - improved set_projection for raster objects -- added double_line and offset_line -- added insets option in save_tmap -- improved default settings for contrast arugment regarding seq and div palettes -- improved automatic positions of legend and map attributes (more specifically, legend snaps to righthand-side without need to adjust legend.width, and legend and attributes position improved when double frame is enabled) -- improved tm_layouts's design.mode output -- lwd parameter added to tm_scale_bar and tm_compass -- fixed bb bug +- added `double_line` and `offset_line` +- added insets option in `save_tmap` +- improved default settings for contrast argument regarding seq and div palettes +- improved automatic positions of legend and map attributes (more specifically, legend snaps to right-hand side without need to adjust legend.width, and legend and attributes position improved when double frame is enabled) +- improved `tm_layouts()`'s design.mode output +- `lwd` parameter added to `tm_scale_bar()` and `tm_compass()` +- fixed `bb` bug # tmap 1.2-1 - fixed bug with PROJ.4 version < 4.9.1 - improved error messages -- rd projection reset to +init=epsg:28992, since the latter now has a +towgs item -- fixed bug of print.tmap returned object +- rd projection reset to `"+init=epsg:28992"`, since the latter now has a `"+towgs"` item +- fixed bug of `print.tmap()` returned object # tmap 1.2 -- added read_osm, a function to read Open Street Map data -- added bb, a handy bounding box function +- added `read_osm()`, a function to read Open Street Map data (now `tmaptools::read_osm()`) +- added `bb`, a handy bounding box function - added layout themes with tm_style and tm_format - added automatic text labeling -- added interactive SVG, that can be opend in RStudio (see itmap) -- added map compass (tm_compass) -- added text aesthetics size and col +- added interactive SVG, that can be opened in RStudio (see itmap) +- added map compass (`tm_compass()`) +- added text aesthetics `size` and `col` - added automatic map coloring -- added earth boundary, which is useful for projected world maps +- added earth boundary, which is useful for projected world maps `World` - added warped grid lines (e.g. long-lat lines can be shown in projected maps) -- added new color scale modes (enabled with style="cat", "cont", and "order") -- added save_tmap +- added new color scale modes (enabled with `style="cat"`, "cont", and "order") +- added `save_tmap()` - added smooth_map, smooth_raster_cover, sample_dots, points_to_raster and poly_to_raster - added read_GPX - improved automatic layout regarding title, legend, and map attributes - layer arguments, e.g. palette, can take multiple values for small multiples - improved grid lines (labels can also be placed outside frame) -- arguments free.coords and drop.shapes of tm_facets working +- arguments `free.coords` and `drop.shapes` of `tm_facets()` working - updated examples and vignette -- fixed viewport bug -- see ?tmap for a structured overview of all tmap functions +- fixed `viewport` bug +- see `?tmap` for a structured overview of all tmap functions # tmap 1.0 -- added tm_credits and tm_scale_bar -- added is.master argument to tm_shape, that determines which shape is the master -- added unit and unit.size arguments to tm_shape that correlates the coordinates with the desired units -- added tm_polygons, which is a combination of tm_fill and tm_borders +- added `tm_credits()` and `tm_scale_bar()` +- added `is.master` argument to `tm_shape()`, that determines which shape is the master +- added `unit` and `unit.size` arguments to `tm_shape()` that correlates the coordinates with the desired units +- added `tm_polygons()`, which is a combination of `tm_fill()` and `tm_borders()` - fixed several small bugs # tmap 0.8 -- added tm_raster -- improved legend behaviour: legend titles should be set in the layer functions (instead of in tm_layout) -- removed crop_shape, since raster::crop does the same job, but, but faster -- out-of-scope functions migrated to spatialToolbox package, available on github.com/mtennekes/spatialToolbox +- added `tm_raster()` +- improved legend behavior: legend titles should be set in the layer functions (instead of in `tm_layout()`) +- removed `crop_shape()`, since `raster::crop()` does the same job, but, but faster +- out-of-scope functions migrated to spatialToolbox package, available on https://github.com/mtennekes/spatialToolbox # tmap 0.7.1 -- fixed big in scale parameter (global scale set in tm_layout) +- fixed bug in `scale` parameter (global scale set in `tm_layout()`) # tmap 0.7 -- enhanced small multiples (tm_facets) with respect to scaling and free coordinate scales -- added alpha argument to tm layers for transparency +- enhanced small multiples (`tm_facets()`) with respect to scaling and free coordinate scales +- added `alpha` argument to `tm_layers()` for transparency - added text shadow argument -- added function split to split a shape object and sbind to combine shape objects. -- added automatic legend positioning when legend.position=NULL +- added function `split()` to split a shape object and `sbind()` to combine shape objects. +- added automatic legend positioning when `legend.position = NULL` - improved number formatting in legend -- improved inner.margins and outer.margins. Both can take one value (e.g. outer.margins=0 rather than outer.margins=c(0,0,0,0)) -- improved qtm: tm_facets parameters working, and also fixed scale parameter bug -- improved all examples for approx_areas, calc_densities -- fixed bug regarding drawing a frame with outer.margins=0. -- fixed bug in plotting blubbles -- improved temp file handling in animation_tmap +- improved `inner.margins` and `outer.margins`. Both can take one value (e.g. `outer.margins=0` rather than `outer.margins=c(0,0,0,0))` +- improved `qtm()`: `tm_facets()` parameters working, and also fixed scale parameter bug +- improved all examples for `approx_areas`, `calc_densities` +- fixed bug regarding drawing a frame with `outer.margins=0`. +- fixed bug in plotting bubbles +- improved temp file handling in `animation_tmap()` - added functions to get and set polygon directions, and to calculate the intersection ratios of polygons (intersection_shapes) # tmap 0.6 diff --git a/R/qtm.R b/R/qtm.R index 25143051..45e11dba 100644 --- a/R/qtm.R +++ b/R/qtm.R @@ -1,8 +1,8 @@ #' Quick thematic map plot #' -#' Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking [tmap-element()]s. Without arguments or with a search term, this functions draws an interactive map. +#' Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking [`tmap-element`]s. Without arguments or with a search term, this functions draws an interactive map. #' -#' The first argument is a shape object (normally specified by [tm_shape()]). The next arguments, from `fill` to `raster`, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as [tm_polygons()], can be specified (see `...`). It is also possible to stack [tmap-element()]s on a `qtm` plot. See examples. +#' The first argument is a shape object (normally specified by [tm_shape()]). The next arguments, from `fill` to `raster`, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as [tm_polygons()], can be specified (see `...`). It is also possible to stack [`tmap-element`]s on a `qtm` plot. See examples. #' #' By default, a scale bar is shown. This option can be set with [tmap_options()] (argument `qtm.scalebar`). A minimap is shown by default when `qtm` is called without arguments of with a search term. This option can be set with [tmap_options()] (argument `qtm.minimap`). #' @@ -10,14 +10,14 @@ #' \itemize{ #' \item shape object, which is an object from a class defined by the [`sf`][`sf::sf`] or [`stars`][stars::st_as_stars()] package. Objects from the packages `sp` and `raster` are also supported, but discouraged. #' \item Not specified, i.e. `qtm()` is executed. In this case a plain interactive map is shown. -#' \item A OSM search string, e.g. `qtm("Amsterdam")`. In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim) +#' \item An OpenStreetMap search string, e.g. `qtm("Amsterdam")`. In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim) #' } #' @param fill,col,size,shape,lwd,lty,fill_alpha,col_alpha Visual variables. #' @param by data variable name by which the data is split, or a vector of two variable names to split the data by two variables (where the first is used for the rows and the second for the columns). See also [tm_facets()] -#' @param scale numeric value that serves as the global scale parameter. All font sizes, symbol sizes, border widths, and line widths are controlled by this value. The parameters `symbols.size`, `text.size`, and `lines.lwd` can be scaled seperately with respectively `symbols.scale`, `text.scale`, and `lines.scale`. See also `...`. +#' @param scale numeric value that serves as the global scale parameter. All font sizes, symbol sizes, border widths, and line widths are controlled by this value. The parameters `symbols.size`, `text.size`, and `lines.lwd` can be scaled separately with respectively `symbols.scale`, `text.scale`, and `lines.scale`. See also `...`. #' @param title main title. For legend titles, use `X.style`, where X is the layer name (see `...`). #' @param crs Either a [`crs`][sf::st_crs()] object or a character value (`PROJ.4` character string). By default, the projection is used that is defined in the `shp` object itself. -#' @param bbox bounding box. Arugment passed on to [tm_shape()] +#' @param bbox bounding box. Argument passed on to [tm_shape()] #' @param basemaps name(s) of the provider or an URL of a tiled basemap. It is a shortcut to [tm_basemap()]. Set to `NULL` to disable basemaps. By default, it is set to the tmap option `basemaps`. #' @param overlays name(s) of the provider or an URL of a tiled overlay map. It is a shortcut to [tm_tiles()]. #' @param zindex zindex @@ -26,7 +26,7 @@ #' @param style Layout options (see [tm_layout()]) that define the style. See [tmap_style()] for details. #' @param format Layout options (see [tm_layout()]) that define the format. See [tmap_format()] for details. #' @param ... arguments passed on to the `tm_*` functions. The prefix of these arguments should be with the layer function name without `"tm_"` and a period. For instance, the palette for polygon fill color is called `fill.palette`. The following prefixes are supported: `shape.`, `fill.`, `borders.`, `polygons.`, `symbols.`, `dots.`, `lines.`, `raster.`, `text.`, `layout.`, `grid.`, `facets.`, and `view.`. Arguments that have a unique name, i.e. that does not exist in any other layer function, e.g. `convert2density`, can also be called without prefix. -#' @return [tmap-element()] +#' @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} diff --git a/R/shapeTM.R b/R/shapeTM.R index a49a7b31..789132b2 100644 --- a/R/shapeTM.R +++ b/R/shapeTM.R @@ -2,9 +2,9 @@ #' #' Internal tmap function to create a tmap shape #' -#' @param shp shp -#' @param tmapID tmapID -#' @param bbox bbox +#' @param shp Shape file +#' @param tmapID tmap Identifier +#' @param bbox bounding box #' @export #' @keywords internal shapeTM = function(shp, tmapID = NULL, bbox = NULL, ...) { diff --git a/R/tm_facets.R b/R/tm_facets.R index b6e2be7f..60de1c11 100644 --- a/R/tm_facets.R +++ b/R/tm_facets.R @@ -20,7 +20,7 @@ #' @param textNA Text used for facets of missing values. #' @param scale.factor Number that determines how the elements (e.g. font sizes, symbol sizes, line widths) of the small multiples are scaled in relation to the scaling factor of the shapes. The elements are scaled to the `scale.factor`th root of the scaling factor of the shapes. So, for `scale.factor=1`, they are scaled proportional to the scaling of the shapes. Since elements, especially text, are often too small to read, a higher value is recommended. By default, `scale.factor=2`. #' @param type `"grid"`, `"wrap"` or `"stack"` -#' @param along deceprated Please use `tm_facets_page()` +#' @param along deprecated Please use `tm_facets_page()` #' @export #' @rdname tm_facets #' @name tm_facets @@ -104,7 +104,7 @@ tm_facets_grid = function(rows = NULL, #' @export #' @rdname tm_facets -#' @param ... paseed on to `tm_facets()` +#' @param ... passed on to `tm_facets()` #' @name tm_facets_wrap tm_facets_wrap = function(by = "VARS__", nrows = NA, diff --git a/R/tm_layers_aux.R b/R/tm_layers_aux.R index 07e0bb9a..0874fa49 100644 --- a/R/tm_layers_aux.R +++ b/R/tm_layers_aux.R @@ -55,7 +55,7 @@ tm_graticules = function(x = NA, #' Coordinate grid / graticule lines #' -#' Creates a [`tmap-element`] that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. By default, `tm_grid()` draws horizontal and vertical lines acording to the coordinate system of the (master) shape object. Latitude and longitude graticules are drawn with `tm_graticules()`. +#' Creates a [`tmap-element`] that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. By default, `tm_grid()` draws horizontal and vertical lines according to the coordinate system of the (master) shape object. Latitude and longitude graticules are drawn with `tm_graticules()`. #' #' @param x X coordinates for vertical grid lines. If `NA`, it is specified with a pretty scale and `n.x`. #' @param y Y coordinates for horizontal grid lines. If `NA`, it is specified with a pretty scale and `n.y`. diff --git a/R/tm_layers_cartogram.R b/R/tm_layers_cartogram.R index 3b3b557f..75fadf41 100644 --- a/R/tm_layers_cartogram.R +++ b/R/tm_layers_cartogram.R @@ -5,7 +5,7 @@ #' @param size,size.scale,size.legend,size.free Transformation variable that determines the size of the polygons. #' @param plot.order Specification in which order the spatial features are drawn. See [tm_plot_order()] for details. #' @param trans.args lists that are passed on to internal transformation function -#' @param ... passd on to [tm_polygons()] +#' @inheritDotParams tm_polygons #' @export tm_cartogram = function(size = 1, size.scale = tm_scale(), diff --git a/R/tm_layout.R b/R/tm_layout.R index 8d044567..0728c1f0 100644 --- a/R/tm_layout.R +++ b/R/tm_layout.R @@ -59,7 +59,7 @@ tm_layout = function( #' @param control.bases base layers #' @param control.overlays overlay layers #' @param set.bounds logical that determines whether maximum bounds are set, or a bounding box. Not applicable in plot mode. In view mode, this is passed on to [setMaxBounds()][leaflet::setMaxBounds()] -#' @param set.view numeric vector that determines the view. Either a vector of three: lng, lat, and zoom, or a single value: zoom. See [setView()][leaflet::setView()]. Only applicable if `bbox` is not specified +#' @param set.view numeric vector that determines the view. Either a vector of three: `lng`, `lat`, and `zoom`, or a single value: `zoom`. See [setView()][leaflet::setView()]. Only applicable if `bbox` is not specified #' @param set.zoom.limits numeric vector of two that set the minimum and maximum zoom levels (see [tileOptions()][leaflet::tileOptions()]). #' @param leaflet.options options passed on to [leafletOptions()][leaflet::leafletOptions()] #' @export diff --git a/R/tm_scale_.R b/R/tm_scale_.R index 60111ecf..ecc32622 100644 --- a/R/tm_scale_.R +++ b/R/tm_scale_.R @@ -57,7 +57,7 @@ tm_scale_ordinal = function(n.max = 30, #' @param n.max Maximum number of categories (factor levels). In case there are more, they are grouped into `n.max` groups. #' @param values (generic scale argument) The visual values. For colors (e.g. `fill` or `col` for `tm_polygons()`) this is a palette name from the `cols4all` package (see [cols4all::c4a()]) or vector of colors, for size (e.g. `size` for `tm_symbols()`) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. `shape` for [tm_symbols()]) these are a set of symbols, etc. The tmap option `values.var` contains the default values per visual variable and in some cases also per data type. #' @param values.repeat (generic scale argument) Should the values be repeated in case there are more categories? -#' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a grey scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark grey to light grey are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. +#' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a gray scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark gray to light gray are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle gray (`"gray50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. #' @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.na (generic scale argument) Value used for missing values. See tmap option `"value.na"` for defaults per visual variable. #' @param value.null (generic scale argument) Value used for NULL values. See tmap option `"value.null"` for defaults per visual variable. Null data values occur when out-of-scope features are shown (e.g. for a map of Europe showing a data variable per country, the null values are applied to countries outside Europe). @@ -101,7 +101,7 @@ tm_scale_categorical = function(n.max = 30, #' @param as.count Should the data variable be processed as a count variable? For instance, if `style = "pretty"`, `n = 2`, and the value range of the variable is 0 to 10, then the column classes for `as.count = TRUE` are 0; 1 to 5; 6 to 10 (note that 0 is regarded as an own category) whereas for `as.count = FALSE` they are 0 to 5; 5 to 10. Only applicable if `style` is `"pretty"`, `"fixed"`, or `"log10_pretty"`. By default, `TRUE` if `style` is one of these, and the variable is an integer. #' @param values (generic scale argument) The visual values. For colors (e.g. `fill` or `col` for [tm_polygons()]) this is a palette name from the `cols4all` package (see [cols4all::c4a()]) or vector of colors, for size (e.g. `size` for `tm_symbols`) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. `shape` for `tm_symbols`) these are a set of symbols, etc. The tmap option `values.var` contains the default values per visual variable and in some cases also per data type. #' @param values.repeat (generic scale argument) Should the values be repeated in case there are more categories? -#' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a grey scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark grey to light grey are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. +#' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a gray scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark gray to light gray are used (more precisely `"gray25"` to `"gray75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. #' @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.na (generic scale argument) Value used for missing values. See tmap option `"value.na"` for defaults per visual variable. #' @param value.null (generic scale argument) Value used for NULL values. See tmap option `"value.null"` for defaults per visual variable. Null data values occur when out-of-scope features are shown (e.g. for a map of Europe showing a data variable per country, the null values are applied to countries outside Europe). @@ -140,7 +140,7 @@ tm_scale_intervals = function(n = 5, #' @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. #' @param values (generic scale argument) The visual values. For colors (e.g. `fill` or `col` for [tm_polygons()]) this is a palette name from the `cols4all` package (see [cols4all::c4a()]) or vector of colors, for size (e.g. `size` for `tm_symbols`) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. `shape` for [tm_symbols()]) these are a set of symbols, etc. The tmap option `values.var` contains the default values per visual variable and in some cases also per data type. #' @param values.repeat (generic scale argument) Should the values be repeated in case there are more categories? -#' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a grey scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark grey to light grey are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. +#' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a gray scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark gray to light gray are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. #' @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.na (generic scale argument) Value used for missing values. See tmap option `"value.na"` for defaults per visual variable. #' @param value.null (generic scale argument) Value used for NULL values. See tmap option `"value.null"` for defaults per visual variable. Null data values occur when out-of-scope features are shown (e.g. for a map of Europe showing a data variable per country, the null values are applied to countries outside Europe). @@ -179,7 +179,7 @@ tm_scale_discrete = function(ticks = NA, #' @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. #' @param values (generic scale argument) The visual values. For colors (e.g. `fill` or `col` for [tm_polygons()]) this is a palette name from the `cols4all` package (see [cols4all::c4a()]) or vector of colors, for size (e.g. `size` for [tm_symbols()]) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. `shape` for [tm_symbols()]) these are a set of symbols, etc. The tmap option `values.var` contains the default values per visual variable and in some cases also per data type. #' @param values.repeat (generic scale argument) Should the values be repeated in case there are more categories? -#' @param values.range (generic scale argument) Range of the values, especially useful for color palettes. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a grey scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark grey to light grey are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. +#' @param values.range (generic scale argument) Range of the values, especially useful for color palettes. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a gray scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark gray to light gray are used (more precisely `"grey25"` to `"grey75"`), and `0, 0.5` means that only colors are used from black to middle gray (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`. #' @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.na (generic scale argument) Value used for missing values. See tmap option `"value.na"` for defaults per visual variable. #' @param value.null (generic scale argument) Value used for NULL values. See tmap option `"value.null"` for defaults per visual variable. Null data values occur when out-of-scope features are shown (e.g. for a map of Europe showing a data variable per country, the null values are applied to countries outside Europe). diff --git a/R/tmap_options.R b/R/tmap_options.R index c5e8938a..9f2b3017 100644 --- a/R/tmap_options.R +++ b/R/tmap_options.R @@ -710,30 +710,30 @@ complete_options = function(x, o) { #' #' @param ... See details #' @details -#' | option | description | -#' | ------ | ----------- | -#' | modes | Mode specific options. It is a named list where names correspond to the available modes. Each item is a list of options. | -#' | crs | Map crs (see [tm_shape()]). `NA` means the crs is specified in [tm_shape()]. The crs that is used by the transformation functions is defined in [tm_shape()].| -#' | facet.max | Maximum number of facets | -#' | facet.flip | Should facets be flipped (in case of facet wrap)? This can also be set via [tm_facets_flip()] | -#' | raster.max.cells | Maximum number of raster grid cells | -#' | show.messages | Show messages? | -#' | show.warnings | Show warnings? | -#' | output.format | Output format | -#' | output.size | Output size | -#' | output.dpi | Output dpi | -#' | output.dpi.animation | Output dpi for animations | -#' | value.const | Default visual value constants e.g. the default fill color for `tm_shape(World) + tm_polygons()`. A list is required with per visual variable a value. | -#' | value.na | Default visual values that are used to visualize NA data values. A list is required with per visual variable a value.| -#' | value.null | Default visual values that are used to visualize null (out-of-scope) data values. A list is required with per visual variable a value.| -#' | value.blank | Default visual values that correspond to blank. For color these are `"#00000000"` meaning transparent. A list is required with per visual variable a value. | -#' | values.var | Default values when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. | -#' | values.range | Default range for values. See `values.range` of [tm_scale_categorical()]. A list is required with per visual variable a value. -#' | value.neutral | Default values for when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. | | -#' | scales.var | Default scales. | -#' | label.format | Format for the labels (was `legend.format` in tmap v3) | -#' | label.na | Default label for missing values | -#' See [tm_layout()] for layout specific options +#' | option | description | +#' | ------ | ----------- | +#' | `modes` | Mode specific options. It is a named list where names correspond to the available modes. Each item is a list of options. | +#' | `crs` | Map crs (see [tm_shape()]). `NA` means the crs is specified in [tm_shape()]. The crs that is used by the transformation functions is defined in [tm_shape()].| +#' | `facet.max` | Maximum number of facets | +#' | `facet.flip` | Should facets be flipped (in case of facet wrap)? This can also be set via [tm_facets_flip()] | +#' | `raster.max.cells` | Maximum number of raster grid cells | +#' | `show.messages` | Show messages? | +#' | `show.warnings` | Show warnings? | +#' | `output.format` | Output format | +#' | `output.size` | Output size | +#' | `output.dpi` | Output dpi | +#' | `output.dpi.animation` | Output dpi for animations | +#' | `value.const` | Default visual value constants e.g. the default fill color for `tm_shape(World) + tm_polygons()`. A list is required with per visual variable a value. | +#' | `value.na` | Default visual values that are used to visualize NA data values. A list is required with per visual variable a value.| +#' | `value.null` | Default visual values that are used to visualize null (out-of-scope) data values. A list is required with per visual variable a value.| +#' | `value.blank` | Default visual values that correspond to blank. For color these are `"#00000000"` meaning transparent. A list is required with per visual variable a value. | +#' | `values.var` | Default values when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. | +#' | `values.range` | Default range for values. See `values.range` of [tm_scale_categorical()]. A list is required with per visual variable a value. +#' | `value.neutral` | Default values for when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. | | +#' | `scales.var` | Default scales. | +#' | `label.format` | Format for the labels (was `legend.format` in tmap v3). | +#' | `label.na` | Default label for missing values. | +#' See [tm_layout()] for layout specific options. #' @name tmap_options #' @rdname tmap_options #' @export diff --git a/R/tmap_save.R b/R/tmap_save.R index bb5ba369..4912ecb9 100644 --- a/R/tmap_save.R +++ b/R/tmap_save.R @@ -15,7 +15,7 @@ #' @param insets_vp [`viewport`][grid::viewport()] of an inset map, or a list of [`viewport`][grid::viewport()]s of multiple inset maps. The number of viewports should be equal to the number of tmap objects specified with `insets_tm`. #' @param add.titles add titles to leaflet object. #' @param in.iframe should an interactive map be saved as an iframe? If so, two HTML files will be saved; one small parent HTML file with the iframe container, and one large child HTML file with the actual widget. See [widgetframe::saveWidgetframe()] for details. By default `FALSE` which means that one large HTML file is saved (see [saveWidget()][htmlwidgets::saveWidget()]). -#' @param selfcontained when an interactive map is saved, should the resources (e.g. Javascript libraries) be contained in the HTML file? If `FALSE`, they are placed in an adjacent directory (see also [htmlwidgets::saveWidget()]). Note that the HTML file will often still be large when `selfcontained = FALSE`, since the map data (polygons and popups), which are also contained in the HTML file, usually take more space then the map resources. +#' @param selfcontained when an interactive map is saved, should the resources (e.g. JavaScript libraries) be contained in the HTML file? If `FALSE`, they are placed in an adjacent directory (see also [htmlwidgets::saveWidget()]). Note that the HTML file will often still be large when `selfcontained = FALSE`, since the map data (polygons and popups), which are also contained in the HTML file, usually take more space then the map resources. #' @param verbose Deprecated. It is now controlled by the tmap option `show.messages` (see [tmap_options()]) #' @param ... arguments passed on to device functions or to [`saveWidget()`][htmlwidgets::saveWidget()] or [`saveWidgetFrame()`][widgetframe::saveWidgetframe()] #' @importFrom htmlwidgets saveWidget diff --git a/README.md b/README.md index a5f7f2fb..6021aa54 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # tmap: thematic maps in R -[![R-CMD-check](https://github.com/r-tmap/tmap/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-tmap/tmap/actions/workflows/R-CMD-check.yaml) +[![R CMD CHECK](https://github.com/r-tmap/tmap/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-tmap/tmap/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/r-tmap/tmap/branch/master/graph/badge.svg)](https://app.codecov.io/gh/r-tmap/tmap?branch=master) [![CRAN](http://www.r-pkg.org/badges/version/tmap)](https://cran.r-project.org/package=tmap) -[![cran checks](https://cranchecks.info/badges/worst/tmap)](https://cran.r-project.org/web/checks/check_results_tmap.html) +[![CRAN checks](https://cranchecks.info/badges/worst/tmap)](https://cran.r-project.org/web/checks/check_results_tmap.html) [![Downloads](http://cranlogs.r-pkg.org/badges/tmap?color=brightgreen)](https://www.r-pkg.org:443/pkg/tmap) [![License](https://img.shields.io/badge/License-GPL%20v3-brightgreen.svg?style=flat)](http://www.gnu.org/licenses/gpl-3.0.html) @@ -121,12 +121,12 @@ Other resources * [Working with Spatial Data and using tmap, Samantha A. Alger][22] * [Computer World: Mapping in R just got a whole lot easier][18] * [National Socio-Environmental Synthesis Center: Maps in R][19] -* [Introduction to visualising spatial data in R][9] -* [Blog post StatialControl][7] +* [Introduction to visualizing spatial data in R][9] +* [Blog post SpatialControl][7] * [Blog post TWIAV][8] * [Computer World: Create maps in R in 10 (fairly) easy steps][12] * [Computer World: Great R packages for data import, wrangling and visualization][17] -* [Tutorial Visualising spatial data: from base to shiny - workshop][15] +* [Tutorial Visualizing spatial data: from base to shiny - workshop][15] * [Stack Overflow questions (#tmap)][16] diff --git a/examples/tm_polygons.R b/examples/tm_polygons.R index 7ea4bf41..b9104027 100644 --- a/examples/tm_polygons.R +++ b/examples/tm_polygons.R @@ -46,7 +46,7 @@ tm_shape(World) + tm_fill("darkolivegreen3") + tm_format("World", title="A green # Borders only tm_shape(World) + tm_borders() -# Data variable containing colours values +# Data variable containing color values World$isNLD = ifelse(World$name=="Netherlands", "darkorange", "darkolivegreen3") tm_shape(World) + tm_fill("isNLD") + diff --git a/man/qtm.Rd b/man/qtm.Rd index 10373ebb..ffa0f594 100644 --- a/man/qtm.Rd +++ b/man/qtm.Rd @@ -34,20 +34,20 @@ qtm( \itemize{ \item shape object, which is an object from a class defined by the \code{\link[sf:sf]{sf}} or \code{\link[stars:st_as_stars]{stars}} package. Objects from the packages \code{sp} and \code{raster} are also supported, but discouraged. \item Not specified, i.e. \code{qtm()} is executed. In this case a plain interactive map is shown. -\item A OSM search string, e.g. \code{qtm("Amsterdam")}. In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim) +\item An OpenStreetMap search string, e.g. \code{qtm("Amsterdam")}. In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim) }} \item{fill, col, size, shape, lwd, lty, fill_alpha, col_alpha}{Visual variables.} \item{by}{data variable name by which the data is split, or a vector of two variable names to split the data by two variables (where the first is used for the rows and the second for the columns). See also \code{\link[=tm_facets]{tm_facets()}}} -\item{scale}{numeric value that serves as the global scale parameter. All font sizes, symbol sizes, border widths, and line widths are controlled by this value. The parameters \code{symbols.size}, \code{text.size}, and \code{lines.lwd} can be scaled seperately with respectively \code{symbols.scale}, \code{text.scale}, and \code{lines.scale}. See also \code{...}.} +\item{scale}{numeric value that serves as the global scale parameter. All font sizes, symbol sizes, border widths, and line widths are controlled by this value. The parameters \code{symbols.size}, \code{text.size}, and \code{lines.lwd} can be scaled separately with respectively \code{symbols.scale}, \code{text.scale}, and \code{lines.scale}. See also \code{...}.} \item{title}{main title. For legend titles, use \code{X.style}, where X is the layer name (see \code{...}).} \item{crs}{Either a \code{\link[sf:st_crs]{crs}} object or a character value (\code{PROJ.4} character string). By default, the projection is used that is defined in the \code{shp} object itself.} -\item{bbox}{bounding box. Arugment passed on to \code{\link[=tm_shape]{tm_shape()}}} +\item{bbox}{bounding box. Argument passed on to \code{\link[=tm_shape]{tm_shape()}}} \item{basemaps}{name(s) of the provider or an URL of a tiled basemap. It is a shortcut to \code{\link[=tm_basemap]{tm_basemap()}}. Set to \code{NULL} to disable basemaps. By default, it is set to the tmap option \code{basemaps}.} @@ -66,13 +66,13 @@ qtm( \item{...}{arguments passed on to the \verb{tm_*} functions. The prefix of these arguments should be with the layer function name without \code{"tm_"} and a period. For instance, the palette for polygon fill color is called \code{fill.palette}. The following prefixes are supported: \code{shape.}, \code{fill.}, \code{borders.}, \code{polygons.}, \code{symbols.}, \code{dots.}, \code{lines.}, \code{raster.}, \code{text.}, \code{layout.}, \code{grid.}, \code{facets.}, and \code{view.}. Arguments that have a unique name, i.e. that does not exist in any other layer function, e.g. \code{convert2density}, can also be called without prefix.} } \value{ -\code{\link[=tmap-element]{tmap-element()}} +A \code{\link{tmap-element}} } \description{ -Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking \code{\link[=tmap-element]{tmap-element()}}s. Without arguments or with a search term, this functions draws an interactive map. +Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking \code{\link{tmap-element}}s. Without arguments or with a search term, this functions draws an interactive map. } \details{ -The first argument is a shape object (normally specified by \code{\link[=tm_shape]{tm_shape()}}). The next arguments, from \code{fill} to \code{raster}, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as \code{\link[=tm_polygons]{tm_polygons()}}, can be specified (see \code{...}). It is also possible to stack \code{\link[=tmap-element]{tmap-element()}}s on a \code{qtm} plot. See examples. +The first argument is a shape object (normally specified by \code{\link[=tm_shape]{tm_shape()}}). The next arguments, from \code{fill} to \code{raster}, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as \code{\link[=tm_polygons]{tm_polygons()}}, can be specified (see \code{...}). It is also possible to stack \code{\link{tmap-element}}s on a \code{qtm} plot. See examples. By default, a scale bar is shown. This option can be set with \code{\link[=tmap_options]{tmap_options()}} (argument \code{qtm.scalebar}). A minimap is shown by default when \code{qtm} is called without arguments of with a search term. This option can be set with \code{\link[=tmap_options]{tmap_options()}} (argument \code{qtm.minimap}). } diff --git a/man/shapeTM.Rd b/man/shapeTM.Rd index f2525ad4..568ae8e7 100644 --- a/man/shapeTM.Rd +++ b/man/shapeTM.Rd @@ -7,11 +7,11 @@ shapeTM(shp, tmapID = NULL, bbox = NULL, ...) } \arguments{ -\item{shp}{shp} +\item{shp}{Shape file} -\item{tmapID}{tmapID} +\item{tmapID}{tmap Identifier} -\item{bbox}{bbox} +\item{bbox}{bounding box} } \description{ Internal tmap function to create a tmap shape diff --git a/man/tm_cartogram.Rd b/man/tm_cartogram.Rd index 01f60985..b42fbc77 100644 --- a/man/tm_cartogram.Rd +++ b/man/tm_cartogram.Rd @@ -21,7 +21,25 @@ tm_cartogram( \item{trans.args}{lists that are passed on to internal transformation function} -\item{...}{passd on to \code{\link[=tm_polygons]{tm_polygons()}}} +\item{...}{ + Arguments passed on to \code{\link[=tm_polygons]{tm_polygons}} + \describe{ + \item{\code{fill,fill.scale,fill.legend,fill.free}}{Visual variable that determines the fill color. See details.} + \item{\code{col,col.scale,col.legend,col.free}}{Visual variable that determines the border color. See details.} + \item{\code{lwd,lwd.scale,lwd.legend,lwd.free}}{Visual variable that determines the line width. See details.} + \item{\code{lty,lty.scale,lty.legend,lty.free}}{Visual variable that determines the line type. See details.} + \item{\code{fill_alpha,fill_alpha.scale,fill_alpha.legend,fill_alpha.free}}{Visual variable that determines the fill color alpha transparency See details.} + \item{\code{col_alpha,col_alpha.scale,col_alpha.legend,col_alpha.free}}{Visual variable that determines the border color alpha transparency. See details.} + \item{\code{linejoin,lineend}}{Line join and line end. See \link[grid:gpar]{gpar()} for details.} + \item{\code{trans.args,mapping.args}}{lists that are passed on to internal transformation and mapping functions respectively} + \item{\code{zindex}}{Map layers are drawn on top of each other. The \code{zindex} numbers (one for each map layer) determines the stacking order. By default the map layers are drawn in the order they are called.} + \item{\code{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{\code{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{\code{popup.vars}}{names of data variables that are shown in the popups in \code{"view"} mode. Set popup.vars to \code{TRUE} to show all variables in the shape object. Set popup.vars to \code{FALSE} to disable popups. Set popup.vars to a character vector of variable names to those those variables in the popups. The default (\code{NA}) depends on whether visual variables (e.g.\code{col}) are used. If so, only those are shown. If not all variables in the shape object are shown.} + \item{\code{popup.format}}{list of formatting options for the popup values. See the argument \code{legend.format} for options. 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{\code{hover}}{name of the data variable that specifies the hover labels} + \item{\code{id}}{name of the data variable that specifies the indices of the spatial features. Only used for \code{"view"} mode.} + }} } \description{ Map layer that draws a cartogram diff --git a/man/tm_facets.Rd b/man/tm_facets.Rd index 382ec1b1..bb819b1e 100644 --- a/man/tm_facets.Rd +++ b/man/tm_facets.Rd @@ -85,9 +85,9 @@ tm_facets_flip() \item{type}{\code{"grid"}, \code{"wrap"} or \code{"stack"}} -\item{along}{deceprated Please use \code{tm_facets_page()}} +\item{along}{deprecated Please use \code{tm_facets_page()}} -\item{...}{paseed on to \code{tm_facets()}} +\item{...}{passed on to \code{tm_facets()}} } \description{ Specify facets. \code{tm_facets()} is the core function, but recommended is to use \code{tm_facets_wrap()}, \code{tm_facets_stack()} or \code{tm_facets_grid()}. The former two specify facets for one grouping variable (so one faceting dimension). The difference is that wrap may place facets in multiple rows and columns whereas \code{tm_facets_stack()} stacks the facets either horizontally or vertically. \code{tm_facets_grid()} supports up to three faceting dimensions. diff --git a/man/tm_grid.Rd b/man/tm_grid.Rd index af06148f..520d7db1 100644 --- a/man/tm_grid.Rd +++ b/man/tm_grid.Rd @@ -109,7 +109,7 @@ tm_grid( \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).} } \description{ -Creates a \code{\link{tmap-element}} that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. By default, \code{tm_grid()} draws horizontal and vertical lines acording to the coordinate system of the (master) shape object. Latitude and longitude graticules are drawn with \code{tm_graticules()}. +Creates a \code{\link{tmap-element}} that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. By default, \code{tm_grid()} draws horizontal and vertical lines according to the coordinate system of the (master) shape object. Latitude and longitude graticules are drawn with \code{tm_graticules()}. } \examples{ current.mode <- tmap_mode("plot") diff --git a/man/tm_polygons.Rd b/man/tm_polygons.Rd index 400dbe30..5dc31ff5 100644 --- a/man/tm_polygons.Rd +++ b/man/tm_polygons.Rd @@ -146,7 +146,7 @@ tm_shape(World) + tm_fill("darkolivegreen3") + tm_format("World", title="A green # Borders only tm_shape(World) + tm_borders() -# Data variable containing colours values +# Data variable containing color values World$isNLD = ifelse(World$name=="Netherlands", "darkorange", "darkolivegreen3") tm_shape(World) + tm_fill("isNLD") + diff --git a/man/tm_scale_categorical.Rd b/man/tm_scale_categorical.Rd index 4ab734ae..6d5a067c 100644 --- a/man/tm_scale_categorical.Rd +++ b/man/tm_scale_categorical.Rd @@ -46,7 +46,7 @@ tm_scale_categorical( \item{values.repeat}{(generic scale argument) Should the values be repeated in case there are more categories?} -\item{values.range}{(generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a grey scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark grey to light grey are used (more precisely \code{"grey25"} to \code{"grey75"}), and \verb{0, 0.5} means that only colors are used from black to middle grey (\code{"grey50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} +\item{values.range}{(generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a gray scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark gray to light gray are used (more precisely \code{"grey25"} to \code{"grey75"}), and \verb{0, 0.5} means that only colors are used from black to middle gray (\code{"gray50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} \item{values.scale}{(generic scale argument) Scaling of the values. Only useful for size-related visual variables, such as \code{size} of \code{\link[=tm_symbols]{tm_symbols()}} and \code{lwd} of \code{\link[=tm_lines]{tm_lines()}}.} diff --git a/man/tm_scale_continuous.Rd b/man/tm_scale_continuous.Rd index cd9f71d2..1cfa8d8b 100644 --- a/man/tm_scale_continuous.Rd +++ b/man/tm_scale_continuous.Rd @@ -47,7 +47,7 @@ tm_scale_continuous_log1p(...) \item{values.repeat}{(generic scale argument) Should the values be repeated in case there are more categories?} -\item{values.range}{(generic scale argument) Range of the values, especially useful for color palettes. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a grey scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark grey to light grey are used (more precisely \code{"grey25"} to \code{"grey75"}), and \verb{0, 0.5} means that only colors are used from black to middle grey (\code{"grey50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} +\item{values.range}{(generic scale argument) Range of the values, especially useful for color palettes. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a gray scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark gray to light gray are used (more precisely \code{"grey25"} to \code{"grey75"}), and \verb{0, 0.5} means that only colors are used from black to middle gray (\code{"grey50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} \item{values.scale}{(generic scale argument) Scaling of the values. Only useful for size-related visual variables, such as \code{size} of \code{\link[=tm_symbols]{tm_symbols()}} and \code{lwd} of \code{\link[=tm_lines]{tm_lines()}}.} diff --git a/man/tm_scale_discrete.Rd b/man/tm_scale_discrete.Rd index ef0495ef..8c0a2ebd 100644 --- a/man/tm_scale_discrete.Rd +++ b/man/tm_scale_discrete.Rd @@ -29,7 +29,7 @@ tm_scale_discrete( \item{values.repeat}{(generic scale argument) Should the values be repeated in case there are more categories?} -\item{values.range}{(generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a grey scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark grey to light grey are used (more precisely \code{"grey25"} to \code{"grey75"}), and \verb{0, 0.5} means that only colors are used from black to middle grey (\code{"grey50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} +\item{values.range}{(generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a gray scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark gray to light gray are used (more precisely \code{"grey25"} to \code{"grey75"}), and \verb{0, 0.5} means that only colors are used from black to middle grey (\code{"grey50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} \item{values.scale}{(generic scale argument) Scaling of the values. Only useful for size-related visual variables, such as \code{size} of \code{\link[=tm_symbols]{tm_symbols()}} and \code{lwd} of \code{\link[=tm_lines]{tm_lines()}}.} diff --git a/man/tm_scale_intervals.Rd b/man/tm_scale_intervals.Rd index 1eaebc60..629c9136 100644 --- a/man/tm_scale_intervals.Rd +++ b/man/tm_scale_intervals.Rd @@ -44,7 +44,7 @@ tm_scale_intervals( \item{values.repeat}{(generic scale argument) Should the values be repeated in case there are more categories?} -\item{values.range}{(generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a grey scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark grey to light grey are used (more precisely \code{"grey25"} to \code{"grey75"}), and \verb{0, 0.5} means that only colors are used from black to middle grey (\code{"grey50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} +\item{values.range}{(generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as \code{c(0, 1)}. For instance, when a gray scale is used for color (from black to white), \code{c(0,1)} means that all colors are used, \verb{0.25, 0.75} means that only colors from dark gray to light gray are used (more precisely \code{"gray25"} to \code{"gray75"}), and \verb{0, 0.5} means that only colors are used from black to middle grey (\code{"grey50"}). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option \code{values.range}.} \item{values.scale}{(generic scale argument) Scaling of the values. Only useful for size-related visual variables, such as \code{size} of \code{\link[=tm_symbols]{tm_symbols()}} and \code{lwd} of \code{\link[=tm_lines]{tm_lines()}}.} diff --git a/man/tm_view.Rd b/man/tm_view.Rd index ee8bc9fe..4a574edc 100644 --- a/man/tm_view.Rd +++ b/man/tm_view.Rd @@ -26,7 +26,7 @@ tm_view( \item{set.bounds}{logical that determines whether maximum bounds are set, or a bounding box. Not applicable in plot mode. In view mode, this is passed on to \link[leaflet:map-methods]{setMaxBounds()}} -\item{set.view}{numeric vector that determines the view. Either a vector of three: lng, lat, and zoom, or a single value: zoom. See \link[leaflet:map-methods]{setView()}. Only applicable if \code{bbox} is not specified} +\item{set.view}{numeric vector that determines the view. Either a vector of three: \code{lng}, \code{lat}, and \code{zoom}, or a single value: \code{zoom}. See \link[leaflet:map-methods]{setView()}. Only applicable if \code{bbox} is not specified} \item{set.zoom.limits}{numeric vector of two that set the minimum and maximum zoom levels (see \link[leaflet:map-options]{tileOptions()}).} diff --git a/man/tmap_options.Rd b/man/tmap_options.Rd index 18c5e1bf..2240c0f8 100644 --- a/man/tmap_options.Rd +++ b/man/tmap_options.Rd @@ -36,27 +36,27 @@ tmap options \details{ \tabular{ll}{ option \tab description \cr - modes \tab Mode specific options. It is a named list where names correspond to the available modes. Each item is a list of options. \cr - crs \tab Map crs (see \code{\link[=tm_shape]{tm_shape()}}). \code{NA} means the crs is specified in \code{\link[=tm_shape]{tm_shape()}}. The crs that is used by the transformation functions is defined in \code{\link[=tm_shape]{tm_shape()}}. \cr - facet.max \tab Maximum number of facets \cr - facet.flip \tab Should facets be flipped (in case of facet wrap)? This can also be set via \code{\link[=tm_facets_flip]{tm_facets_flip()}} \cr - raster.max.cells \tab Maximum number of raster grid cells \cr - show.messages \tab Show messages? \cr - show.warnings \tab Show warnings? \cr - output.format \tab Output format \cr - output.size \tab Output size \cr - output.dpi \tab Output dpi \cr - output.dpi.animation \tab Output dpi for animations \cr - value.const \tab Default visual value constants e.g. the default fill color for \code{tm_shape(World) + tm_polygons()}. A list is required with per visual variable a value. \cr - value.na \tab Default visual values that are used to visualize NA data values. A list is required with per visual variable a value. \cr - value.null \tab Default visual values that are used to visualize null (out-of-scope) data values. A list is required with per visual variable a value. \cr - value.blank \tab Default visual values that correspond to blank. For color these are \code{"#00000000"} meaning transparent. A list is required with per visual variable a value. \cr - values.var \tab Default values when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. \cr - values.range \tab Default range for values. See \code{values.range} of \code{\link[=tm_scale_categorical]{tm_scale_categorical()}}. A list is required with per visual variable a value. \cr - value.neutral \tab Default values for when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. \cr - scales.var \tab Default scales. \cr - label.format \tab Format for the labels (was \code{legend.format} in tmap v3) \cr - label.na \tab Default label for missing values \cr - See \code{\link[=tm_layout]{tm_layout()}} for layout specific options \tab \cr + \code{modes} \tab Mode specific options. It is a named list where names correspond to the available modes. Each item is a list of options. \cr + \code{crs} \tab Map crs (see \code{\link[=tm_shape]{tm_shape()}}). \code{NA} means the crs is specified in \code{\link[=tm_shape]{tm_shape()}}. The crs that is used by the transformation functions is defined in \code{\link[=tm_shape]{tm_shape()}}. \cr + \code{facet.max} \tab Maximum number of facets \cr + \code{facet.flip} \tab Should facets be flipped (in case of facet wrap)? This can also be set via \code{\link[=tm_facets_flip]{tm_facets_flip()}} \cr + \code{raster.max.cells} \tab Maximum number of raster grid cells \cr + \code{show.messages} \tab Show messages? \cr + \code{show.warnings} \tab Show warnings? \cr + \code{output.format} \tab Output format \cr + \code{output.size} \tab Output size \cr + \code{output.dpi} \tab Output dpi \cr + \code{output.dpi.animation} \tab Output dpi for animations \cr + \code{value.const} \tab Default visual value constants e.g. the default fill color for \code{tm_shape(World) + tm_polygons()}. A list is required with per visual variable a value. \cr + \code{value.na} \tab Default visual values that are used to visualize NA data values. A list is required with per visual variable a value. \cr + \code{value.null} \tab Default visual values that are used to visualize null (out-of-scope) data values. A list is required with per visual variable a value. \cr + \code{value.blank} \tab Default visual values that correspond to blank. For color these are \code{"#00000000"} meaning transparent. A list is required with per visual variable a value. \cr + \code{values.var} \tab Default values when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. \cr + \code{values.range} \tab Default range for values. See \code{values.range} of \code{\link[=tm_scale_categorical]{tm_scale_categorical()}}. A list is required with per visual variable a value. \cr + \code{value.neutral} \tab Default values for when a data variable to mapped to a visual variable, e.g. a color palette. A list is required with per visual variable a value. \cr + \code{scales.var} \tab Default scales. \cr + \code{label.format} \tab Format for the labels (was \code{legend.format} in tmap v3). \cr + \code{label.na} \tab Default label for missing values. \cr + See \code{\link[=tm_layout]{tm_layout()}} for layout specific options. \tab \cr } } diff --git a/man/tmap_save.Rd b/man/tmap_save.Rd index bd08d59d..ba94c02d 100644 --- a/man/tmap_save.Rd +++ b/man/tmap_save.Rd @@ -51,7 +51,7 @@ tmap_save( \item{in.iframe}{should an interactive map be saved as an iframe? If so, two HTML files will be saved; one small parent HTML file with the iframe container, and one large child HTML file with the actual widget. See \code{\link[widgetframe:saveWidgetframe]{widgetframe::saveWidgetframe()}} for details. By default \code{FALSE} which means that one large HTML file is saved (see \link[htmlwidgets:saveWidget]{saveWidget()}).} -\item{selfcontained}{when an interactive map is saved, should the resources (e.g. Javascript libraries) be contained in the HTML file? If \code{FALSE}, they are placed in an adjacent directory (see also \code{\link[htmlwidgets:saveWidget]{htmlwidgets::saveWidget()}}). Note that the HTML file will often still be large when \code{selfcontained = FALSE}, since the map data (polygons and popups), which are also contained in the HTML file, usually take more space then the map resources.} +\item{selfcontained}{when an interactive map is saved, should the resources (e.g. JavaScript libraries) be contained in the HTML file? If \code{FALSE}, they are placed in an adjacent directory (see also \code{\link[htmlwidgets:saveWidget]{htmlwidgets::saveWidget()}}). Note that the HTML file will often still be large when \code{selfcontained = FALSE}, since the map data (polygons and popups), which are also contained in the HTML file, usually take more space then the map resources.} \item{verbose}{Deprecated. It is now controlled by the tmap option \code{show.messages} (see \code{\link[=tmap_options]{tmap_options()}})} diff --git a/tests/testthat/test-v3.R b/tests/testthat/test-v3.R index 073214c5..a92772c4 100644 --- a/tests/testthat/test-v3.R +++ b/tests/testthat/test-v3.R @@ -9,7 +9,7 @@ test_that("v3 syntax works", { - # Data variable containing colours values + # Data variable containing color values World$isNLD <- ifelse(World$name == "Netherlands", "darkorange", diff --git a/tmap.Rproj b/tmap.Rproj index 7755ae37..7075b741 100644 --- a/tmap.Rproj +++ b/tmap.Rproj @@ -16,3 +16,5 @@ BuildType: Package PackageUseDevtools: Yes PackageInstallArgs: --no-multiarch PackageRoxygenize: rd,namespace + +SpellingDictionary: en_US diff --git a/vignettes/tmap_sneak_peek.Rmd b/vignettes/tmap_sneak_peek.Rmd index eb6d14b9..3f75f453 100644 --- a/vignettes/tmap_sneak_peek.Rmd +++ b/vignettes/tmap_sneak_peek.Rmd @@ -25,7 +25,7 @@ knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) ```{r, echo = FALSE, message = FALSE} library(tmap) data(World, metro) -#tmap_design_mode() +# tmap_design_mode() ``` The next major update of **tmap** will be a massive one. @@ -37,9 +37,9 @@ It is still fully in the development, but now is a good time for a sneak peek. First and foremost, **tmap v4** will be fully extendable. More precisely, the following aspects can be extended: -* Map layers: we are not limited anymore by the fixed set of `tm_polygons`, `tm_lines`, `tm_symbols`, and `tm_raster` (and their derivatives such as `tm_borders` and `tm_dots`), but any layer of interest can be developed as an extension of **tmap**. We will illustrate this below with `tm_cartogram`. Other layers that are worthwhile to implement are `tm_donuts`, `tm_hexagons`, `tm_network`, `tm_hillshade`, etc. +* Map layers: we are not limited anymore by the fixed set of `tm_polygons()`, `tm_lines()`, `tm_symbols()`, and `tm_raster()` (and their derivatives such as `tm_borders()` and `tm_dots()`), but any layer of interest can be developed as an extension of **tmap**. We will illustrate this below with `tm_cartogram()`. Other layers that are worthwhile to implement are `tm_donuts()`, `tm_hexagons()`, `tm_network()`, `tm_hillshade()`, etc. -* Aesthetics: there will be many more visual variables available. We will illustrate this in the next section, where we already implemented 5 new aesthetics for `tm_polygons`. Moreover, it will be much easier for developers to add new visual variables to map layer functions. +* Aesthetics: there will be many more visual variables available. We will illustrate this in the next section, where we already implemented 5 new aesthetics for `tm_polygons()`. Moreover, it will be much easier for developers to add new visual variables to map layer functions. * Graphics Engine: **tmap v3** contains two modes: `plot` and `view` (which are based on `grid` graphics and `leaflet` respectively) but the framework makes it possible to add other modes as well. @@ -51,7 +51,7 @@ First and foremost, **tmap v4** will be fully extendable. More precisely, the fo As mentioned before, we have added more aesthetics (visual variables), and it will be easier for developers to add new aesthetics. We have reordered the arguments that specify and configure the aesthetics which will be illustrated below. The arguments that specify aesthetics themselves will remain the same. -E.g., the main aesthetic in `tm_polygons` is `fill`, which defines the fill color of the polygons. +E.g., the main aesthetic in `tm_polygons()` is `fill`, which defines the fill color of the polygons. However, the other arguments of the layer functions are organized differently. Thus, each aesthetic will only have four arguments: @@ -79,7 +79,7 @@ tm_shape(World) + fill.legend = tm_legend(title = "Happy Planet Index")) ``` -In **tmap v4**, `tm_polygons` will have the aesthetics `fill`, `col`, `fill_alpha`, `col_alpha`, `lwd`, `lty`, and eventually also `pattern`. The other standard map layers will also have additional aesthetics. +In **tmap v4**, `tm_polygons()` will have the aesthetics `fill`, `col`, `fill_alpha`, `col_alpha`, `lwd`, `lty`, and eventually also `pattern`. The other standard map layers will also have additional aesthetics. A data variable can be mapped to each of them, using different scales (see next section for an overview). The next example uses `fill`, `lwd` (line width), and `lty` (line type) as aesthetics: @@ -118,7 +118,7 @@ The polygons are distorted such that the size will be (approximately) proportion ## Map layers (e.g. cartogram) -It will be easy for developers to add new map layers as extension. We illustrate this by a new map layer, `tm_cartogram`. +It will be easy for developers to add new map layers as extension. We illustrate this by a new map layer, `tm_cartogram()`. Cartograms could already be made with **tmap v3**, but it explicitly required transforming the data using the **cartogram** package before mapping. @@ -135,9 +135,9 @@ tm_shape(World_carto, crs = "+proj=eck4") + title = "Happy Planet Index") ``` -In **tmap v4**, there will be a direct function `tm_cartogram` (using the **cartogram** package under the hood), which uses the transformation aesthetic `size` and inherits all visual aesthetics from `tm_polygons`: +In **tmap v4**, there will be a direct function `tm_cartogram()` (using the **cartogram** package under the hood), which uses the transformation aesthetic `size` and inherits all visual aesthetics from `tm_polygons()`: -```{r, class.source='bg-success',message=FALSE} +```{r, class.source='bg-success', message=FALSE} # tmap v4 tm_shape(World, crs = "+proj=eck4") + tm_cartogram(size = "pop_est", @@ -177,9 +177,6 @@ tm_shape(World, crs = "+proj=eck4") + tm_place_legends_right(width = 0.2) ``` -(We haven't decided whether to include `tm_cartogram` in the **tmap** package or in an extension package, e.g., **tmapCartogram** or **tmapExtra**. -Let us know your opinion at https://github.com/r-tmap/tmap/issues/565) - ## Scales Scales are used to map data variables to visual variables. @@ -187,19 +184,19 @@ Scales are not new in **map v4**, but they are used more explicitly. The following table shows the scales that are currently available: -| Scale | Main Data Type | Example | -|--- |--- |--- | -| `tm_scale_categorical` | categorical (`factor`) | Fruit type | -| `tm_scale_ordinal` | categorical (`ordered`) | Education level | -| `tm_scale_intervals` | numerical (`integer` or `numeric`) | Age group | -| `tm_scale_continuous` | numerical (`numeric`) | Height | -| `tm_scale_log10` | numerical (`numeric`) | Income | -| `tm_scale_discrete` | numerical (`integer`) | Number of children | +| Scale | Main Data Type | Example | +|--- |--- |--- | +| `tm_scale_categorical()` | categorical (`factor`) | Fruit type | +| `tm_scale_ordinal()` | categorical (`ordered`) | Education level | +| `tm_scale_intervals()` | numerical (`integer` or `numeric`) | Age group | +| `tm_scale_continuous()` | numerical (`numeric`) | Height | +| `tm_scale_log10()` | numerical (`numeric`) | Income | +| `tm_scale_discrete()` | numerical (`integer`) | Number of children | The main data type (second column) is the data type for which the scale is supposed to be applied. Any scale can be applied to any data type (even though it might not make sense), with one exception: continuous (and log10) scales cannot be applied to visual variables that can only take a finite set of values. Examples are symbol shape and line type. -By default, `tm_scale_categorical`, `tm_scale_ordinal`, and `tm_scale_intervals` are used for data of class `factor`, `ordered` and `numeric` respectively. +By default, `tm_scale_categorical()`, `tm_scale_ordinal()`, and `tm_scale_intervals()` are used for data of class `factor`, `ordered` and `numeric` respectively. Scales for date/time variables will be included as well. The main argument of each scale function is `values`, which are the values for the visual variables. @@ -215,7 +212,7 @@ The following table shows which type of values are required for which visual var | `fill_alpha` and `col_alpha` | Value range | The default values depend not only on the visual variable, but also on the scale and on whether data values are diverging. -For instance, if `tm_scale_intervals` is applied to a numeric variable with both negative and positive values where the visual variable is `fill`, then a diverging color palette is used. +For instance, if `tm_scale_intervals()` is applied to a numeric variable with both negative and positive values where the visual variable is `fill`, then a diverging color palette is used. The following map illustrates what happens when the six scale functions are applied to the same data variable. We use the variable *life expectancy* (which we round in order to make sure the number of unique values is limited): @@ -267,19 +264,21 @@ tm_shape(Africa) + ``` -## Multivarite Scales +## Multivariate Scales It will be possible to assign multiple variables for one aesthetic. -This can be done with the function `tm_mv` (which stands for multivariate). +This can be done with the function `tm_mv()` (which stands for multivariate). An example is the bivariate choropleth, which is not yet implemented, but will definitely be. ```{r, eval = TRUE, class.source='bg-success'} # tmap v4 tm_shape(World) + - tm_symbols(fill = tm_mv("well_being", "footprint"), - fill.scale = tm_scale_bivariate(scale1 = tm_scale_intervals(breaks = c(2, 5, 6, 8)), - scale2 = tm_scale_intervals(breaks = c(0, 3, 6, 20)), - values = "brewer.qualseq")) + tm_symbols( + fill = tm_mv("well_being", "footprint"), + fill.scale = tm_scale_bivariate(scale1 = tm_scale_intervals(breaks = c(2, 5, 6, 8)), + scale2 = tm_scale_intervals(breaks = c(0, 3, 6, 20)), + values = "brewer.qualseq") + ) ``` Another example of multivariate aesthetics are glpys, which are small charts used as symbols. @@ -338,10 +337,10 @@ tm_shape(World) + ``` **tmap v3** contains many (often complicated) options for rather simple things. -These options are set globally via `tmap_options` or within a single plot with `tm_layout`. +These options are set globally via `tmap_options()` or within a single plot with `tm_layout()`. -In **tmap v4**, the directly related to the layout are accessible via `tm_layout`. -However, to ease its use, there will be a bunch of handy shortcut functions, such as `tm_place_legends_left`: +In **tmap v4**, the directly related to the layout are accessible via `tm_layout()`. +However, to ease its use, there will be a bunch of handy shortcut functions, such as `tm_place_legends_left()`: ```{r, eval = FALSE, class.source='bg-warning'} # tmap v3 @@ -402,11 +401,11 @@ This is also useful to make continuous legends better. ## Facets -In **tmap v4**, there will be convenient wrappers `tm_facet_wrap` and `tm_facet_grid`, where the former wraps the facets, and the latter places the facets in a grid layout. +In **tmap v4**, there are convenient wrappers `tm_facet_wrap()` and `tm_facet_grid()`, where the former wraps the facets, and the latter places the facets in a grid layout. -Furthermore, each visual variable will have a `free` argument, which determines whether scales are free (`TRUE`) or shared (`FALSE`) across facets. +Furthermore, each visual variable has a `free` argument, which determines whether scales are free (`TRUE`) or shared (`FALSE`) across facets. -In **tmap v3** this `free` argument could be set via `tm_facets`, whereas in **tmap v4** this argument has been moved to the layer functions: +In **tmap v3** this `free` argument could be set via `tm_facets()`, whereas in **tmap v4** this argument has been moved to the layer functions: ```{r, eval=FALSE, class.source='bg-warning'} @@ -471,7 +470,7 @@ tm_layout(meta.margins = c(.2, 0, 0,.1)) What you see in the map is that life expectancy is shown as polygon fill in green, and GDP per capita as red bubbles. The maps are grouped by income group (rows) and economy (columns). The scale for life expectancy is set to free for the columns. -This means that the scale will be applied for each column separately, with a legend per colomn. +This means that the scale will be applied for each column separately, with a legend per column. The scale for GDP per capita is applied separately for each row. @@ -483,7 +482,7 @@ The scale for GDP per capita is applied separately for each row. Just like **tmap v3**, there will be a `"plot"` and a `"view"` mode. However, the framework used in **tmap v4** also facilitates developers to write plotting methods for other modes. -For instance, **CesiumJS** is a great Javascript library for 3d globe visualizations. +For instance, **CesiumJS** is a great JavaScript library for 3d globe visualizations. It would be awesome to include this in **R**. When there is a low-level interface between **CesiumJS** and **R** (similar to the R package **leaflet** being an interface between the JS library **leaflet** and **R**), it will be relatively easy for developers to add a new mode for these 3d visualizations in **tmap v4**. @@ -506,7 +505,7 @@ 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 panel of RStudio or the browser: +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 diff --git a/vignettes/tmap_vv.Rmd b/vignettes/tmap_vv.Rmd index de9ff415..49fc880b 100644 --- a/vignettes/tmap_vv.Rmd +++ b/vignettes/tmap_vv.Rmd @@ -37,7 +37,7 @@ data(World, metro, rivers, land) * **tmap 3.x** supports several map layer variables, for example `"col"`, `"size"`, and `"shape"` for the `tm_symbols()` map layer function. There will be many more of those variables in **tmap 4**. Besides the visual variables, so-called transformation variables also will be available. A *transformation variable* role is to change the spatial coordinates (for instance, to create a cartogram). A *visual variable* only changes the appearance of a spatial object, e.g. fill color or line width. You can find some examples of these variables below. -* Map layer arguments (e.g. the arguments of `tm_polygons()`) are much better organized: for each visual/transformation variable, there are only four arguments. In case of the visual variable `"fill"` these are: `"fill"`, `"fill.scale"`, `"fill.legend"` and `"fill.free"`, which respectively specify the data variable or visual value that defines the polygon fill color, the used scaling function, the legend layout, and whether scales are applied freely across facets. +* Map layer arguments (e.g. the arguments of `tm_polygons()`) are much better organized: for each visual/transformation variable, there are only four arguments. In case of the fill visual variable, these are: `fill`, `fill.scale`, `fill.legend` and `fill.free`, which respectively specify the data variable or visual value that defines the polygon fill color, the used scaling function, the legend layout, and whether scales are applied freely across facets. * The input for each visual/transformation variable can be multivariate, in the sense that multiple data variables are scaled to one transformation of visual variable. An example is a bivariate choropleth, in which a cross tabulation of two data variables is mapped to one (bivariate) color palette. @@ -53,13 +53,13 @@ data(World, metro, rivers, land) #### tmap 4 - ggplot2 -The **tmap** package is very similar to **gplot2** and its Grammar of Graphics, but tailored to spatial data visualization, whereas **ggplot2** is much more general. More specifically: +The **tmap** package is very similar to **ggplot2** and its Grammar of Graphics, but tailored to spatial data visualization, whereas **ggplot2** is much more general. More specifically: * In **tmap**, the visual/transformation variables are always specifies in the map layer functions, whereas in ggplot2 the aesthetics are usually specified at plot level. * In **ggplot2**, scales are determined on plot level, whereas in **tmap**, they are determined on map layer level. -* In **tmap**, spatial data (e.g. an `sf` object) is specified with `tm_shape()`. The spatial coordinates (`x` and `y`) are considered to be part of the data (which can be changed with transformation variables). In principle, any map layer function can be used with any spatial class. E.g. `tm_dots()` renders dots for `sf` points data, but it also works for other spatial classes: e.g. centroids for `sf` polygons/lines and raster data (**stars** / **terra** packages). However, in `ggplot()`, each spatial class requires a custom map layer function, e.g. `geom_sf()` for `sf` objects. +* In **tmap**, spatial data (e.g. an `sf` object) is specified with `tm_shape()`. The spatial coordinates (`x` and `y`) are considered to be part of the data (which can be changed with transformation variables). In principle, any map layer function can be used with any spatial class. E.g. `tm_dots()` renders dots for `sf` points data, but it also works for other spatial classes: e.g. centroids for `sf` polygons/lines and raster data (**stars** / **terra** packages). However, in `ggplot2::ggplot()`, each spatial class requires a custom map layer function, e.g. `ggplot2::geom_sf()` for `sf` objects. * **tmap** has a static plot mode and an interactive mode. @@ -85,14 +85,14 @@ A **visual variable** describes a certain visual property of a drawn object, suc 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` | | +| 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. @@ -138,7 +138,7 @@ 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. +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) + @@ -201,7 +201,7 @@ For `tm_scale_intervals()` it is possible to chose how to determine the breaks ( Finally, `tm_scale_discrete()` uses a discrete linear scale. Note that this is different than `tm_scale_ordinal()`, which does not use colors for values that are not present (as categories), for instance 53. -Each `tm_scale_` functions can (in principle) be applied to any visual or transformation variable. Note that this is different from **ggplot2** where scales are organized by variable and by type (e.g. `ggplot2::scale_fill_continuous()`). This is related to another difference with **ggplot2**. In **tmap**, the scales are set directly in the map layer function to the target visual/transformation variable, for instance `tm_polygons(fill = "x", fill.scale = tm_scale_continuous())`. In `ggplot()`, scales are set outside the layer functions. +Each `tm_scale_*()` functions can (in principle) be applied to any visual or transformation variable. Note that this is different from **ggplot2** where scales are organized by variable and by type (e.g. `ggplot2::scale_fill_continuous()`). This is related to another difference with **ggplot2**. In **tmap**, the scales are set directly in the map layer function to the target visual/transformation variable, for instance `tm_polygons(fill = "x", fill.scale = tm_scale_continuous())`. In `ggplot()`, scales are set outside the layer functions. Each `tm_scale_` function has (at least) the following arguments: `values`, `values.repeat`, `values.range`, `values.scale`, `value.na`, `value.null`, `value.neutral`, `labels`, `label.na`, `label.null`, and `label.format`. The `value*` arguments determine the visual values to which the data values are mapped. In case the scale is applied to a visual variable that represents color, they takes color values or a color palette. However, if for instance the same scale is applied to line width, then values should be numeric values that represent line widths. @@ -214,12 +214,14 @@ tm_shape(World) + tm_symbols(size = "HPI", size.scale = tm_scale_intervals(values = c(0.3,0.5, 0.8), value.na = 0.1, breaks = c(12,20,30,45)), col = "grey30") ``` -The defaults for those `value*` arguments are stored in the **tmap** options. For instance +The defaults for those `value.*` arguments are stored in the **tmap** options. For instance ```{r} tmap_options("values.var")$values.var$fill ``` -contains the default color palettes for the visual variable `"fill"` for different types of data. For instance, when data values are all positive numbers, and `tm_scale_intervals` or `tm_scale_continuous` is applied, the default color palette is `hcl.blues3`, as can be seen in the examples above. +contains the default color palettes for the visual variable `"fill"` for different types of data. For instance, when data values are all positive numbers, and `tm_scale_intervals()` or `tm_scale_continuous()` is applied, the default color palette is `"hcl.blues3"`, as can be seen in the examples above. -Regarding the available color palettes: **tmap** uses the new R package **cols4all** which contains a large number of well-known color palettes. Please run `cols4all::c4a_gui()` which starts an interactive tool (the successor of `tmaptools::palette_explorer()`). Of course, also own color palettes can be loaded directly via a vector of color codes. +Regarding the available color palettes: **tmap** uses the new R package **cols4all** which contains a large number of well-known color palettes. +Please run `cols4all::c4a_gui()` which starts an interactive tool (the successor of `tmaptools::palette_explorer()`). +Of course, also own color palettes can be loaded directly via a vector of color codes.