vg_helper 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b01823993ada318ef29956c058158602b4648d28515f1051c3ffda4fd62fe67
-  data.tar.gz: ab70be22d50b15004b11e108faa16909d0d30fa51e7dca475375676cdcff9191
+  metadata.gz: 2142e0527c36a9586942961a2dd42efc1d48090b9ccf3990595a970aa38fbf9c
+  data.tar.gz: 771c7a1c68f1a3e7ed30932e243b1062c1d46defe35d42a91eeb8b25eff40981
 SHA512:
-  metadata.gz: 0615f0ecbaa49ab4d7c16adf60553344b4f1afda2f8b8693971f62bdca68830137627f83bbb65d7d3bd73bc3e8ef2d18a0b23a41174f4cd8d4c756679216dd69
-  data.tar.gz: fa7ea6f99167a1c3ae4805ec961070d1ef07bfa49568699a8179f39c8a2e43df47901affca3e8cdfd04861be87d5f626d967b28d8ad04c220b6fceb3ecb23a29
+  metadata.gz: 73e911c62c69a0710b6d0ca0d938e7b6b3883bdafea0709a94f031c858c17b49d8c4a7494e4521cc71779bb9978fed8d7df1f67677c031d220fe2b06de0658a8
+  data.tar.gz: ac1eb5d9cd9c3f47c3b08f34f61fa8f09ca6f67e8b686404daf9308af5a4333409cf9d8e32046d9227a37b59f3f781dbcfb59e9a887ad5ee9a1bc57b7820e565

data/README.md

@@ -1,34 +1,674 @@
-# VgHelper
+# VGHelper
 
-TODO: Delete this and the text below, and describe your gem
+VGHelper is a small Ruby helper library for creating interactive
+[Vega-Lite](https://vega.github.io/vega-lite/) charts from
+`Rover::DataFrame`.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/vg_helper`. To experiment with that code, run `bin/console` for an interactive prompt.
+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
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vg_helper"
+```
+
+and run:
+
+```sh
+bundle install
+```
+
+Or install it directly:
+
+```sh
+gem install vg_helper
+```
+
+Then:
+
+```ruby
+require "vg_helper"
+require "rover"
+```
+
+---
+
+## Quick Start
+
+```ruby
+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:
+
+```ruby
+chart
+```
+
+A complete cell can simply end with:
+
+```ruby
+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`:
+
+```ruby
+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.
+
+```ruby
+VGHelper.draw_xdate(
+  df,
+  x_col,
+  y_col,
+  category_col,
+  ...
+)
+```
+
+Basic example:
+
+```ruby
+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`.
+
+```ruby
+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
+
+```ruby
+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.
+
+```ruby
+chart = VGHelper.draw_xdate(
+  df,
+  "datetime",
+  "value",
+  "category",
+  time_mode: :day
+)
+```
+
+### Exact-time mode
+
+```ruby
+time_mode: :exact
+```
+
+The time of day is preserved.
+
+```ruby
+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:
+
+```ruby
+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:
+
+```text
+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:
+
+```ruby
+initialxpoints: 100
+```
+
+controls the number of x positions initially displayed.
+
+For example:
+
+```ruby
+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.
+
+```ruby
+xslide: true
+```
+
+or:
+
+```ruby
+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:
+
+```ruby
+yslide: true
+```
+
+and disabled with:
+
+```ruby
+yslide: false
+```
+
+The control type can also be selected:
+
+```ruby
+yrangechanger: "number"
+```
+
+or:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+yrangechanger: "range"
+```
+
+Explicit y ranges can be supplied where appropriate:
+
+```ruby
+miny: 0,
+maxy: 100
+```
+
+---
+
+## Category checkboxes
+
+Series visibility can be controlled interactively.
+
+```ruby
+category_check: true
+```
+
+This adds a checkbox for each category.
+
+To hide these controls:
+
+```ruby
+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:
+
+```text
+n
+avg
+std
+max
+min
+```
+
+For example:
+
+```text
+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.
+
+```ruby
+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.
+
+```ruby
+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:
+
+```text
+Product A : 10
+Product B : 15
+Product C : 5
+```
+
+it is treated as one observation:
+
+```text
+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:
+
+```ruby
+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`.
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+horizontallines: [
+  [20, "Target"],
+  [30, "Upper Limit"]
+]
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Colors can be specified separately:
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+horizontalcolors: [
+  "#0000ff",
+  "#ff0000"
+]
 ```
 
-## Usage
+Reference lines are useful for targets, limits, thresholds,
+specifications, and other fixed values.
 
-TODO: Write usage instructions here
+---
 
-## Development
+# Vertical reference lines
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Vertical reference lines can also be added.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+For a date chart:
+
+```ruby
+verticallines: [
+  ["2026-01-10", "Close"],
+  ["2026-01-20", "Restart"]
+]
+```
+
+For a nominal chart:
+
+```ruby
+verticallines: [
+  ["STEP_020", "Event A"],
+  ["STEP_050", "Event B"]
+]
+```
+
+Colors can be specified with:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```text
+vega.min.js
+vega-lite.min.js
+vega-embed.min.js
+```
+
+`write_htmls` embeds these JavaScript files directly into the output
+HTML.
+
+```ruby
+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:
+
+```ruby
+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:
+
+```sh
+bundle install
+```
+
+Run the test suite with:
+
+```sh
+bundle exec rspec
+```
+
+To build the gem locally:
+
+```sh
+gem build vg_helper.gemspec
+```
+
+---
 
 ## Contributing
 
@@ -37,3 +677,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/[USERN
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+The bundled Vega, Vega-Lite, and Vega-Embed JavaScript files remain
+subject to their respective licenses.
+
+Please see the relevant license files for details.

data/lib/vg_helper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VgHelper
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/vg_helper.rb

@@ -102,9 +102,9 @@ module VGHelper
 		               "#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf",
 					   "#393b79", "#637939", "#8c6d31", "#843c39", "#7b4173"] * 10)[0...(categories.length)]
 		horizontalcolors ||= (["#0000ff", "#ff0000"] * 6)[0...(horizontallines.length)]
