Expressions¶

Expressions allow for defining predicates or computing new variables based on existing data. The expression language is based on JavaScript, but provides only a limited set of features, guaranteeing secure execution.

Expressions can be used with the "filter" and "formula" transforms, in encoding, and in expression references for dynamic properties in marks, transforms, and data sources.

Usage¶

All basic arithmetic operators are supported:

(1 + 2) * 3 / 4

When using expressions within the data transformation pipeline, the current row is available in the datum variable. Its properties (fields) can be accessed by using the dot or bracket notation:

datum.foo + 2

If the name of the property contains special characters such as ".", "!", or " " (a space) the bracket notation must be used:

datum['A very *special* name!'] > 100

Conditional operators¶

Ternary operator:

datum.foo < 5 ? 'small' : 'large'

And an equivalent if construct:

if(datum.foo < 5, 'small', 'large')

Provided constants and functions¶

Common mathematical functions are supported:

(datum.u % 1e-8 > 5e-9 ? 1 : -1) *
  (sqrt(-log(max(1e-9, datum.u))) - 0.618) *
  1.618

Constants and functions from Vega¶

The following constants and functions are provided by the vega-expression package.

reverse also accepts strings. It returns a reversed string without modifying the input and reverses by Unicode code point rather than UTF-16 code unit.

String Functions¶

parseFloat, parseInt, upper, lower, replace, split, substring, trim, btoa, atob

Formatting Functions¶

format

RegExp Functions¶

regexp, test

Scale Functions¶

These helpers are analogous to Vega's scale helper functions, but GenomeSpy resolves scales by channel instead of by named scale.

They are available in formula and filter transforms, in dynamic expression properties, and in scale ExprRef properties. They are reactive: when a referenced scale changes, dependent expressions update.

When a helper is used in a scale ExprRef, it resolves from the view that owns the scale resolution. For a shared scale, declare the expression in scales.<channel> on the composed view that owns the resolution.

# scale(channel, value)
Maps a value through the scale for the given channel, such as "x", "y", "color", or "size". The channel is resolved against the current view's scale resolution.

For band, index, and locus scales, this returns the start of the band. To match the default placement of point marks on an unreversed x scale, add bandwidth('x') / 2. The encoding's band property controls placement within the band independently of the scale's align property.

# invert(channel, range)
Maps a range value back through the scale for the given channel. The channel is resolved against the current view's scale resolution.

For index and locus scales, inversion returns a continuous coordinate measured from band starts. Without padding, [invert('x', 0), invert('x', 1)] equals domain('x') for an unreversed x scale. Apply floor to identify the band at a range position.

# domain(channel)
Returns the current domain of the scale for the given channel. The channel is resolved against the current view's scale resolution.

# range(channel)
Returns the current range of the scale for the given channel. The channel is resolved against the current view's scale resolution.

# bandwidth(channel)
Returns the current bandwidth of a band-like scale for the given channel. The value uses the same units as the scale range. For positional scales, multiply the result by width or height to convert it to pixels.

# zoomLevel()
Returns the geometric zoom level of the zoomable x and y scales that are resolvable from the expression scope. A missing or non-zoomable axis contributes 1, so the result is sqrt(xZoom * yZoom) and is 1 when neither axis is zoomable. The function discovers the resolvable x and y scales when the expression is bound.

# zoomLevel(channel)
Returns the zoom level of one scale, such as zoomLevel("x"). The channel must be a literal string. The value is the reference-domain span divided by the current displayed-domain span. A non-zoomable scale returns 1.

Compose separate calls when a formula needs multiple explicit scales. For example, sqrt(zoomLevel("x") * zoomLevel("y")) is the explicit equivalent of the automatic two-dimensional metric. Other formulas can use min, max, or ordinary arithmetic.

A scale domain (including its initial domain), zoom extent, or zoom configuration cannot read that same scale's zoom level. Cross-scale dependency cycles are also rejected. A scale range may read its own zoom level because range changes do not determine magnification.

Other functions¶

# tickStep(start, stop, count)
Returns a nicely rounded step of 1, 2, or 5 times a power of ten for approximately count intervals between start and stop. For example, tickStep(0, 12000000, 2) returns 5000000. Descending intervals produce a negative step. See D3's tickStep documentation.

# mapHasKey(map, key)
Returns true if the map contains the given key.

# lerp(array, fraction)
Provides a linearly interpolated value from the first to the last element in the given array based on the specified interpolation fraction, usually ranging from 0 to 1. For instance, lerp([0, 50], 0.5) yields 25.

# linearstep(edge0, edge1, x)
Calculates a linear interpolation between 0 and 1 for a value x within the range defined by edge0 and edge1. It applies a clamp to ensure the result stays within the 0.0 to 1.0 range.

# smoothstep(edge0, edge1, x)
Performs smooth Hermite interpolation between 0 and 1 for values of x that lie between edge0 and edge1. This function is particularly useful for scenarios requiring a threshold function with a smooth transition, offering a gradual rather than an abrupt change between states.

# center(array)
Returns the midpoint of an ordered extent, such as [min, max]. It uses the first and last elements and does not sort the array.