Skip to main content

Define different titles with LABEL

The LABEL clause is one of the simpler clauses in ggsql and allows you to override the default naming of axes and legends, as well as adding titles to the plot.

Clause syntax

The LABEL clause takes one or more labeling settings.

LABEL <aesthetic/title> => <string>, ...

If an aesthetic is given, then the title will be used for the relevant axis or legend, e.g. x => 'my x-axis' will label the x axis, whereas fill => 'Species' will label the legend for fill (if any).

There are a few additional labels beside the aesthetics that govern the different titles of the plot and can be given instead of an aesthetic name:

  • title: The main title of the plot
  • subtitle: An additional, often longer and more descriptive, title beneath the main title
  • caption: A string placed below the plot, often used to add additional information about the data source etc. Not supported by the Vega-Lite writer, which has no equivalent; the png (raster) writer renders it.

Rich text

The png writer reads the strings you provide here as markdown, so LABEL title => 'Sales in **2024**' renders the year in bold. This currently applies to the plot title, subtitle and caption, and to the axis titles. Legend titles and break labels (axis tick labels and legend keys) are still drawn literally — the renderer has no rich-text support on those slots yet, so markdown in them shows its markers. This is a gap rather than a design choice, and they will parse once the renderer catches up. The Vega-Lite writer has no rich-text support at all and draws every label exactly as given.

The recognised markdown is the same as for the text layer.

There is currently no way to turn this off for labels — the parse setting only covers text layers.

Automatic labelling logic

Axes and legends get an automatic label from the mapping. The logic is as follows:

  1. Start from the global mapping and then go through the layer mappings as they appear.
  2. Collect mappings for each aesthetic in the order they appear
  3. For each aesthetic determine the label based on the following priority:
  4. An explicitly provided one with LABEL
  5. The name of the first appearing column mapping
  6. The name of the aesthetic

This means that constants mapped to an aesthetic doesn’t contribute to the derived label, only data columns, and if all else fails the name of the aesthetic will be used.