-		colorset += horizontalcolors
+		# colorset += horizontalcolors
 		verticalcolors ||= (["#0000ff", "#ff0000"] * 6)[0...(verticallines.length)]
-		colorset += verticalcolors
+		# colorset += verticalcolors
 
 		x1_msec = values1[x_col].to_a.map { |v| udate(v) }
 
@@ -264,8 +264,8 @@ module VGHelper
 					y: { 
 						field: y_col,
 						type: "quantitative",
-						scale: { domain: [{expr: "min_y"}, {expr: "max_y"}] },
-						axis: nil
+						scale: { domain: [{expr: "min_y"}, {expr: "max_y"}] }
+						#axis: nil
 					},
 					color: {
 						field: category_col,
@@ -655,12 +655,17 @@ module VGHelper
 			.width(width)
 			.height(height)
 
-		if !v2_array.empty?
-			builder = builder.resolve(
-				scale: { y: "independent", color: "independent", x: "shared" },
-				axis: { x: "shared" }
+		resolve_scale = {
+			color: "independent",
+			x: "shared"
+			}
+
+		resolve_scale[:y] = "independent" unless v2_array.empty?
+
+		builder = builder.resolve(
+			scale: resolve_scale,
+			axis: { x: "shared" }
 			)
-		end
 
 		builder
 		
@@ -1176,21 +1181,11 @@ module VGHelper
 
 			encoding: {
 				y: {
-				field:
-					y_col_str,
-
-				type:
-					"quantitative",
-
-				scale: {
-					domain:
-					ydomain
-				},
-
-				axis:
-					nil
+					field: y_col_str,
+					type: "quantitative",
+					scale: { domain: ydomain }
+					#axis: nil 
 				},
-
 				color: {
 				field:
 					category_col_str,
@@ -1539,29 +1534,26 @@ module VGHelper
 		############################
 		# Build
 		############################
-
+		
 		builder =
 			Vega.lite
-			.data(values: all_data)
-			.params(params)
-			.encoding(x: x_encoding)
-			.layer(layers)
-			.width(width)
-			.height(height)
-			.title(title)
+				.data(values: all_data)
+				.params(params)
+				.encoding(x: x_encoding)
+				.layer(layers)
+				.width(width)
+				.height(height)
+				.title(title)
+
+		resolve_scale = {
+			color: "independent"
+			}
 
-		unless v2_array.empty?
-			builder =
-			builder.resolve(
-				scale: {
-				y:
-					"independent",
+			resolve_scale[:y] = "independent" unless v2_array.empty?
 
-				color:
-					"independent"
-				}
+		builder = builder.resolve(
+			scale: resolve_scale
 			)
-		end
 
 		builder
 	end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vg_helper
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - showata
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-25 00:00:00.000000000 Z
+date: 2026-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rover-df