VGHelper

VGHelper is a small Ruby helper library for creating interactive Vega-Lite charts from Rover::DataFrame.

It provides convenient helpers for time-series and nominal x-axis charts, with support for multiple categories, secondary y-axes, reference lines, interactive range controls, brush statistics, and offline HTML output.

One of the main goals of VGHelper is to make Vega-Lite charts usable even in offline or proxy-restricted environments.

VGHelper bundles the JavaScript runtimes required by Vega, Vega-Lite, and Vega-Embed, so HTML generated by VGHelper does not need to load these libraries from an external CDN.

Features

  • Time-series charts (draw_xdate)
  • Nominal / categorical x-axis charts (draw_xnominal)
  • Multiple series and multiple category columns
  • Line charts with optional point markers
  • Secondary y-axis with bar charts
  • Stacked bars using a secondary category
  • Horizontal reference lines
  • Vertical reference lines
  • Configurable colors for reference lines
  • Interactive x-axis range controls
  • Interactive y-axis range controls
  • Category visibility checkboxes
  • Brush selection
  • Statistics for the selected / displayed range
    • count
    • mean
    • standard deviation
    • maximum
    • minimum
  • Statistics based on total stacked-bar height for the secondary axis
  • Daily and exact-time modes for temporal data
  • Reversible left/right y-axis orientation
  • Self-contained offline HTML output
  • No CDN access required for generated HTML

Installation

Add this line to your application's Gemfile:

gem "vg_helper"

and run:

bundle install

Or install it directly:

gem install vg_helper

Then:

require "vg_helper"
require "rover"

Quick Start

require "vg_helper"
require "rover"

df = Rover::DataFrame.new(
  {
    "datetime" => [
      "2026-01-01 10:00:00",
      "2026-01-02 10:00:00",
      "2026-01-03 10:00:00",
      "2026-01-04 10:00:00"
    ],
    "category" => [
      "A", "A", "A", "A"
    ],
    "value" => [
      10, 15, 12, 18
    ]
  }
)

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "value",
  "category"
)

Jupyter Notebook / IRuby

In Jupyter Notebook with IRuby, place the chart object at the end of the cell to display it directly:

chart

A complete cell can simply end with:

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "value",
  "category"
)

chart

The same applies to charts created with draw_xnominal.

Offline HTML output

To write the chart to an HTML file instead, use write_htmls:

VGHelper.write_htmls(chart, "chart.html")

write_htmls uses the bundled vega.min.js, vega-lite.min.js, and vega-embed.min.js files. The generated HTML does not load these libraries from a CDN and can be viewed without a network connection.

Open chart.html in a browser to view the interactive chart.

draw_xdate

draw_xdate creates a chart with a temporal x-axis.

VGHelper.draw_xdate(
  df,
  x_col,
  y_col,
  category_col,
  ...
)

Basic example:

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "temperature",
  "station"
)

The fourth argument specifies the column used to separate the data into series.

Multiple category columns

An array of columns can be supplied as category_col.

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "temperature",
  ["pref", "city"]
)

VGHelper combines the values internally and treats each combination as an independent series.

Time modes

draw_xdate supports two time modes.

Daily mode

time_mode: :day

Dates are normalized to the beginning of each calendar day.

This is useful when the time of day is irrelevant and the x-axis should represent daily observations.

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "value",
  "category",
  time_mode: :day
)

Exact-time mode

time_mode: :exact

The time of day is preserved.

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "value",
  "category",
  time_mode: :exact
)

Use this for hourly, minute-level, or other intraday data.

draw_xnominal

draw_xnominal creates a chart whose x-axis consists of discrete ordered values.

For example:

df = Rover::DataFrame.new(
  {
    "step" => [
      "STEP_001",
      "STEP_002",
      "STEP_003",
      "STEP_004"
    ],
    "value" => [
      10, 13, 18, 16
    ],
    "category" => [
      "A", "A", "A", "A"
    ]
  }
)

chart = VGHelper.draw_xnominal(
  df,
  "step",
  "value",
  "category"
)

The original order of x values is preserved.

This makes draw_xnominal useful for data such as:

STEP_001
STEP_002
STEP_003
...

where the x values are categories but their sequence is meaningful.

Limiting the initial x range

For large nominal datasets:

initialxpoints: 100

controls the number of x positions initially displayed.

For example:

chart = VGHelper.draw_xnominal(
  df,
  "step",
  "value",
  "category",
  initialxpoints: 100
)

Interactive controls

X-axis controls

The x-axis range controls can be enabled or disabled.

xslide: true

or:

