Skip to main content

Custom Visualization

XetHub supports custom visualizations that stay up-to-date with the data in your repository, rendered live in the browser.

  • Supported data types: CSV, TSV, JSON
  • Supported visualization formats: Vega, Vega-Lite
note

Want us to support more data types or formats? File a feature request to let us know!

Vega and Vega-Lite​

XetHub's custom visualizations are powered by Vega and Vega-Lite. Vega is a specification language in JSON to describe visualizations of data; Vega-Lite is a higher level, simpler specification language on top of Vega. They both work by on the principle of a visualization grammar: a declarative language for creating, saving, and sharing interactive visualization designs.

You can see examples of what's possible in Vega and Vega-Lite here and here.

Example Visualization: Simple Bar Chart​

Suppose you have a repository with a .json file named data.json, containing the following:

[
  {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43},
  {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53},
  {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52}
]

In the same repo, you can add a custom visualization of this data using the file extensions .vg.json (for Vega) or .vl.json (for Vega-Lite). Let's add a file named visualization.vl.json:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "A simple bar chart.",
  "data": {"url": "data.json"},
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "nominal"},
    "y": {"field": "b", "type": "quantitative"}
  }
}

Note that to refer to the data, the URL data.json is given on the line "data": {"url": "data.json"}. This URL is a relative PATH to the data within the same repository.

The resulting visualization, when rendered, will look like this:

Where it appears​

Custom visualizations appear rendered in the following places:

  • Folder views that contain the custom visualization specifications (.vg.json or .vl.json).
  • File views and diffs of the visualization specifications (.vg.json or .vl.json).
  • File views and diffs of data (.csv, .tsv, .json) referenced by a visualization specification (.vg.json, .vl.json).

You can see an example of this in the root of the CalTech Birds Image Similarity repository.

Limitations​

Currently, custom visualizations are fully rendered in the browser and fetch all referenced data on demand. If the referenced data is quite large (beyond perhaps a few hundred MB), it may take a long time to download, and may slow down or even make the page unresponsive. In this case, you might consider committing sampled or aggregated data to the repository and referencing that instead.