Filter¶

The "filter" transform removes rows based on a predicate expression or a selection predicate.

Parameters¶

Predicate Expression¶

expr Required

Type: string

An expression string. The row is removed if the expression evaluates to false.

debounce

Type: number

Trailing-edge delay in milliseconds before requesting dataflow replay after a reactive expression dependency changes. Repeated changes restart the delay.

Parameter updates and incoming data are not delayed. Incoming batches use current parameter values, and a completed batch satisfies any pending reactive replay. The delay does not wait for independently scheduled lazy data loads.

Default value: no delay

description

Type: string

A description of the transform step. Can be used for documentation and agent context.

Selection Predicate¶

param Required

Type: string

A selection parameter. The row is removed if it is not part of the selection.

empty

Type: boolean

If true, the filter retains all rows when the selection is empty.

Default: true

fields

Type: object

Maps selection components to fields. Required for category and interval filters, which have no implicit visual encoding. Category mappings must cover exactly the declared component.

debounce

Type: number

Trailing-edge delay in milliseconds before requesting dataflow replay after a reactive expression dependency changes. Repeated changes restart the delay.

Parameter updates and incoming data are not delayed. Incoming batches use current parameter values, and a completed batch satisfies any pending reactive replay. The delay does not wait for independently scheduled lazy data loads.

Default value: no delay

description

Type: string

A description of the transform step. Can be used for documentation and agent context.

Example¶

Filtering by a Predicate Expression¶

{
  "type": "filter",
  "expr": "datum.p <= 0.05"
}

The example above passes through all rows for which the field p is less than or equal to 0.05.

When a predicate depends on parameters, debounce can delay replay until the dependencies have stopped changing for the specified number of milliseconds. It delays only dependency-triggered replay: parameter updates and new input data remain immediate. A completed input batch uses current parameter values and makes any pending replay unnecessary. The delay does not wait for an independently scheduled lazy load.

Filtering by a Selection Predicate¶

Category selection filters require a mapping from the declared channel to the field in the filtered data, for example:

{
  "type": "filter",
  "param": "activation_states",
  "fields": { "color": "activation_state" }
}

Matching uses raw typed category values. Empty selections retain all rows by default; empty: false retains none. Filtering can change inferred scale domains, while selected values remain stored if temporarily absent.

Interval selections in GenomeSpy are defined by their data extent along the x and/or y channels. When filtering data based on a selection, you must explicitly map the visual channels (x or y) to the corresponding data fields to ensure correct filtering. This ensures that the filter correctly interprets the selection in the context of your dataset.

{
  "description": "Filter transform example using a selection predicate.",

  "data": { "url": "data/sincos.csv" },

  "params": [{ "name": "brush" }],

  "vconcat": [
    {
      "height": 30,
      "transform": [
        { "type": "collect" },
        {
          "type": "filter",
          "param": "brush",
          "fields": { "x": "x", "y": "sin" }
        },
        { "type": "aggregate" },
        {
          "type": "formula",
          "as": "text",
          "expr": "datum.count + ' points selected'"
        }
      ],
      "mark": { "type": "text", "size": 20 },
      "encoding": {
        "text": { "field": "text" }
      }
    },
    {
      "params": [
        {
          "name": "brush",
          "value": { "x": [2.5, 4], "y": [-0.6, 0.6] },
          "select": { "type": "interval", "encodings": ["x", "y"] },
          "push": "outer"
        }
      ],
      "mark": { "type": "point", "size": 100 },
      "encoding": {
        "x": { "field": "x", "type": "quantitative" },
        "y": { "field": "sin", "type": "quantitative" }
      }
    }
  ]
}