xslide: false

For draw_xdate, the controls modify the temporal range.

For draw_xnominal, they modify the range of displayed x positions.

Y-axis controls

Y-axis controls can be enabled with:

yslide: true

and disabled with:

yslide: false

The control type can also be selected:

yrangechanger: "number"

or:

yrangechanger: "range"

Explicit y ranges can be supplied where appropriate:

miny: 0,
maxy: 100

Category checkboxes

Series visibility can be controlled interactively.

category_check: true

This adds a checkbox for each category.

To hide these controls:

category_check: false

Brush selection and statistics

Both chart helpers support interactive x-axis brush selection.

Drag across part of the chart to select a range.

VGHelper displays statistics for the selected data:

n
avg
std
max
min

For example:

temperature  n: 32  avg: 21.45  std: 2.18  max: 25.60  min: 17.90

When no smaller brush range is selected, the statistics correspond to the currently displayed range.

Category visibility settings are also reflected in the statistics.

Secondary y-axis

A second Rover::DataFrame can be displayed as bars using a secondary y-axis.

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "temperature",
  "station",

  df2: volume_df,
  x2_col: "datetime",
  y2_col: "volume"
)

This produces a main chart together with bars using an independent y scale.

Stacked secondary-axis bars

A category can also be assigned to the secondary data.

chart = VGHelper.draw_xdate(
  df,
  "datetime",
  "temperature",
  "station",

  df2: volume_df,
  x2_col: "datetime",
  y2_col: "volume",
  y2_category_col: "product"
)

Rows sharing the same x position are displayed as stacked bars.

For statistical calculations, VGHelper first calculates the total height of each stacked bar.

For example, if one x position contains:

Product A : 10
Product B : 15
Product C : 5

it is treated as one observation:

30

The mean, standard deviation, maximum, minimum, and count displayed for the secondary axis are then calculated from these stacked totals, rather than from the individual bar segments.

Axis orientation

By default, the main y-axis is displayed on the left and the secondary y-axis on the right.

The orientation can be reversed:

reverse_orient: true

This places the main axis on the right and the secondary axis on the left.

Horizontal reference lines

Horizontal reference lines can be added with horizontallines.

horizontallines: [
  [20, "Target"],
  [30, "Upper Limit"]
]

Colors can be specified separately:

horizontalcolors: [
  "#0000ff",
  "#ff0000"
]

Reference lines are useful for targets, limits, thresholds, specifications, and other fixed values.

Vertical reference lines

Vertical reference lines can also be added.

For a date chart:

verticallines: [
  ["2026-01-10", "Close"],
  ["2026-01-20", "Restart"]
]

For a nominal chart:

verticallines: [
  ["STEP_020", "Event A"],
  ["STEP_050", "Event B"]
]

Colors can be specified with:

verticalcolors: [
  "#0000ff",
  "#ff0000"
]

Vertical lines can be used to indicate important x positions.

Custom marks

The Vega-Lite mark definition can be customized with markkind.

For example:

markkind: {
  type: "line",
  point: {
    filled: true,
    size: 40
  },
  tooltip: true
}

This allows VGHelper to expose Vega-Lite's mark configuration while providing convenient defaults.

Offline HTML output

VGHelper is designed to work without access to external CDNs.

The gem bundles local copies of:

vega.min.js
vega-lite.min.js
vega-embed.min.js

write_htmls embeds these JavaScript files directly into the output HTML.

VGHelper.write_htmls(
  chart,
  "chart.html"
)

The resulting file can therefore be opened without accessing jsDelivr, unpkg, or another CDN.

This can be particularly useful in:

  • corporate proxy environments
  • restricted networks
  • isolated analysis environments
  • offline machines

Multiple charts can also be written to the same HTML file:

VGHelper.write_htmls(
  [chart1, chart2, chart3],
  "charts.html"
)

TODO

VGHelper is still under development.

Planned features include:

  • [ ] Export charts as images
  • [ ] Improve customization of Vega-Lite parameters
  • [ ] Improve documentation and examples

Dependencies

VGHelper currently uses:

  • Ruby
  • vega
  • rover

Vega, Vega-Lite, and Vega-Embed JavaScript runtimes are bundled for offline HTML output.

Development

After checking out the repository:

bundle install

Run the test suite with:

bundle exec rspec

To build the gem locally:

gem build vg_helper.gemspec

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/vg_helper.

License

The gem is available as open source under the terms of the MIT License.

The bundled Vega, Vega-Lite, and Vega-Embed JavaScript files remain subject to their respective licenses.

Please see the relevant license files for details.