visual -> map variable

Author: mtennekes

.gitignore

@@ -22,4 +22,5 @@ docs/
 #figures/
 /.quarto/
 *_cache/
-*_files/
+*_files/
+local/

_quarto.yml

@@ -42,7 +42,7 @@ book:
       chapters: 
         - "tm-shape.qmd" 
         - "layers.qmd" 
-        - "visual-variables.qmd" 
+        - "map-variables.qmd" 
         - "scales.qmd"
         - "legends.qmd"
         - "map-components.qmd"

charts.qmd

@@ -7,7 +7,7 @@ source("code/before_script.R")
 
 \index{charts}
 Thematic maps usually represent one or more variables using colors, shapes, or sizes.
-Then, the map legend is used to explain the meaning of these visual variables (@sec-legends).
+Then, the map legend is used to explain the meaning of these map variables (@sec-legends).
 Such a legend can be expanded (or even replaced, @sec-charts-customization) with a chart that provides more information about the distribution of the variable values.
 
 \index{histogram}
@@ -216,7 +216,7 @@ tm_shape(slo_tavg) +
 ## Additional chart customization {#sec-charts-customization}
 
 \index{ggplot2}
-All of the charts are directly based on the visual variables from the map layer and then created internally using the **ggplot2** package (@R-ggplot2).
+All of the charts are directly based on the map variables from the map layer and then created internally using the **ggplot2** package (@R-ggplot2).
 By default, however, the charts are much simplified, not showing all the details that **ggplot2** can provide, such as axis labels, titles, and various theme elements.
 <!-- https://github.com/geocompx/tmap/issues/10#issuecomment-3007409988 -->
 

facets.qmd

@@ -61,7 +61,7 @@ tm_shape(slo_regions_ts) +
 ```
 
 Both approaches can be combined, allowing to create facets for multiple variables over time (@fig-facets3).
-Here, variables specified as a visual variable (`c("pop_dens", "gdppercap", "tourism")`) are shown in columns, while the faceting variable is set with `tm_facets(by = "time")` and presents the data for each year in a separate row.
+Here, variables specified as a map variable (`c("pop_dens", "gdppercap", "tourism")`) are shown in columns, while the faceting variable is set with `tm_facets(by = "time")` and presents the data for each year in a separate row.
 
 ```{r}
 #| label: fig-facets3
