Skip to content

Scales

.gg.scale.alpha

Return an alpha (opacity) scale between the min and max alpha arguments. Note - alpha scales can only map numeric variables. An error will be thrown if a categorical variable is given.

Parameter(s):

Name Type Description
minAlpha long between 0 and 255
maxAlpha long between 0 and 255

Returns:

Name Type Description
<returns> dict scale

Example: A scale from 50 to 255 (max) opacity

 .gg.scale.alpha[50;255] 

.gg.scale.breaks

Specify the break points (ticks) that should be used for the scale. This will override the generated breakpoints for the scale.

Parameter(s):

Name Type Description
breaks any[] list of break points in the domain on the scale
s dict scale

Returns:

Name Type Description
<returns> dict extended scale

Example: A scale with default breaks

 .gg.scale.linear

Example: A scale with explicit breaks at 0 50 60 65 and 100

 .gg.scale.breaks[0 50 60 65 100] .gg.scale.linear

Example: A scale with no breaks

 .gg.scale.breaks[()] .gg.scale.linear

.gg.scale.categorical

Create a scale for a categorical variable (any data type). If given a numeric variable, the distinct numbers will be treated as independent categories, and will be evenly spaced along the axis. See .gg.scale.linear for a linear numeric scale.

The scale can optionally be initialized with a sorting function. This function can reorder the categories so they display in any given order. By default, the categories are sorted ascending. For default sorting behaviour, provide no argument: .gg.scale.categorical[].

Note - the sort function is a function from the domain to the ordered domain. Elements can be injected or removed. Whatever is returned from the function will be displayed on the scale. To restrict a specific order to only the visible records, intersect the specific order with the domain as in the last example below. This allows drilldown to maintain the ordering while only displaying visible categories.

Returns:

Name Type Description
<returns> dict scale

See Also: .gg.scale.linear

Example: Default ascending categorical scale

 .gg.scale.categorical[]

Example: Descending categorical scale

 .gg.scale.categorical[desc]

Example: Specific ordering in categorical scale

 .gg.scale.categorical[{`IF`VVS1`VVS2`VS1`VS2`SI1`SI2`I1 inter x}]

.gg.scale.circle.area

Create a circle area scale, scaling to areas between the given max and min. This scale is a good candidate for coupling with a size aesthetic mapping on a point geometry.

Parameter(s):

Name Type Description
m long min area
M long max area

See Also: .gg.scale.circle.radius .qp.point .qp.s.aes

Example: Circle area scale

 .gg.scale.circle.area[5;50]

.gg.scale.circle.radius

Create a circle radius scale, scaling to radii between the given max and min. This scale is a good candidate for coupling with a size aesthetic mapping on a point geometry, however, the points will grow quicker than their underlying value. For a linear growth, see .gg.scale.circle.area.

Parameter(s):

Name Type Description
m long min area
M long max area

See Also: .gg.scale.circle.area .qp.point .qp.s.aes

Example: Circle area scale

 .gg.scale.circle.radius[2;6]

.gg.scale.colour.cat

Create a new categorical color scale using the list of colours given. If there are more values in the list than colours given, then the colours will wrap to include all values (note, values will not have unique colors if this is the case).

For example:

.gg.scale.colour.cat `green`red // or .gg.scale.colour.cat (.gg.colour.Green; .gg.colour.Red)

Alternatively, a dictionary of categories to colours can be provided to make the colour mapping explicit. For example, if there are two categories in the domain: `pass`fail, we can assign `pass to green and `fail to red with:

.gg.scale.colour.cat `pass`fail!(.gg.colour.Green; .gg.colour.Red)

See .gg.colour.COLOURS for available colours.

Parameter(s):

Name Type Description
colours byte[][] list of colours (0xrrggbb)

Returns:

Name Type Description
<returns> dict categorical colour scale

See Also: .gg.colour.COLOURS

Example: Colour scale with 3 built-in colours

 .gg.scale.colour.cat (.gg.colour.SteelBlue; .gg.colour.FireBrick; .gg.colour.Green)

Example: Colour scale with 4 RGB colours

 .gg.scale.colour.cat (0x336699; 0x669933; 0x993366; 0x558899)

Example: Colour scale with 4 RGB colours and explicit mapping

 .gg.scale.colour.cat `a`b`c`d!(0x336699; 0x669933; 0x993366; 0x558899)

.gg.scale.colour.cat10

Create a new 10-valued categorical color scale. If there are more than 10 distinct values in the list, then the colours will wrap to include all values (note, values will not have unique colors if this is the case).

