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 data object 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.
Constants¶
NaN,
E,
LN2,
LN10,
LOG2E,
LOG10E,
PI,
SQRT1_2,
SQRT2,
MIN_VALUE,
MAX_VALUE
Type Checking Functions¶
isArray,
isBoolean,
isNumber,
isObject,
isRegExp,
isString,
isDefined,
isValid
Math Functions¶
isNaN,
isFinite,
abs,
acos,
asin,
atan,
atan2,
ceil,
cos,
exp,
floor,
hypot,
log,
max,
min,
pow,
random,
round,
sin,
sqrt,
tan,
clamp
Sequence (Array or String) Functions¶
length,
join,
indexof,
lastindexof,
reverse,
slice,
sort,
span
String Functions¶
parseFloat,
parseInt,
upper,
lower,
replace,
split,
substring,
trim,
btoa,
atob
Formatting Functions¶
RegExp Functions¶
Scale Functions¶
These helpers are analogous to Vega's scale helper functions, but GenomeSpy resolves scales by channel instead of by named scale.
#
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.
#
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.
#
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.
These helpers are available in formula and filter transforms, in dynamic
expression properties, and in scale ExprRef properties. They are reactive:
when the referenced scale changes, dependent expressions update.
Other functions¶
#
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.