Create and Manage Encodings

Manage encodings to control how data maps to marks, channels, and layout behavior.

msc.encode(elem, channel, attribute, params)#

Encodes a data attribute using a visual channel on an element.

• elem: Mark or Group
• channel (String, required): visual channel
• attribute (String, required): data attribute
• params (Object): has the following properties
  • aggregator (String, optional): aggregator, defaults to "sum"
  • scale (Scale, optional): the scale to use for the encoding
  • scaleType (String, optional): type of scale
  • shareScale (Encoding, optional): share the scale of another encoding
  • flipScale (Boolean, optional): whether the scale is flipped, defaults to false
  • includeZero (Boolean, optional): whether the scale domain includes 0, defaults to false
  • rangeExtent (Number, optional): range extent
  • mapping (Object, optional): user-defined mapping between field values and visual properties
  • scheme (String, optional): color scheme; only the schemes in d3-scale-chromatic are supported, specified by their d3 name (e.g., "schemeTableau10", "interpolateYlOrRd"). Use a scheme* name for categorical data and an interpolate* name for continuous data. The available schemes are:
    • Categorical: schemeCategory10, schemeAccent, schemeDark2, schemePaired, schemePastel1, schemePastel2, schemeSet1, schemeSet2, schemeSet3, schemeTableau10
    • Diverging: BrBG, PRGn, PiYG, PuOr, RdBu, RdGy, RdYlBu, RdYlGn, Spectral (as interpolate* or scheme*, e.g., interpolateRdBu)
    • Sequential (single hue): Blues, Greens, Greys, Oranges, Purples, Reds (as interpolate* or scheme*, e.g., interpolateBlues)
    • Sequential (multi-hue): BuGn, BuPu, GnBu, OrRd, PuBuGn, PuBu, PuRd, RdPu, YlGnBu, YlGn, YlOrBr, YlOrRd (as interpolate* or scheme*); Cividis, Viridis, Inferno, Magma, Plasma, Warm, Cool, CubehelixDefault, Turbo (as interpolate* only, e.g., interpolateViridis)
    • Cyclical: Rainbow, Sinebow (as interpolate* only, e.g., interpolateRainbow)
  • startAngle (Number, optional): start angle in degrees when encoding with the "angle" channel, defaults to 90

The “length” channel#

The "length" channel encodes a data attribute as the length of paths:

• For paths laid along a guide path (the pieces of a divided path, or paths in a stack layout along a path), the lengths are parts of a whole, like pie slices: the scale’s domain is [0, sum of the values] and, by default, its range is the guide’s length minus the gaps, so the paths fill the guide exactly. The range is recomputed when the layout changes (e.g. its gap). There is one scale per divided path.
• Elsewhere (e.g. paths in a grid), each length is on its own, like a bar: the largest value gets the length of the path as created, and each path is resized from its start.

With rangeExtent, the largest value (or, along a guide, the values' total) maps to that many pixels instead. The channel only applies to paths.

• angleDirection (String, optional): direction to encode angles, defaults to "clockwise"
• Return type: Encoding

msc.getChannelEncodingByAttribute(attribute, channel, scene)#

Returns the encoding for given attribute and channel within a scene.

• attribute (String): data attribute
• channel (String): visual channel
• scene (Scene): the scene to search
• Return type: Encoding or null

msc.getChannelEncodingByElement(elem, channel)#

Returns the encoding for the given channel on a specific element.

• elem: Mark or Group
• channel (String): visual channel
• Return type: Encoding or null

msc.getEncodingsByChannel(channel, scene)#

Returns all the encodings in the scene that use the given channel.

• channel (String): visual channel
• scene (Scene): the scene to search
• Return type: Array of Encodings

msc.getEncodingsByElement(elem, includeVertexSegment)#

Returns all encodings associated with the element.

• elem: Mark or Group
• includeVertexSegment (Boolean, optional): whether to also include encodings on the element’s vertices and segments
• Return type: Array of Encodings

msc.removeEncoding(enc, scene)#

Removes an encoding from the scene.

• enc (Encoding): the encoding to remove
• scene (Scene, optional): the scene to remove from; defaults to the encoding’s own scene
• Return type: void