ColorScale

public struct ColorScale : Encodable
extension ColorScale: ExpressibleByArrayLiteral
extension ColorScale: ExpressibleByDictionaryLiteral

Mapping from numerical values to colors.

Instead of constructing a custom color scale, in most situation it’s desirable to pick one from a pre-defined palette. There is a wide range of built-in scales that should suit nearly all applications. Key advantage of these scales is that they address the technicalities to avoid hidden biases that can distort how people naturally perceive the data.

Built-in Color Scales

Based on the type of data the built-in scales are suited to one can distinguish the following types:

  • Sequential - Vast majority of continuous data without any special properties.
  • Diverging - Continuous data with a natural mid-point or a critical value where roughly half of the data is smaller and the other half is larger.
  • Cyclic - Periodic data that wrap back to the same value after reaching end-points. For example tide height plotted on the globe.

Good way to pick one of the scales is to use the swatch() method that displays a figure with the scales other. The following example displays all diverging scales:

let diverging = ColorScale.Diverging.swatch()
// Also: Sequential, Cyclic, Ocean, Brewer, Carto, Plotly
try diverging.show()

Most popular color scales are exposed directly as static properties of ColorScale struct. The following code displays a swatch of the most frequent used scales:

let frequent = ColorScale.swatch()
try frequent.show()

Custom Color Scales

Color scale can be also created manually from a sequence of colors and optional normalizes scale values. In most situations the desirable behavior is a smooth, linear interpolation between in-between the sequence colors. However, it’s also possible to create discontinuous scales with sharp jumps at particular thresholds.

The following example creates a custom color scale by linearly interpolating colors. The minimum/maximum value of the data will be displayed in red/blue with the intermediate values interpolated through green. The min/max value can be changed by manually setting zMin/cMin or zMax/cMax properties of the Trace or Marker objects. Location of the green mid-point can be altered by zMid/cMid property in a similar fashion.

let rgb0: ColorScale = [.red, .green, .blue]
let rgb1 = ColorScale(interpolate: [.red, .green, .blue])

The following example achieves the same result as above but builds the color scale fom a dictionary that maps the scale values to colors:

let rgb0: ColorScale = [0: .red, 0.5: .green, 1.0, .blue]
let rgb1 = ColorScale(interpolate: [0: .red, 0.5: .green, 1.0, .blue])

The next code snippet creates a discontinuous black-white color scale with sharp jump below and above the mid-point:

let bw = ColorScale(interpolate: [(0: .white), (0.5: .white), (0.5, .black), (1.0, .black)])

See also

Color, ColorWay

Remark

