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.
- 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
Add this line to your application's Gemfile:
gem "vg_helper"and run:
bundle installOr install it directly:
gem install vg_helperThen:
require "vg_helper"
require "rover"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"
)In Jupyter Notebook with IRuby, place the chart object at the end of the cell to display it directly:
chartA complete cell can simply end with:
chart = VGHelper.draw_xdate(
df,
"datetime",
"value",
"category"
)
chartThe same applies to charts created with draw_xnominal.
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 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.
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.
draw_xdate supports two time modes.
time_mode: :dayDates 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
)time_mode: :exactThe 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 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.
For large nominal datasets:
initialxpoints: 100controls the number of x positions initially displayed.
For example:
chart = VGHelper.draw_xnominal(
df,
"step",
"value",
"category",
initialxpoints: 100
)The x-axis range controls can be enabled or disabled.
xslide: trueor:
xslide: falseFor draw_xdate, the controls modify the temporal range.
For draw_xnominal, they modify the range of displayed x positions.
Y-axis controls can be enabled with:
yslide: trueand disabled with:
yslide: falseThe control type can also be selected:
yrangechanger: "number"or:
yrangechanger: "range"Explicit y ranges can be supplied where appropriate:
miny: 0,
maxy: 100Series visibility can be controlled interactively.
category_check: trueThis adds a checkbox for each category.
To hide these controls:
category_check: falseBoth 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.
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.
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.
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: trueThis places the main axis on the right and the secondary axis on the left.
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 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.
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.
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"
)VGHelper is still under development.
Planned features include:
- Export charts as images
- Improve customization of Vega-Lite parameters
- Improve documentation and examples
VGHelper currently uses:
- Ruby
vegarover
Vega, Vega-Lite, and Vega-Embed JavaScript runtimes are bundled for offline HTML output.
After checking out the repository:
bundle installRun the test suite with:
bundle exec rspecTo build the gem locally:
gem build vg_helper.gemspecBug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/vg_helper.
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.