Data Visualization

Snow Flower Text supports data visualization with Vega and Vega-Lite. You can embed data visualization diagrams in AsciiDoc documents by writing text in JSON format of the Vega specification.Snow Flower Text has a built-in Vega engine, so You can get started without any additional installation.

The vega block is a proprietary extension of Snow Flower Text. The images visualized by Vega are pre-rendered so that the load does not increase, so you can continue comfortable editing while checking the preview even if you embed more figures in the document.

Vega is a language for describing visualizations. It is designed as a language to handle data visualization, just like a SQL language to handle data. Vega-Lite is a high-level language built on top of Vega for the rapid creation of statistical graphics. Vega’s design is based on years of research and development at Stanford University and the University of Washington.

This article explains how to use the vega block. If you want to know more about the JSON of the Vega and Vega-Lite specifications, please refer to the following URL

Features

AsciiDoc documents can simply embed images with the image macro, but Snow Flower Text’s Vega extension is superior in the following ways

Easy data exchange: The Vega and Vega-Lite specifications define visualizations in JSON format only. The targets for data exchange are clear and easy, and a rich set of sample sources can be edited and used as templates.
Findable: The labels of rendered data visualization diagrams remain text-searchable. This feature is inherited even after exporting to formats such as HTML, PDF, and DocBook. The findability is better than embedding raster images.
Change traceable: Write in highly readable text. Therefore, changes in different versions can be easily found by text comparison. This is an excellent feature that office software that holds information in binary does not have. It has better traceability than binary format files.
Vector image: Since the visualization is a vector image, it renders clearly on any medium. No matter how much you zoom in, there will be no jaggies. Portability is better than embedding raster images.

How to use vega blocks

You can visualize your data using the Vega and VagaLite data visualization languages by using the vega block. Write as follows.

[vega]
----
Vega or VegaLite JSON
----

In a vega block, define a visualization diagram in JSON of the Vega or Vega-Lite specification. The Snow Flower Text vega block automatically distinguishes between Vega-specification JSON and Vega-Lite-specification JSON.

For example, a simple bar chart would be written in Vega-Lite as follows:

