Skip to main content

Color scales

Numerical scales

numericScale

This function lets you quickly create scales that map numerical values to colors, and comes with a number of best practice scales, as well as options to customize them.

smplr.Color.numericScale({
  name: NumericScale | string
  domain?: [number, number]
  invert?: boolean
  padding?: number | [number, number]
  gamma?: number
  brighten?: number
  saturate?: number
  nodata?: string
  classes?: number | number[]
  zeroAsNoData?: boolean
}) => ((n: number | null | undefined) => string)

// example
smplr.Color.numericScale({
  name: smplr.Color.NumericScale.RdYlBu,
  domain: [10, 30],
  invert: true,
})
  • name is the identifier of the scale. See below for the list of available scales. You can either pass it as a string - 'OrRd', or using our provided enum for typesafety and autocompletion - smplr.Color.NumericScale.OrRd.
  • domain - optional - is typically the range of values that will be passed to the scale. It is an array of 2 numbers, where the first number is mapped to the start of the scale, and the second number is mapped to the end of the scale. Values lower than the domain will be mapped to the start of the scale, and values higher to the end. Default value: [0,1].
  • invert - optional - is a boolean used to invert the scale, or swap its start and end. Default value: false.
  • padding - optional - reduces the color range by cutting off a fraction of the scale. A single number applies the same padding to both ends, while an array lets you pad differently on the start and the end of the scale. Negative values can be used to compress the scale and extend its extreme values. Default value: 0.
  • gamma - optional - is used to "shift" a scale's center more the the beginning (gamma < 1) or end (gamma > 1). Default value: 1.
  • brighten - optional - is used to change the lightness of the scale. Positive values brightens it, while negative values darkens it. Default value: 0.
  • saturate - optional - is used to change the saturation of the scale. Positive values saturates it, while negative values desaturates it. Default value: 0.
  • nodata - optional - is the color used when the value passed to the scale is not valid. Default value: #6a6c6c.
  • classes - optional - is used to return a distinct set of colors instead of a continuous scale. A number generates a scale broken into equi-distant classes, while an array lets you choose the "breakpoints" to use for the classes.
  • zeroAsNoData - optional - should be set to true if you want to consider the value 0 as missing data, thus rendering it using the nodata color. Default value: false.

The scales available are:

  • single hue sequential scales: Oranges, Reds, Greens, Purples, Greys, Blues - from ColorBrewer.
  • multi-hue sequential scales: OrRd, PuBu, BuPu, BuGn, YlOrBr, YlGn, RdPu, YlGnBu, GnBu, YlOrRd, PuRd, PuBuGn – from ColorBrewer, and Viridis initially from Matplotlib.
  • diverging scales: Spectral, RdYlGn, RdBu, PiYG, PRGn, RdYlBu, BrBG, RdGy, PuOr - from ColorBrewer.

The air quality example uses numericScale and can be used as a code playground to test out the options. You can also chose and configure a color scale using our colors playground.

tip

Configure a numerical scale using our interactive colors playground

Categorical scales

categoryScale

This function lets you quickly map a discrete number of named categories to colors. It comes with fallback color built-in, as well as type safe categories.

smplr.Color.categoryScale<C extends string>({
  categories: Record<C, string>
  nodata?: string
}): ((category: C) => string)

// example
smplr.Color.categoryScale({
  categories: {
    sunny: 'yellow',
    rainy: 'blue',
    cloudy: 'grey'
  },
})
  • categories is an object matching category names to colors.
  • nodata - optional - is the color used when the value passed to the scale is not a known category. Default value: #6a6c6c.

Typescript tip: You may disable category typesafety by passing a "loose" type hint to the function: categoryScale<string>({...}).

Easy swatches for your legend

When using a category scale, you can use the same arguments provided to create the scale to generate the corresponding swatches. This makes it easy to use a legend for the scale.

smplr.Color.categorySwatches<C extends string>({
  // same as categoryScale
  categories: Record<C, string>
  nodata?: string
  // additional swatches config
  excludeNoData?: boolean
  noDataLabel?: string
}): {
  color: string
  label: string
}[]
  • categories and nodata - refer to categoryScale above.
  • excludeNoData - optional - lets you opt out of having a swatch for the nodata color. Default value: false.
  • noDataLabel - optional - lets you customize the label used for the nodata color. Default value: 'No data'.

ragScale

This function is built on top of categoryScale and provide a shortcut for red/amber/green scenarios. Here, the scale comes with pre-defined and optimized RAG colors, that can be customized. And the values "red", "amber", and "green" are always valid for quick testing.

smplr.Color.ragScale<C extends string | 'red' | 'amber' | 'green'>({
  categories?: Partial<Record<'red' | 'amber' | 'green', C>>
  colors?: {
    red?: string
    amber?: string
    green?: string
  }
  nodata?: string
}): ((category: C) => string)

// example
smplr.Color.ragScale({
  categories: {
    red: 'vacant',
    amber: 'expiring',
    green: 'occupied',
  },
})
  • categories - optional - is an object matching category names to the RAG classes. Default value: { red: 'red', amber: 'amber', green: 'green' }.
  • colors - optional - is an object used to provide custom RAG colors. Default value: { red: '#ff3f34', amber: '#c77a15', green: '#3aa655' }.
  • nodata - optional - is the color used when the value passed to the scale is not a known category. Default value: #6a6c6c.

Typescript tip: You may disable category typesafety by passing a "loose" type hint to the function: ragScale<string>({...}).

Easy swatches for your legend

When using a RAG scale, you can use the same arguments provided to create the scale to generate the corresponding swatches. This makes it easy to use a legend for the scale.

smplr.Color.ragSwatches<C extends string | 'red' | 'amber' | 'green'>({
  // same as ragScale
  categories?: Partial<Record<'red' | 'amber' | 'green', C>>
  colors?: {
    red?: string
    amber?: string
    green?: string
  }
  nodata?: string
  // additional swatches config
  excludeNoData?: boolean
  noDataLabel?: string
}): {
  color: string
  label: string
}[]
  • categories, colors and nodata - refer to ragScale above.
  • excludeNoData - optional - lets you opt out of having a swatch for the nodata color. Default value: false.
  • noDataLabel - optional - lets you customize the label used for the nodata color. Default value: 'No data'.