Discrete

Scales are declared with the SCALE clause. Read the documentation for this clause for a thorough description of its syntax.

The discrete scale type maps various categorical data types into a discrete output domain. The two categorical data types in ggsql are strings and booleans with strings being the most common. However, you can force a numeric data type into being discrete by explicitly using a discrete scale (e.g. SCALE DISCRETE x)

Input range

The input range for discrete scales consists of all the unique values that the scale understands. Their ordering in the input range will determine their ordering in the display, either in the legend or the axis. Values in the data that do not exist in the input range will be set to null.

Examples

Set order of bars using input range

VISUALISE species AS x FROM ggsql:penguins
DRAW bar
SCALE x FROM ['Chinstrap', 'Gentoo', 'Adelie']
SCALE y FROM [0, null]

Remove a category by omitting it

VISUALISE species AS x FROM ggsql:penguins
DRAW bar
SCALE x FROM ['Adelie', 'Chinstrap']
SCALE y FROM [0, null]

Explicitly include null in range to show removed data

VISUALISE island AS x FROM ggsql:penguins
DRAW bar
SCALE x FROM ['Torgersen', 'Biscoe', null]
SCALE y FROM [0, null]

Output range

The output range can either be given as an array of values or a named palette. For both of these, the requirement is that they contain at least the number of values as is present in the input range. There are discrete palettes for both color, linetype, and shape.

All aesthetics has a default output range so it is never required to provide one unless you want to change from the default. The defaults are as follows:

  • x/y: Ignored (values used directly)
  • stroke/fill: The ggsql palette
  • linetype: The default palette
  • shape: The shapes palette

The remaining aesthetics don’t have a meaningful discrete output domain and don’t work with discrete scales. Consider using an ordinal scale for these if necessary.

Examples

Choose a different color palette

VISUALISE bill_len AS x, bill_dep AS y, island AS color FROM ggsql:penguins
DRAW point
SCALE color TO tableau

Construct a manual output range

VISUALISE bill_len AS x, bill_dep AS y, island AS shape FROM ggsql:penguins
DRAW point
SCALE shape TO ['star', 'circle', 'diamond']

Transform

There are two transforms relevant to discrete scales and they are only used for casting the data. The string transform converts all data mapped to the scale into strings, and the bool transform will cast all mapped data into a booleans. Apart from this, they have no effect.

Settings

There is only one setting relevant for discrete scales:

  • reverse: Reverses the order of the scale. Defaults to false

Examples

Reverse the color legend

VISUALISE bill_len AS x, bill_dep AS y, species AS color FROM ggsql:penguins
DRAW point
SCALE color FROM ['Adelie', 'Chinstrap', 'Gentoo']
    SETTING reverse => true

Renaming

Breaks are generally named by their value. However, you may wish to rename one, several, or all of these. The RENAMING clause allows you to do that both by directly renaming a specific break or by providing a formatting function.

Direct renaming

When you provide a break value on the left and a break exist at that value then it will take on the label specified on the right. For examples adding RENAMING ‘Adelie’ => ‘Adélie’ will ensure that the species name will get the correct diacrit in the label.

Label formatting

Besides direct renaming you can also provide a formatting string if you want the same to happen to all labels, e.g. add a prefix or suffix. The syntax for this is RENAMING * => '... {} ...'. The current label will be inserted into the {} to produce the new label. Besides simply inserting the break value into the string, we can also provide a formatter. Of special interest to discrete scales are the :Title, :lower, and :UPPER formatters which lets you control the casing of strings. You can read more about these formatters in the break formatting section of the SCALE documentation

You can combine formatting with direct renaming in which case the direct renaming has priority over the formatting.

Examples

Rename null

VISUALISE sex AS x FROM ggsql:penguins
DRAW bar
SCALE x
    RENAMING 'null' => 'missing'
SCALE y FROM [0, null]

Add prefix

VISUALISE species AS x FROM ggsql:penguins
DRAW bar
SCALE x 
    RENAMING * => 'Species: {}'
SCALE y FROM [0, null]

Apply formatting

VISUALISE bill_len AS x, bill_dep AS y, sex AS color FROM ggsql:penguins
DRAW point
SCALE color
    RENAMING * => '{:Title}'