PROVEGA

PROVEGA is an extension of Vega-Lite aimed at supporting progressive visualization. It introduces new properties under the provega namespace.

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "url": "data/large_dataset.csv"
  },
  "mark": "line",
  "encoding": {
    "x": { "field": "timestamp", "type": "temporal" },
    "y": { "field": "value", "type": "quantitative" }
  },
  "provega": {
    "progression": {
      "chunking": {
      },
      "control": {
      },
      "monitoring": {
      }
    }
  }
}

1. Progression

1. Progression

1.1 `chunking`

Defines how the data is chunked and read progressively. The type field is mandatory.

The reading field is used when the dataset is passed as a single CSV file (or JSON array) embedded in the spec, or as URL endpoint, and must be sampled and chunked progressively during rendering.

Alternatively, if the Vega-Lite data.values field already contains an array of arrays (each sub-array representing a pre-defined chunk), then only the reading.frequency value will be considered to control playback speed across these chunks.

Property	Type	Default	Description
`type`	"data" \| "process" \| "mixed"	– (required)	Specifies the chunking scope.
`reading.method`	"sequential" \| "random"	"sequential"	Sampling method for chunking when using a single dataset source.
`reading.ascending`	boolean	false	If `true`, reads data in ascending order.
`reading.chunk_size`	number	10	Number of items in each chunk.
`reading.frequency`	number (ms)	1000	Delay between chunk loads. Always applies if chunks are pre-defined.
`reading.seed`	number	0	Random seed for sampling (used when method is "random").

📄 Simple Example Making Data Chunking from a Dataset

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "values": [
      { "x": 1, "y": 5 }, 
      { "x": 2, "y": 10 },
      { "x": 3, "y": 15 }, 
      { "x": 4, "y": 20 },
      { "x": 5, "y": 25 },
      { "x": 6, "y": 30 },
      { "x": 7, "y": 35 },
      { "x": 8, "y": 40 },
      { "x": 9, "y": 45 },
      { "x": 10, "y": 50 }
    ]
  },
  "mark": "line",
  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "y", "type": "quantitative" }
  },
  "provega": {
    "progression": {
      "chunking": {
        "type": "data",
        "reading": {
          "frequency": 1000,
          "chunk_size": 2,
          "method": "sequential",
          "ascending": true
        }
      }
    }
  }
}

📄 Simple Example Using Pre-Chunks

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "values": [
      [ { "x": 1, "y": 5 }, { "x": 2, "y": 10 } ],
      [ { "x": 3, "y": 15 }, { "x": 4, "y": 20 } ],
      [ { "x": 5, "y": 25 } ]
    ]
  },
  "mark": "line",
  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "y", "type": "quantitative" }
  },
  "provega": {
    "progression": {
      "chunking": {
        "type": "data",
        "reading": {
          "frequency": 1000
        }
      }
    }
  }
}

1.2 `control`

Defines the control modes and interactions with the progressive process.

Property	Type	Default	Description
`mode`	"monitoring" \| "exploration"	"monitoring"	Shortcut for enabling/disabling control features.
`pause`	boolean	false	Enables pause capability.
`stop`	boolean	false	Enables stop capability.
`backward`	boolean	false	Enables backward traversal.
`min_frequency`	number (ms)	–	Minimum delay between results.
`min_rendering_frequency`	number \| null	null	Controls rendering update frequency.

1.3 `monitoring`

Adds monitoring tools to track progress and quality of progressive visualization.

Property	Type	Default	Description
`aliveness`	boolean	true	Shows spinner to indicate process is alive.
`etc`	string \| boolean	null	Estimated time to completion; variable name or `true` for default.
`progressbar`	boolean	true	Shows a progress bar.
`change`	Object	undefined	Tracks and visualizes changes in the visualization.
`change.area`	boolean (or Object)	false	Highlights the area of change in the visualization.
`change.mark`	boolean (or Object)	false	Highlights the marks that changed in the visualization.
`change.noise_reduction`	boolean	false	Enables noise filtering for change detection

1.3.1 `change.area`

It is possible to customize the appeareance of the change area. Instead of passing a sigle bool value to enable the change area, pass an object.

Property	Type	Default	Description
`change.area.active`	boolean	false	Highlights the area of change in the visualization.
`change.area.blink`	boolean	false	Enable the blinking.
`change.area.style.color`	string	red	Color of the area.
`change.area.style.opacity`	string	red	Opacity of the area.

1.3.2 `change.mark`

It is possible to customize the appeareance of the changed marks. Instead of passing a sigle bool value to enable the highlight, pass an object.

Property	Type	Default	Description
`change.mark.active`	boolean	false	Highlights the changed marks in the visualization.
`change.mark.blink`	boolean	false	Enable the blinking.
`change.mark.style.color`	string	red	Color of the mark.
`change.mark.style.opacity`	string	red	Opacity of the mark.

1.4 `quality`

Tracks various indicators of progressive quality. Each field is optional and accepts a variable name (string) or true for defaults.

Field	Subfields	Metadata Default
`absolute_progress`	on_data_input, on_result_output, on_visual_output	metadata.quality.absolute_progress.*
`relative_progress`	on_data_input, on_result_output, on_visual_output	metadata.quality.relative_progress.*
`relative_stability`	on_data_input, on_result_output, on_visual_output	metadata.quality.relative_stability.*
`absolute_certainty`	on_result_output	metadata.quality.absolute_certainty.on_result_output


  "quality": {
          "absolute_progress": {
            "on_data_input": true,
            "on_result_output": true,
            "on_visual_output": true
          },
          "relative_progress": {
            "on_data_input": true,
            "on_result_output": true,
            "on_visual_output": true
          },
          "relative_stability": {
            "on_data_input": true,
            "on_result_output": true,
            "on_visual_output": true
          },
          "absolute_certainty": {
            "on_result_output": true
          }
    }

📄 Example: Vega-Lite Spec with PROVEGA

This example demonstrates how to use provega properties in a Vega-Lite specification to enable progressive chunking and monitoring:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "url": "data/large_dataset.csv"
  },
  "mark": "line",
  "encoding": {
    "x": { "field": "timestamp", "type": "temporal" },
    "y": { "field": "value", "type": "quantitative" }
  },
  "provega": {
    "progression": {
      "chunking": {
        "type": "data",
        "reading": {
          "method": "sequential",
          "chunk_size": 20,
          "frequency": 500
        }
      },
      "control": {
        "mode": "exploration",
        "pause": true,
        "stop": true,
        "backward": true,
        "min_frequency": 300
      },
      "monitoring": {
        "aliveness": true,
        "progressbar": true,
        "change": {
          "area": true,
          "noise_reduction": true
        },
        "quality": {
          "absolute_progress": {
            "on_data_input": true
          }
        }
      }
    }
  }
}

PROVEGA

Table of Contents

1. Progression

1.1 chunking

📄 Simple Example Making Data Chunking from a Dataset

📄 Simple Example Using Pre-Chunks

1.2 control

1.3 monitoring

1.3.1 change.area

1.3.2 change.mark