R/tmap_mode.R

In r-tmap/tmap: Thematic Maps

#' Set tmap mode to static plotting or interactive viewing
#' 
#' Set tmap mode to static plotting or interactive viewing.
#' The global option `tmap.mode` determines the whether thematic maps are plot
#' in the graphics device, or shown as an interactive leaflet map (see also [tmap_options()].
#' The function `tmap_mode()` is a wrapper to set this global option.
#' The convenient function `ttm()`, which stands for toggle thematic map,
#' is a toggle switch between the two modes. The function `ttmp()` stands for
#' toggle thematic map and print last map: it does the same as `ttm()` followed
#' by [tmap_last()]; in order words, it shows the last map in the other mode.
#' It is recommended to use `tmap_mode()` in scripts and `ttm()`/`ttmp()` in the console.
#' 
#' # mode = "plot"
#' 
#' Thematic maps are shown in the graphics device.
#' This is the default mode, and supports all tmap's features,
#' such as small multiples (see [tm_facets()]) and extensive layout settings (see [tm_layout()]).
#' It is recommended to use [tmap_save()] for saving static maps.
#' 
#' # mode = "view"
#' 
#' Thematic maps are viewed interactively in the web browser or RStudio's Viewer pane.
#' Maps are fully interactive with tiles from OpenStreetMap or other map providers
#' (see [tm_tiles()]). See also [tm_view()] for options related to the `"view"` mode.
#' This mode generates a [leaflet::leaflet()] widget, which can also be directly
#' obtained with [tmap_leaflet()].
#' With R Markdown, it is possible to publish it to an HTML page. 
#'  
#' However, there are a couple of constraints in comparison to `"plot"`:
#' 
#' * The map is always projected according to the Web Mercator projection.
#'   Although this projection is the de facto standard for interactive web-based mapping,
#'   it lacks the equal-area property, which is important for many thematic maps,
#'   especially choropleths (see examples from [tm_shape()]).
#' * Small multiples are not supported
#' * The legend cannot be made for aesthetics regarding size, which are symbol size and line width.
#' * Text labels are not supported (yet)
#' * The layout options set with [tm_layout()]) regarding map format are not used.
#'   However, the styling options still apply.
#' 
#' @param mode One of `"plot"` or `"view"`. See Details for more info. 
#' @return The previous tmap mode before switching.
#' @example ./examples/tmap_mode.R
#' @seealso 
#' * `vignette("tmap_sneak_peek")`
#' * [tmap_last()] to show the last map
#' * [tm_view()] for viewing options
#' * [tmap_leaflet()] for obtaining a leaflet widget
#' * [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) {
	current.mode = getOption("tmap.mode")
	
	tOpt = get("tmapOptions", envir = .TMAP)
	show.messages = tOpt$show.messages
	
	modes = get_modes()

	if (is.null(mode)) {
		message("current tmap mode is \"", current.mode, "\"")
	} else {
		if (!mode %in% modes) stop("Unknown mode. Available modes: ", paste(modes, collapse = ", "))
		options(tmap.mode=mode)
		if (show.messages) message("tmap mode set to '", mode, "'")
	}
	invisible(current.mode)
}	

# tmap_graphics = function(mode = NULL) {
# 	if (is.null(mode)) mode = getOption("tmap.mode")
# 	get("tmapOptions", envir = .TMAP)$graphics[[mode]]
# }
# 
# tmap_graphics_name = function(mode = NULL) {
# 	tmap_graphics(mode = mode)$name
# }

get_modes = function() {
	names(get("tmapOptions", envir = .TMAP)$modes)
}

#' Set the design mode
#' 
#' When the so-called "design mode" is enabled, inner and outer margins,
#' legend position, and aspect ratio are shown explicitly in plot mode.
#' Also, information about aspect ratios is printed in the console.
#' This function sets the global option `tmap.design.mode`.
#' It can be used as toggle function without arguments.
#' 
#' @seealso [tmap_options()]
#' @param design.mode Logical value that determines the design mode.
#'   If omitted then the design mode is toggled.
#' @export
tmap_design_mode = function(design.mode) {
	dm = if (missing(design.mode)) {
		!getOption("tmap.design.mode")
	} else {
		if (!is.logical(design.mode)) stop("design.mode is not a logical")
		design.mode[1]
	}
	
	options(tmap.design.mode = dm)
	message(
		"design.mode: ", if (!dm) "OFF" else "ON",
		if (dm && getOption("tmap.mode") == "view") " (only effective in plot mode)" else "")
}

#' Set the development mode
#' 
#' When the so-called "development mode" is enabled, helpful messages and timings
#' are printed in the console
#' 
#' @param devel.mode logical value that determines the development mode.
#'   If omitted then the development mode is toggled.
#' @export
tmap_devel_mode = function(devel.mode) {
	dm = if (missing(devel.mode)) {
		!getOption("tmap.devel.mode")
	} else {
		if (!is.logical(devel.mode)) stop("devel.mode is not a logical")
		devel.mode[1]
	}
	
	options(tmap.devel.mode = dm)
	message("devel.mode: ", if (!dm) "OFF" else "ON")
}

pm = function(message) {
	cat("<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>\n")
	cat(message, "\n")
}

po = function(...) {
	e = substitute(list(...))
	nms = sapply(e, deparse)[-1]  
	
	x = list(...)
	
	for (i in seq_along(x)) {
		cat("<==================== ", nms[i], "===============>\n")
		print(x[[i]])
		if (i == length(x)) {
			cat("</============================================>\n")
		}
	}
	
	invisible()
}

so = function(...) {
	e = substitute(list(...))
	nms = sapply(e, deparse)[-1]  
	
	x = list(...)
	
	for (i in seq_along(x)) {
		cat("<==================== ", nms[i], "===============>\n")
		str(x[[i]])
		if (i == length(x)) {
			cat("</============================================>\n")
		}
	}
	
	invisible()
}

#' @rdname tmap_mode
#' @export
ttm = function() {
	current.mode = getOption("tmap.mode")
	
	modes = get_modes()
	
	id = match(current.mode, modes) + 1L
	if (id > length(modes)) id = 1L
	
	tmap_mode(modes[id])
	invisible(current.mode)
}

#' @rdname tmap_mode
#' @export
ttmp = function() {
	ttm()
	tmap_last()
}

check_mode = function(mode) {
	if (!mode %in% get_modes()) stop("incorrect mode", call. = FALSE)
}

check_unit = function(unit) {
	if (!unit %in% c("metric", "imperial", "km", "m", "mi", "miles", "ft", "feet")) stop("incorrect unit", call. = FALSE)
}