@@ -252,8 +252,8 @@ tm_shape(slo_tavg) +
 ```
 
 ::: {.callout-note}
-Each visual variable (e.g., `col`, `size`, `shape`) has a related argument with the `.free` suffix, e.g., `col.free`, `size.free`, `shape.free`.
-These arguments are used to control whether the scales for the visual variable are applied freely across facets or are shared.
+Each map variable (e.g., `col`, `size`, `shape`) has a related argument with the `.free` suffix, e.g., `col.free`, `size.free`, `shape.free`.
+These arguments are used to control whether the scales for the map variable are applied freely across facets or are shared.
 For example, `col.free = TRUE` means that each facet has its own color scale, while `col.free = FALSE` means that all facets share the same color scale.
 
 The `.free` arguments can also be used to control the scales for each facet dimension with a vector of logical values.

glossary.qmd

@@ -19,14 +19,13 @@ glossary = tibble::tribble(
   "Map layer", "A map layer is a visual representation of geographical information. We distinguish two types: *data-driven* and *auxiliary* map layers. The former requires spatial objects, whereas the latter only requires the geographic information (bounding box and coordinate reference system).",
   "Options", "In the context of tmap, we refer to the options as settings, which can be configured using `tm_options`. These can be *layout* options (see **layout**) or otherwise (e.g., `'show.messages'`).",
   "Proportional symbols", "Proportional symbols are symbols that are drawn at geographic locations and that are sized proportionally with a data variable. The result is known as a 'proportional symbol map'. These symbols are usually bubbles (filled circles), but can also be small charts, called **glyphs**.",
-  "Scale function", "A scale function determines how to scale a data variable to either a visual variable or a transformation variable. Examples: `tm_scale_continuous()`, `tm_scale_categorical()`.",
+  "Scale function", "A scale function determines how to scale a data variable to a map variable, whether it controls a visual property or a transformation. Examples: `tm_scale_continuous()`, `tm_scale_categorical()`.",
   "tmap element", "A `tm_` object that can be stacked with the `+` operator. These are: `tm_shape()`, map layer functions (such as `tm_polygons()`), facet specification function `tm_facets()`, map components (such as `tm_compass()`), and layout/option specification functions, such as `tm_layout()`.",
   "Shape (object)", "'Shape' is a nickname for a spatial data object. It is used in `tm_shape()`.",
-  "Shape (visual variable)", "The shape is a visual variable for some map layer functions, most prominently `tm_symbols()`. It determines the shape/design of the symbols.",
+  "Shape (map variable)", "The shape is a map variable for some map layer functions, most prominently `tm_symbols()`. It determines the shape/design of the symbols.",
   "Style", "The overall layout of the map. Similar to ggplot2's 'theme' (see **theme**).",
   "Theme", "tmap stands for 'thematic maps', where *theme* refers to the topic of the data plotted on a map. Note that in ggplot2, a 'theme' refers to the overall layout, e.g., `ggplot2::theme_minimal()`. In tmap, we use **style** for this.",
-  "Transformation variable", 'A variable of a data-driven map layer that determines a *transformation* of the spatial object. For instance, `tm_cartogram(size = "var")`.',
-  "Visual variable", 'A variable of a data-driven map layer that determines a *visual* aspect. This can be data-driven, e.g., `tm_polygons(fill = "var")`, where `var` is the name of an `sf` column, or a constant value, such as `tm_polygons(fill = "blue")`.',
+  "Map variable", 'A variable of a data-driven map layer that controls a *visual* property (e.g., color, size, shape) or a *transformation* (e.g., a cartogram) of the spatial object. This can be data-driven, e.g., `tm_polygons(fill = "var")` or `tm_cartogram(size = "var")`, where `var` is the name of an `sf` column, or a constant value, such as `tm_polygons(fill = "blue")`.',
   "Chart", 'A small non-spatial data visualization. In tmap for several purposes: 1) an addition to a legend `tm_polygons(fill = "var", fill.chart = tm_chart_histogram())`, 2) a glyph (see **glyphs**), 3) a custom chart plotted as an inset.',
   "Inset", "A visual object that is plotted on a specific (pre-defined) location. It can be a small map (**minimap**) or a **chart**."
 )

index.qmd

@@ -14,7 +14,7 @@ Whether you're a beginner in geospatial analysis or an experienced GIS user tran
 This book walks you through the full process of thematic mapping with **tmap**, including:
 
 - Load, explore, and prepare spatial data in R
-- Build maps using **tmap**’s core components like shapes, layers, and visual variables
+- Build maps using **tmap**’s core components like shapes, layers, and map variables
 - Customize map appearance with legends, scales, layouts, and annotations
 - Create faceted, animated, and interactive maps for various audiences
 - Integrate **tmap** maps into reports, web apps, and Shiny dashboards

layers.qmd

@@ -68,7 +68,7 @@ layers_df |>
 <!--JN: Idea - also add a simple viz showing different kind of layers here (visual summary)-->
 
 In this chapter, we focus on what map layers are available in **tmap** and how they differ from each other.
-@sec-visual-variables, on the other hand, is all about how to present information given in variables using colors, sizes, and shapes.
+@sec-map-variables, on the other hand, is all about how to present information given in variables using colors, sizes, and shapes.
 
 ## Polygons {#sec-polygons}
 
@@ -151,7 +151,7 @@ slo_cities = read_sf("data/slovenia/slo_cities.gpkg")
 Symbols are a versatile type of map layer.
 They are usually used to represent point data but can also be used for lines and polygons.
 In the latter cases, they are located in the centroid coordinates of each feature.
-Their flexibility is also related to the ways symbols can be visualized -- it is possible to show values of a given variable by colors of symbols, their sizes, or shapes (more about that is explained in @sec-visual-variables).
+Their flexibility is also related to the ways symbols can be visualized -- it is possible to show values of a given variable by colors of symbols, their sizes, or shapes (more about that is explained in @sec-map-variables).
 
 \index{tm\_symbols}
 The `tm_symbols()` is the main function in **tmap**, allowing to use and modify symbol elements (@fig-tmsymbols1).
@@ -257,7 +257,7 @@ tm_shape(slo_railroads) +
   tm_lines()
 ```
 
