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
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
String Functions¶
parseFloat,
parseInt,
upper,
lower,
replace,
split,
substring,
trim
RegExp Functions¶
Other functions¶
#
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.