Which aesthetic names? Opinions please!

[mtennekes]

Which aesthetic names shall we use in tmap v4?

We could (of course) use the same as in the current version, but there will be (small) inconsistencies between layers. Moreover, many visual variables have not been implemented as aesthetic yet (e.g. alpha and line type). Some have not even implemented as visual constants (e.g. border line type for polygons).

Ideally, I would like to standardize aesthetic names, so not decide per layer function, but in general. Below a proposal based on a table that @Nowosad made earlier (thanks!). I only considered the elementary layers:

layer	aes	other_aes*
tm_polygons()	fill, color, pattern, linetype, linewidth, fill.alpha, color.alpha	linejoin
tm_symbols() / tm_dots()*	fill, color, pattern, linetype, linewidth, fill.alpha, color.alpha, size
tm_lines()	color, linetype, linewidth	linejoin, lineend
tm_arrow()*	color, linetype, linewidth, orientation, curvature	lineend, arrowhead
tm_raster() or tm_hex()	color
tm_text()	text, color, size, fontfamily, fontface

Remarks:

• The category other_aes will be visual constants and not visual variables, as I see no use in having a data variable encoded as e.g. linejoin.
• I included the tm_arrow since it has additional aesthetics. For now, I only consider tm_lines to be used for paths and tm_arrow for (curved) origin destination arrows. There are many alternatives possible, e.g. bundles edges but these may follow later.
• tm_dots and tm_symbols both use color as line color and fill as fill color. However, many symbols do not have a fill, so their color is controlled by color only. This applies to dots with pch=16.
• A tm_cartogram will be the same as tm_polygons with an additional size aesthetic. Note that a non contiguous cartogram is in essence similar to tm_symbols. Contiguous cartograms and dorling cartograms have more intelligence under the hood, but again, these only require the additional size aesthetic.

Some choices to make:

• col or color?
• lwd (current tmap), linewidth, or stroke (ggplot2)?
• orientation or direction for tm_arrows?
• alternatives for fill.alpha and color.alpha?

Shoot!

[rsbivand]

I suggest always prefer the argument names used in base R if they exist. col, lty, lwd, and similar are transferable between packages (including mapsf), grid and graphics, see ?grid::gpar and ?graphics::par. Possiibly prefer gpar() versions if grid and graphics diverge.

[mtennekes]

Good point! And that's also consistent with the current version of tmap. Small downside is that the other required aesthetic names like size, orientation (or direction) are currently not abbreviated. The base R variant for size is cex, but that is not a very user friendly parameter name.

[JimShady]

Would be great if col, color and colour were all valid (as they are in ggplot I believe?)

[JimShady]

linewidth preferably to lwd or stroke in my opinion.

[Nowosad]

1. Does it make sense to have fontfamily and fontface as visual variables? Are they not better as visual constants?
2. lwd is fine by me.
3. What would the orientation/direction specify for tm_arrows()?
4. fill.alpha and color.alpha are fine..
5. col or color is probably the most debatable decision. (Correct me if I am wrong) Base R col relates (depending on a plot) to the colors of the objects or to the fill of the objects. In tmap, it would be preferable to split color from fill. If it would be possible to use both col and color - that would be great. If not, I do not have any clear preferences...

[mtennekes]

@Nowosad good questions.

1. fontfamily not sure, but fontface is useful, e.g. for topographical maps which differentiate capitals from other cities.
2. linewidth is also fine with me, but I have a slight preference myself for shorter, abbreviated names (lwd over linewidth).
3. Not sure yet, but in some designs there is no arrowhead but a gradient which indicates direction. Although the coordinates already specify the direction (so a data variable is not always needed), a legend is still useful. But we have to give this more thought.
4. For single-color layers, such as tm_lines and tm_raster, I would prefer to use alpha. Probably, this won't be a problem. Perhaps we should replace the dots by underscores (see below).
5. Yes, indeed good to split "area" color from "stroke" color. It makes sense to call the former fill and the latter col.
   • It is slightly inconsistent with the current version, since tm_polygons currently uses col and border.col. However, we can make it backwards compatible as follows: when a user runs tm_polygons(col = "x"), it will be interpreted as tm_polygons(fill = "x") with a message that col is interpreted as fill, which will be the case in 99.99% of the applications. For users who really want to use the border color as aesthetic we can add a tmap option like autocorrect.arguments, that disables this behavior.
   • Whether tm_raster is a fill or col is debatable. On the one hand it is a fill, since a raster tile occupies a certain area. On the other hand, it has no stroke so one can argue that a tile itself is some sort of squared (or hex) symbol. I would go for the latter explanation, so use col, since it is more intuitive name than fill.

As it is implemented in v4 for now, each aesthetic will have 4 arguments:

1. The aesthetic itself, e.g. col.
2. The setup, col.setup, is a list that contains settings for this aesthetic which were previously loose arguments (e.g. style and breaks).
3. The (general) legend settings col.legend, such as legend title and orientation (portrait or landscape).
4. A logical col.free which determines whether this aesthetic should be processed per facet or for all facets at once.

The names fill.alpha and col.alpha also contain dots, which is a bit confusing. We could opt for fill_alpha and color_alpha instead.