Returns:

Name Type Description
<returns> dict categorical colour scale

See Also: .gg.colour.COLOURS .gg.scale.colour.cat .gg.scale.colour.cat20

Example: 10-valued categorical colour scale applied to a geometry

 t:([]x:til 10; y:1);

 .qp.bar[t; `x; `y] (::)
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.cat10]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]
     , .qp.s.geom[enlist[`gap]!enlist 0]

Image

.gg.scale.colour.cat20

Create a new 20-valued categorical color scale. If there are more than 20 distinct values in the list, then the colours will wrap to include all values (note, values will not have unique colors if this is the case).

Returns:

Name Type Description
<returns> dict categorical colour scale

See Also: .gg.colour.COLOURS .gg.scale.colour.cat .gg.scale.colour.cat10

Example: 20-valued categorical colour scale applied to a geometry

 t:([]x:til 20; y:1);

 .qp.bar[t; `x; `y] (::)
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.cat20]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]
     , .qp.s.geom[enlist[`gap]!enlist 0]

Image

.gg.scale.colour.gradient

Create a gradient scale between the two given colours. Expects numeric/interval data rather than categorical.

For a categorical color scale, see cat10, cat20, etc.

For a 3-valued gradient scale, see gradient2.

Parameter(s):

Name Type Description
minFill byte[] colour representing the min value (0xrrggbb)
maxFill byte[] colour representing the max value (0xrrggbb)

Returns:

Name Type Description
<returns> dict gradient scale

Throws:

Type Description
"scale+gradient error: x"

See Also: .gg.colour.COLOURS .gg.scale.colour.cat .gg.scale.colour.cat10 .gg.scale.colour.cat20 .gg.scale.colour.gradient2

Example: Gradient scale between two built-in colours

  t:([]x:til 500; y:1);

 .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradient[`steelblue; `firebrick]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

Example: Gradient scale between two built-in colours

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradient[`black; `white]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear] 

Image

Example: Gradient scale between two RGB colours

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradient[0x336699; 0x993366]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

.gg.scale.colour.gradient2

Create a gradient scale between the three given colours, with a specified midpoint value. Expects numeric/interval data rather than categorical. For a categorical color scale, see cat10, cat20, etc.

Parameter(s):

Name Type Description
midpoint any number representing the middle of the gradient (for centering). If null, mid point of data will be used.
minFill byte[] colour representing the min value (0xrrggbb)
middleFill byte[] colour representing the min value (0xrrggbb)
maxFill byte[] colour representing the max value (0xrrggbb)

Returns:

Name Type Description
<returns> dict gradient scale

See Also: .gg.colour.COLOURS .gg.scale.colour.cat .gg.scale.colour.cat10 .gg.scale.colour.cat20 .gg.scale.colour.gradient

Example: Gradient scale between two built-in colours

  t:([]x:til 500; y:1);

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradient2[250; 
              `steelblue; `white; `firebrick]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

Example: Gradient scale between two built-in colours

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradient2[360; 
              `steelblue; `white; `firebrick]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear] 

Image

Example: Gradient scale between two RGB colours

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradient2[120; 
              0x336699; 0x993366; 0x669933]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

.gg.scale.colour.gradientN

Create a gradient scale between any number of colours, with a specified midpoint value. Expects numeric/interval data rather than categorical. For a categorical color scale, see cat10, cat20, etc.

Parameter(s):

Name Type Description
midpoints any | null scale values for each intermediate gradient color between the extremes
fill byte[][] colours representing the gradient step (0xrrggbb)

Returns:

Name Type Description
<returns> dict gradient scale

See Also: .gg.colour.COLOURS .gg.scale.colour.cat .gg.scale.colour.cat10 .gg.scale.colour.cat20 .gg.scale.colour.gradient .gg.scale.colour.gradient2

Example: Gradient scale between two built-in colours

  t:([]x:til 500; y:1);

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradientN[250; 
              `steelblue`white`firebrick]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

Example: Gradient scale between two built-in colours

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradientN[360; 
              `steelblue`white`firebrick]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear] 

Image

Example: Gradient scale between two RGB colours

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradientN[120; 
              (0x336699; 0x993366; 0x669933)]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

Example: Gradient scale between several RGB colours

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradientN[::; 
            reverse `red`orange`yellow`lightgreen`teal`blue]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

