Predicate

Edit this page

To test a data point in a filter transform or a test property in conditional encoding, a prediction definition of the following forms must be specified:

  1. a Vega expression string, where datum can be used to refer to the current data object. For example, datum.b2 > 60 would test if the value in the field b2 for each data point is over 60.

  2. one of the field predicates: equal, lt, lte, gt, gte, range, oneOf, or valid,

  3. a selection predicate, which define the names of a selection hat the data point should belong to (or a logical composition of selections).

  4. a logical composition of (1), (2), or (3).

Field Predicate

Test if a field in the data point satisfies certain conditions.

For a field predicate, a field must be provided along with one of the predicate properties: equal, lt (less than), lte (less than or equal), gt (greater than), gte(greater than or equal), range, or oneOf. Values of these operators can be primitive types (string, number, boolean) or a DateTime definition object to describe time. In addition, timeUnit can be provided to further transform a temporal field.

Property Type Description
field String

Required. Field to be tested.

timeUnit TimeUnit | TimeUnitParams

Time unit for the field to be tested.

Field Equal Predicate

Property Type Description
equal String | Number | Boolean | DateTime

Required. The value that the field should be equal to.

For example, to check if the car_color field’s value is equal to "red", we can use the following predicate:

{"field": "car_color", "equal": "red"}

Field Less Than Predicate

Property Type Description
lt String | Number | DateTime

Required. The value that the field should be less than.

For example, to check if the height field’s value is less than 180, we can use the following predicate:

{"field": "height", "lt": 180}

Field Less Than or Equals Predicate

Property Type Description
lte String | Number | DateTime

Required. The value that the field should be less than or equals to.

For example, to check if the Year field’s value is less than or equals to "2000", we can use the following predicate:

{"timeUnit": "year", "field": "Year", "lte": "2000"}

Field Greater Than Predicate

Property Type Description
gt String | Number | DateTime

Required. The value that the field should be greater than.

To check if the state field’s value is greater than "Arizona" by string comparison, we can use the following predicate: (Note: Standard Javascript string comparison is done, ie., “A” < “B”, but “B” < “a”)

{"field": "state", "gt": "Arizona"}

Field Greater Than or Equals Predicate

Property Type Description
gte String | Number | DateTime

Required. The value that the field should be greater than or equals to.

For example, to check if the height field’s value is greater than or equals to 0, we can use the following predicate:

{"field": "height", "gte": 0}

Field Range Predicate

Property Type Description
range Number[] | DateTime[] | Null[]

Required. An array of inclusive minimum and maximum values for a field value of a data item to be included in the filtered data.

Examples

  • {"field": "x", "range": [0, 5]}} checks if the x field’s value is in range [0,5] (0 ≤ x ≤ 5)
  • {"timeUnit": "year", "field": "date", "range": [2006, 2008] }} checks if the date’s value is between year 2006 and 2008
  • {"field": "date", "range": [{"year": 2006, "month": "jan", "date": 1}, {"year": 2008, "month": "feb", "date": 20}] }} checks if the date‘svalue is between Jan 1, 2006 and Feb 20, 2008.

Field One-Of Predicate

Property Type Description
oneOf String[] | Number[] | Boolean[] | DateTime[]

Required. A set of values that the field’s value should be a member of, for a data item included in the filtered data.

For example, {"field": "car_color", "oneOf": ["red", "yellow"]}} checks if the car_color field’s value is "red" or "yellow"

Field Valid Predicate

Property Type Description
valid Boolean

Required. If set to true the field’s value has to be valid, meaning both not null and not NaN.

For example, {"field": "car_color", "valid": true}} checks if the car_color field’s value is valid meaning it is both not null and notNaN.

Selection Predicate

For a selection predicate, a selection name must be provided.

Property Type Description
selection String | Object

Required. Filter using a selection name or a logical composition of selection names.

For example, with {"selection": "brush"}}, only data values that fall within the selection named brush will remain in the dataset as shownbelow.

All selection composition can be used here as well. For instance, {"selection": {"and": ["alex", "morgan"]}}} filtersfor data values that are within both the alex and morgan selections.

When you use a selection filter to dynamically filter the data, scale domains may change, which can lead to jumping titles. To prevent this, you can fix the minExtent of the axis whose scale domain changes. For example, to set the minimum extent to 30, add {"axis": {"minExtent": 30}} to the corresponding encoding.

Predicate Composition

We can also use the logical composition operators (and, or, not) to combine predicates.

Examples

  • {"and": [{"field": "height", "gt": 0}, {"field": "height", "lt": 180}]} checks if the field "height" is between 0 and 180.
  • {"not": {"field": "x", "range": [0, 5]}}} checks if the x field’s value is not in range [0,5] (0 ≤ x ≤ 5).