[vega]
----
{
  "width": 600,
  "data": {
    "values": [
      {"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}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
    "y": {"field": "b", "type": "quantitative"}
  }
}
----

It is rendered as:

Simple bar chart

Proper use of Vega and Vega-Lite

Vega-Lite is always converted to Vega before it is converted to a vector image, and during the Vega-Lite to Vega conversion, definitions are added for statistical charts such as axes, legends, and scales.

Vega-Lite can also be used to represent diagrams that can be represented in Vega, but for general statistical diagrams, Vega-Lite is recommended in preference to Vega because it is more concise and easier to read.

Localization of formatting

By specifying the locale code in the block parameter, the format of the numeric, currency, and date presets can be adapted to the locale. The locale code is a short IETF standardized code.

The following parameters can be specified

localeNumber

Specifies the locale for the number formatting. In the current version, the following locale codes can be specified. If you specify a locale code that is not supported, it will be ignored.

de-DE
en-CA
en-GB
en-US
es-ES
fr-CA
fr-FR
it-IT
ja-JP
ko-KR
nl-NL
pl-PL
pt-BR
ru-RU
sv-SE
zh-CN
zh-TW

localeTime

Specifies the locale for the time format. In the current version, the following locale codes can be specified. If you specify a locale code that is not supported, it will be ignored.

da-DK
de-DE
en-CA
en-GB
en-US
es-ES
fr-CA
fr-FR
it-IT
ja-JP
ko-KR
nl-NL
pl-PL
pt-BR
ru-RU
sv-SE
zh-CN
zh-TW

The preset formatting can be applied by specifying the locale code in localTime.

In the following example, ja-JP (Japanese locale) is specified.

[vega, localeTime="ja-JP"]
----------------------------------------
{
  "width": 600,
  "data": {"url": "https://vega.github.io/editor/data/seattle-weather.csv"},
  "mark": "bar",
  "encoding": {
    "x": {
      "timeUnit": "month",
      "field": "date",
      "type": "ordinal",
      "title": "Month of the year"
    },
    "y": {
      "aggregate": "count",
      "type": "quantitative"
    },
    "color": {
      "field": "weather",
      "type": "nominal",
      "scale": {
        "domain": ["sun", "fog", "drizzle", "rain", "snow"]
      },
      "title": "Weather type"
    }
  }
}
----------------------------------------

It is rendered as: The x-axis is in the format of the specified locale.

Table 1. ロケールコード一覧
Locale code	Language	Location
`da-DK`	Danish	Denmark
`de-DE`	German	Germany
`en-CA`	English	Canada
`en-GB`	English	United Kingdom
`en-US`	English	United States
`es-ES`	Spanish	Spain
`fr-CA`	French	Canada
`fr-FR`	French	France
`it-IT`	Italian	Italy
`ja-JP`	Japanese	Japan
`ko-KR`	Korean	Korea
`nl-NL`	Dutch	Netherlands
`pl-PL`	Polish	Poland
`pt-BR`	Portuguese	Brazil
`ru-RU`	Russian	Russia
`sv-SE`	Swedish	Sweden
`zh-CN`	Chinese (Simplified)	People’s Republic of China
`zh-TW`	Chinese (Traditional)	Taiwan

Color schemes

Vega provides carefully designed preset color schemes that can be effectively applied to categorical data. In particular, the following preset color schemes are easy to use for many people with color blindness.

tableau10

category10

tableau20

category20

In the following example, the color scheme of tableau10 is specified for coloring the a field.

[vega]
----
{
  "width": 600,
  "data": {
    "values": [
      {"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}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {
    	"field": "a",
    	"type": "nominal",
    	"axis": {"labelAngle": 0}
    },
    "y": {
    	"field": "b",
    	"type": "quantitative"
    },
    "color": {
    	"field": "a",
    	"scale": {"scheme": "tableau10"}
    }
  }
}
----

It is rendered as:

{“scheme”: “tableau10”}

For other color schemes, please refer to the “Scheme Reference” article at the following URL

https://vega.github.io/vega/docs/schemes/

You can also create and use your own custom color palette. For example, it can be useful to create a color scheme that matches your company’s brand. For more information, please refer to the article “Registering Additional Schemes” at the following URL

https://vega.github.io/vega/docs/schemes/

Proper use of vega and chart blocks

Snow Flower Text’s AsciiDoc extension has a chart block to support drawing of bar charts, line charts, etc. The vega and chart blocks partially overlap in functionality, but have different characteristics. The vega block notation is more difficult to write than the chart block, but the vega block has a wider range of representation. This is a tradeoff.

Features of the chart block and vega block

Reference

Overview
- vega.github.io/vega/docs/
- vega.github.io/vega-lite/docs/
Example Gallery
- vega.github.io/vega-lite/examples/
- vega.github.io/vega/examples/
Color Schemes
- vega.github.io/vega/docs/schemes/

Appendix A: Sample source

Bar chart

A simple bar chart with embedded data.

[vega]
----
{
  "width": 600,
  "data": {
    "values": [
      {"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}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
    "y": {"field": "b", "type": "quantitative"}
  }
}
----

Horizontal Bar chart

You can lay out horizontally by exchanging x and y in the Bar chart.

[vega]
----
{
  "width": 600,
  "data": {
    "values": [
      {"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}
    ]
  },
  "mark": "bar",
  "encoding": {
    "y": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
    "x": {"field": "b", "type": "quantitative"}
  }
}
----

Stacked Bar char

[vega]
----
{
  "width": 600,
  "data": {"url": "https://vega.github.io/editor/data/seattle-weather.csv"},
  "mark": "bar",
  "encoding": {
    "x": {
      "timeUnit": "month",
      "field": "date",
      "type": "ordinal",
      "title": "Month of the year"
    },
    "y": {
      "aggregate": "count",
      "type": "quantitative"
    },
    "color": {
      "field": "weather",
      "type": "nominal",
      "scale": {
        "domain": ["sun", "fog", "drizzle", "rain", "snow"]
      },
      "title": "Weather type"
    }
  }
}
----

Horizontal Stacked Bar char

[vega]
----
{
  "width": 600,
  "data": {"url": "https://vega.github.io/editor/data/seattle-weather.csv"},
  "mark": "bar",
  "encoding": {
    "y": {
      "timeUnit": "month",
      "field": "date",
      "type": "ordinal",
      "title": "Month of the year"
    },
    "x": {
      "aggregate": "count",
      "type": "quantitative"
    },
    "color": {
      "field": "weather",
      "type": "nominal",
      "scale": {
        "domain": ["sun", "fog", "drizzle", "rain", "snow"]
      },
      "title": "Weather type"
    }
  }
}
----

Grouped bar char

[vega]
----
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": { "url": "https://vega.github.io/editor/data/population.json"},
  "transform": [
    {"filter": "datum.year == 2000"},
    {"calculate": "datum.sex == 2 ? 'Female' : 'Male'", "as": "gender"}
  ],
  "width": {"step": 12},
  "mark": "bar",
  "encoding": {
    "column": {
      "field": "age", "type": "ordinal", "spacing": 10
    },
    "y": {
      "aggregate": "sum", "field": "people",
      "title": "population",
      "axis": {"grid": false}
    },
    "x": {
      "field": "gender",
      "axis": {"title": ""}
    },
    "color": {
      "field": "gender",
      "scale": {"range": ["#675193", "#ca8861"]}
    }
  },
  "config": {
    "view": {"stroke": "transparent"},
    "axis": {"domainWidth": 1}
  }
}
----

Line chart

[vega]
----
{
  "width": 600,
  "data": {"url": "https://vega.github.io/vega-lite/examples/data/stocks.csv"},
  "transform": [{"filter": "datum.symbol==='GOOG'"}],
  "mark": "line",
  "encoding": {
    "x": {"field": "date", "type": "temporal"},
    "y": {"field": "price", "type": "quantitative"}
  }
}
----

Area chart

[vega]
----
{
  "width": 600,
  "data": {
    "url": "https://vega.github.io/vega-lite/examples/data/penguins.json"
  },
  "mark": "area",
  "transform": [
    {
      "density": "Body Mass (g)",
      "groupby": ["Species"],
      "extent": [2500, 6500]
    }
  ],
  "encoding": {
    "x": {"field": "value", "type": "quantitative", "title": "Body Mass (g)"},
    "y": {"field": "density", "type": "quantitative", "stack": "zero"},
    "color": {"field": "Species", "type": "nominal"}
  }
}
----

Pie chart

[vega]
----
{
  "data": {
    "values": [
      {"category": 1, "value": 4},
      {"category": 2, "value": 6},
      {"category": 3, "value": 10},
      {"category": 4, "value": 3},
      {"category": 5, "value": 7},
      {"category": 6, "value": 8}
    ]
  },
  "mark": "arc",
  "encoding": {
    "theta": {"field": "value", "type": "quantitative"},
    "color": {"field": "category", "type": "nominal"}
  },
  "view": {"stroke": null}
}
----

Ring chart

[vega]
----
{
  "data": {
    "values": [
      {"category": 1, "value": 4},
      {"category": 2, "value": 6},
      {"category": 3, "value": 10},
      {"category": 4, "value": 3},
      {"category": 5, "value": 7},
      {"category": 6, "value": 8}
    ]
  },
  "mark": {"type": "arc", "innerRadius": 50},
  "encoding": {
    "theta": {"field": "value", "type": "quantitative"},
    "color": {"field": "category", "type": "nominal"}
  },
  "view": {"stroke": null}
}
----

2D Histogram Scatterplot

[vega]
----
{
  "width": 400,
  "data": {"url": "https://vega.github.io/vega-lite/examples/data/movies.json"},
  "mark": "circle",
  "encoding": {
    "x": {
      "bin": {"maxbins": 10},
      "field": "IMDB Rating"
    },
    "y": {
      "bin": {"maxbins": 10},
      "field": "Rotten Tomatoes Rating"
    },
    "size": {"aggregate": "count"}
  }
}
----

Heatmap

[vega]
----
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
      "url": "https://vega.github.io/vega/data/seattle-weather.csv"
  },
  "title": "Daily Max Temperatures (C) in Seattle, WA",
  "config": {
      "view": {
          "strokeWidth": 0,
          "step": 13
      },
      "axis": {
          "domain": false
      }
  },
  "mark": "rect",
  "encoding": {
      "x": {
          "field": "date",
          "timeUnit": "date",
          "type": "ordinal",
          "title": "Day",
          "axis": {
              "labelAngle": 0,
              "format": "%e"
          }
      },
      "y": {
          "field": "date",
          "timeUnit": "month",
          "type": "ordinal",
          "title": "Month"
      },
      "color": {
          "field": "temp_max",
          "aggregate": "max",
          "type": "quantitative",
          "legend": {
              "title": null
          }
      }
  }
}
----

Sun Burst

[vega]
----
{
  "$schema": "https://vega.github.io/schema/vega/v5.json",
  "width": 600,
  "height": 600,
  "padding": 5,
  "autosize": "none",
  "data": [
    {
      "name": "tree",
      "url": "https://vega.github.io/vega/data/flare.json",
      "transform": [
        {
          "type": "stratify",
          "key": "id",
          "parentKey": "parent"
        },
        {
          "type": "partition",
          "field": "size",
          "sort": {"field": "value"},
          "size": [{"signal": "2 * PI"}, {"signal": "width / 2"}],
          "as": ["a0", "r0", "a1", "r1", "depth", "children"]
        }
      ]
    }
  ],
  "scales": [
    {
      "name": "color",
      "type": "ordinal",
      "domain": {"data": "tree", "field": "depth"},
      "range": {"scheme": "tableau20"}
    }
  ],
  "marks": [
    {
      "type": "arc",
      "from": {"data": "tree"},
      "encode": {
        "enter": {
          "x": {"signal": "width / 2"},
          "y": {"signal": "height / 2"},
          "fill": {"scale": "color", "field": "depth"},
          "tooltip": {"signal": "datum.name + (datum.size ? ', ' + datum.size + ' bytes' : '')"}
        },
        "update": {
          "startAngle": {"field": "a0"},
          "endAngle": {"field": "a1"},
          "innerRadius": {"field": "r0"},
          "outerRadius": {"field": "r1"},
          "stroke": {"value": "white"},
          "strokeWidth": {"value": 0.5},
          "zindex": {"value": 0}
        },
        "hover": {
          "stroke": {"value": "red"},
          "strokeWidth": {"value": 2},
          "zindex": {"value": 1}
        }
      }
    }
  ]
}
----