Example: Rainbow gradient

  .qp.bar[t; `x; `y]
     .qp.s.aes[`fill; `x]
     , .qp.s.scale[`fill; .gg.scale.colour.gradientN[::; 
            reverse `red`orange`yellow`green`blue`indigo`violet]]
     , .qp.s.scale[`y; .gg.scale.limits[0 1] .gg.scale.linear]

Image

.gg.scale.compose

Compose takes two scales f and g and returns a new scale of the composition f . g

Parameter(s):

Name Type Description
f dict f scale
g dict g scale

Returns:

Name Type Description
<returns> dict scale of f . g

Example: A log log scale

 .gg.scale.compose[.gg.scale.log; .gg.scale.log]

Example: A log fill scale

 .gg.scale.compose[.gg.scale.colour.cat10; .gg.scale.log]

.gg.scale.date

Positional scale for date variables

.gg.scale.datetime

Positional scale for datetime variables

.gg.scale.format

Add a format function to a scale.

A format function is a function from data values to tick label string.

Note - newlines can appear in the format output by inserting "\n" in the string.

Parameter(s):

Name Type Description
f fn (scale, value) -> symbol
s dict scale

Returns:

Name Type Description
<returns> dict updated scale

See Also: .gg.scale.breaks

Example: A scale with default tick formats

 .gg.scale.linear

Example: A scale with custom breaks and ticks

  .gg.scale.format[{
     $[10 ~ x;   "ten";
      100 ~ x;   "one hundred";
      1000 ~ x;  "one thousand";
                 ""]
     }] .gg.scale.breaks[10 100 1000] .gg.scale.linear

.gg.scale.fromMeta

Return a scale for a column based on a tables meta type

Parameter(s):

Name Type Description
typec char meta type character

Returns:

Name Type Description
<returns> dict scale

Example:

 .gg.scale.fromMeta "j"

.gg.scale.limits

Specify the limits (maximum and minimum) for a scale. This will override the generated limits for the scale. If either limit given is null, the max or min will be used as usual. The limits should be in the domain of the scale (float for a float scale, long for a long scale, etc).

Parameter(s):

Name Type Description
lims any[] the max and min data to use for the scale
s dict an uninitialized scale

Example: A scale with default limits

 .gg.scale.linear

Example: Start a scale at 0 and used generated max value

 .gg.scale.limits[0 0N] .gg.scale.linear

Example: Restrict (or extend) a scale to be between 0 and 100

 .gg.scale.limits[0 100] .gg.scale.linear

.gg.scale.line.size

Create a scale for the strokewidth of a line.

Parameter(s):

Name Type Description
m long min line size
M long max line size

Returns:

Name Type Description
<returns> dict line size scale

Example:

 .gg.scale.line.size[1;10]

.gg.scale.linear

Positional linear scale for numeric variables

.gg.scale.log

Positional logarithmic scale for numeric variables

.gg.scale.maxChars

Set the max characters that appear in a scale's tick labels

Parameter(s):

Name Type Description
n long the max number of characters to use
s dict scale

Returns:

Name Type Description
<returns> dict updated scale

Throws:

Type Description
"Maximum characters on a scale must be specified in integers"

Example: Set the scale ticks to truncate after 20 characters

 .gg.scale.maxChars[20] .gg.scale.categorical[]

.gg.scale.mercator

Create a Mercator scale. Useful for geo data.

Parameter(s):

Name Type Description
isLat boolean Whether the applied data is latitude

Returns:

Name Type Description
<returns> dict a Mercator scale

Example: Longitude scale

 .gg.scale.mercator[0b]

Example: Latitude scale

 .gg.scale.mercator[1b]

.gg.scale.minute

Positional scale for minute variables

.gg.scale.month

Positional scale for month variables

.gg.scale.power

Create a power scale. Each value will be raised to the given power.

Parameter(s):

Name Type Description
e number exponent for the power

Returns:

Name Type Description
<returns> dict power scale

Example: A power(2) scale

 .gg.scale.power[2]

Example: A square root scale

 .gg.scale.power[0.5]

.gg.scale.second

Positional scale for second variables

.gg.scale.square

Given an X or Y scale, ensure that the other (X or Y) scale has the same range (useful for maps).

Note - Only one of the scales needs to be marked square for this effect.

Parameter(s):

Name Type Description
sc dict

Returns:

Name Type Description
<returns> dict

Example: Square longitude scale

 .gg.scale.square .gg.scale.mercator[0b]

.gg.scale.time

Positional scale for time variables

.gg.scale.timespan

Positional scale for timespan variables

.gg.scale.timestamp

Positional scale for timestamp variables

.gg.scale.weekday

Positional scale for timestamp/datetime data to be displayed as a categorical weekday value label validate