-Lines can be presented using different colors, widths, or types (@sec-visual-variables).
+Lines can be presented using different colors, widths, or types (@sec-map-variables).
 This allows to show a hierarchy (for example, increased line widths for higher capacity roads) or distinguish between types of objects (for example, blue rivers comparing to gray roads).
 
 ## Text {#sec-text}

layout.qmd

@@ -8,7 +8,7 @@ source("code/before_script.R")
 <!-- https://github.com/geocompx/tmap/issues/20#issuecomment-3209507327 -->
 
 \index{map layout}
-Map layout relates to all of the visual aspects of the created plot except the visual variables (@sec-visual-variables and @sec-scales), legends (@sec-legends-and-titles), map components (@sec-map-components), and their positions (@sec-positions).
+Map layout relates to all of the visual aspects of the created plot except the map variables (@sec-map-variables and @sec-scales), legends (@sec-legends-and-titles), map components (@sec-map-components), and their positions (@sec-positions).
 It includes the map background, frame, typography, scale, aspect ratio, margins, and more.
 
 We can customize the map layout using the `tm_layout()` function.
@@ -53,7 +53,7 @@ tm +
 ```
 
 The `tm_layout()` function also has tools to modify the complete map color style with arguments such as `color.saturation`, `color.sepia_intensity`, and `color_vision_deficiency_sim.`
-The first one represents the saturation of all colors on the map, including the backgrounds, as well as visual variables such as the fill or color of polygons and lines.
+The first one represents the saturation of all colors on the map, including the backgrounds, as well as map variables such as the fill or color of polygons and lines.
 The `color.saturation` parameter accepts a value between `0` and `1`, where `0` means no color saturation (i.e., the map is black and white), and `1` means full-color saturation (i.e., the map is colorful, default) (@fig-layout-saturation).
 The value of `0` may be useful when we want to create a black-and-white map, for example, to print it on a black-and-white printer, while the values in between `0` and `1` can be used to create a more muted, stylized map.
 

legends.qmd

@@ -22,7 +22,7 @@ Legends are an essential part of most maps.
 They provide meaning to the symbols or colors used in the map, and often add information about the map's content.
 They allow for interpreting the map correctly, and are therefore crucial for the map's readability.
 
-In **tmap**, legends are created automatically when we add a layer with a data-driven visual variable.
+In **tmap**, legends are created automatically when we add a layer with a data-driven map variable.
 By default, such a legend consists of a title based on the variable name and a color/shape/symbol scale (@fig-legend1). <!--REF to the color scale section?-->
 It is placed outside of the map frame, either on the right or on the bottom of the map, depending on the automatically determined map aspect ratio.
 
@@ -37,7 +37,7 @@ tm_shape(slo_elev) +
 \index{tm\_legend}
 Such a legend is helpful for quick exploration of the data, but often, they are not sufficient for sharing the map with others.
 This chapter covers how to customize the legend's title, position, and appearance in **tmap**.
-Legends are also closely related to the visual variables and scales used in the map that were covered in chapters @sec-visual-variables and @sec-scales -- we recommend reading those chapters first.
+Legends are also closely related to the map variables and scales used in the map that were covered in chapters @sec-map-variables and @sec-scales -- we recommend reading those chapters first.
 Legends are customized using the `tm_legend()` function that is passed to `*.legend` arguments of the layer functions, e.g., `col.legend`, `shape.legend`, `size.legend`, etc.
 
 Often, the most significant part of the legend is the title.