.reversed() returns the color scale flipped, so the min color becomes the max and vice versa.

  • Color scales adapted from cmocean project.

    Copyright

    Licensed under the MIT license.
    See more

    Declaration

    Swift

    public enum Ocean

  • Single/multi-hue sequential and diverging color scales adapted from ColorBrewer2.

    Copyright

    Licensed under the Apache 2.0 license.
    See more

    Declaration

    Swift

    public enum Brewer

  • Sequential and diverging color scales adapted from CartoCOLORS.

    Copyright

    Licensed under the Creative Commons - Attribution license.
    See more

    Declaration

    Swift

    public enum Carto

  • Color scales imported from Plotly.js and Plotly.py.

    Copyright

    Licensed under the MIT license.
    See more

    Declaration

    Swift

    public enum Plotly

  • Collection of sequential color scales for continuous data.

    Sequential color scales are appropriate for nearly all continuous data. In some special case it can be helpful to use a Diverging or Cyclical scale instead.

    Copyright

    Adapted from Plotly.py, licensed under the MIT license.
    See more

    Declaration

    Swift

    public enum Sequential

  • Color scales for continuous data with a natural center point.

    Diverging color scales are appropriate for continuous data that has a natural midpoint or other informative special value, such as 0. For example altitude, or boiling point of a liquid.

    See more

    Declaration

    Swift

    public enum Diverging

  • Periodic color scales that wrap around the ends.

    Cyclical color scales are appropriate for continuous data that have a natural repeating structure. For example temporal data (hour of day, day of week, day of year, seasons), complex numbers, angles or other phase data. All scales start and end with the same color.

    Copyright

    Adapted from Plotly.py, licensed under the MIT license.
    See more

    Declaration

    Swift

    public enum Cyclical

  • Sequential, perceptually uniform, single-hue color scale.

    Declaration

    Swift

    public static let blues: ColorScale

  • Sequential, perceptually uniform, single-hue color scale.

    Declaration

    Swift

    public static let greens: ColorScale

  • Sequential, perceptually uniform, single-hue color scale.

    Declaration

    Swift

    public static let grays: ColorScale

  • Sequential, perceptually uniform, single-hue color scale.

    Declaration

    Swift

    public static let oranges: ColorScale

  • Sequential, perceptually uniform, single-hue color scale.

    Declaration

    Swift

    public static let purples: ColorScale

  • Sequential, perceptually uniform, single-hue color scale.

    Declaration

    Swift

    public static let reds: ColorScale

  • Sequential color scale inspired by sundown.

    Declaration

    Swift

    public static let sunset: ColorScale

  • Sequential color scale originating from Matplotlib.

    Declaration

    Swift

    public static let viridis: ColorScale

  • Sequential color scale originating from Matplotlib.

    Declaration

    Swift

    public static let magma: ColorScale

  • Sequential color scale originating from Matplotlib.

    Declaration

    Swift

    public static let plasma: ColorScale

  • Sequential color scale originating from Matplotlib.

    Declaration

    Swift

    public static let inferno: ColorScale

  • Diverging color scale for data with a natural center point.

    Declaration

    Swift

    public static let redBlue: ColorScale

  • Diverging color scale for data with a natural center point.

    Declaration

    Swift

    public static let pinkGreen: ColorScale

  • Diverging color scale appropriate for temperature-like data.

    Declaration

    Swift

    public static let temps: ColorScale

  • Cyclical color scale that spans all hues at a constant lightness value.

    Declaration

    Swift

    public static let phase: ColorScale

  • Creates a figure that shows all popular color scales next to each other.

    Declaration

    Swift

    public static func swatch() -> Figure

  • Ordered collection of normalized, non-decreasing scale values and corresponding colors.

    Declaration

    Swift

    public let scalesColors: [(Double, Color)]

  • Ordered collection containing just normalized, non-decreasing scale values.

    Declaration

    Swift

    public var scales: [Double] { get }

  • Ordered collection containing just the colors.

    Declaration

    Swift

    public var colors: [Color] { get }

  • Creates color scale from a list of colors.

    The colors in the list are placed at a constant distance from each other and the values in between them are linearly interpolated. First color is assigned to the minimum value and the last color to the maximum.

    The following example crates a three color red-green-blue color scale:

    let rgb: ColorScale = [.red, .green, .blue])

    Precondition

    Collection scalesColors has to contain at least 2 items.

    Declaration

    Swift

    public init(interpolate colors: [Color])

  • Creates color scale from a dictionary that maps normalized numeric values to colors.

    The colors in the list are placed at the value specified by the key. Values in between them are linearly interpolated. First color with 0.0 key is assigned to the minimum value and the the color with 1.0 index is assigned to the maximum.

    The following example creates an asymmetric color scale where change from red to green happens in the 30% of the data range.

    let rgb = ColorScale(interpolate: [0: .red, 0.3: .green, 1.0, .blue])

    Precondition

    Dictionary scalesColors has to contain at least 2 items.

    Warning

    There’s no validation. In particular, nothing prevents scale values outside of the [0,1] range or other degenerated corner cases.

    Declaration

    Swift

    public init(interpolate scalesColors: [Double : Color])

  • Creates color scale from a list of colors with associated values.

    This constructor is particularly useful for discontinuous color scales. The following example creates a two color white-black color scale without any smooth interpolation in between:

    let whiteBlackStep = ColorScale(interpolate: [
    (0.0: .white),
    (0.5: .white),
    (0.5, .black),
    (1.0, .black)
])

    Precondition

    Collection scalesColors has to contain at least 2 items.

    Warning

    There’s no validation. In particular, nothing prevents scale values outside of the [0,1] range or other degenerated corner cases.

    Declaration

    Swift

    public init(interpolate scalesColors: [(Double, Color)])

  • Returns the color scale flipped around the center point.

    Declaration

    Swift

    public func reversed() -> ColorScale

  • Encode the color scale to a format compatible with Plotly.

    Declaration

    Swift

    public func encode(to encoder: Encoder) throws

  • Creates a color scale from a color array literal.

    The following code creates a gray color scale:

    let grays: ColorScale = [.white, .black]

    Precondition

    Array has to contain at least 2 colors.

    Declaration

    Swift

    public init(arrayLiteral colors: Color...)

  • Creates color scale from a double-color dictionary literal.

    The following code creates a gray color scale:

    let grays: ColorScale = [0.0: .white, 1.0: .black]

    Precondition

    The dictionary has to contain at least 2 color-scale pairs.

    Warning

    There’s no validation. In particular, nothing prevents scale values outside of the [0,1] range or other degenerated corner cases.

    Declaration

    Swift

    public init(dictionaryLiteral scalesColors: (Double, Color)...)