rbplotly 0.1.2 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a5824c809b3bf7260b81eacf6b77ab986ab93f5e
-  data.tar.gz: 7199d7e10c9fa43b2cf61f601e68db6b1949e3c2
+SHA256:
+  metadata.gz: 3ee3bc96889cfdc7042b4cb2d4f493003ede009bb78ac14f59b2ff78aa56345c
+  data.tar.gz: e395c9e2230df5996b6a91a1757b4d72cd9829149aad82e7ba0acc3dac066c60
 SHA512:
-  metadata.gz: e37858b56eff737d8622fa3d8c4304370cf16805717df885cc197dfcf472e78d3f47a76d41a9ef55a9410a5f17751494c877d4f156a40edc4cb83c740114b34a
-  data.tar.gz: e7e11ff2ae577e8eb5a91831915196067faa028d54a0275704f75b4c37bdb294ae33639093ce67bb1a345079615600c23402aa291d59667e582aa35f8e8d4d01
+  metadata.gz: c05da261022f1d36806155a0f1f004e17c020e5451b79daf09daeb8f28d2820fd0cd90aa73444109c0516fd6b126745a74b28fa721261e941572fb857e9f7288
+  data.tar.gz: 46fa94b5913d6dfc0b37a5dd5761c59f7c775823b6bc02c41630c94ee7995d418d4676268086a6652fdd1a680c256a0f1205ef044a19892ac2bc5c47d992a306

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-10-07
+
+### Added
+
+- Relative subplot sizes through `column_widths` and `row_heights`, and per-cell right y
+  axes through `specs: [[{secondary_y: true}]]`. Trace placement, trace updates and y-axis
+  updates accept `secondary_y`; existing primary axis numbering is preserved.
+- Animation frames through `Figure.new(frames:)`, `add_frame` and `frames=`, with validation
+  of partial trace/layout updates and inclusion in JSON output. HTML and notebook output
+  register frames and start playback; `to_html` and `write_html` accept `auto_play` and
+  `animation_opts`.
+- Runnable examples for secondary axes and animation.
+
+### Fixed
+
+- Require `json >= 2.9` to avoid the older `script_safe` bug that corrupts characters such
+  as `瀨` and `倩` in chart labels and JSON output.
+- Reject negative, non-finite and out-of-range subplot spacing instead of silently
+  overlapping or collapsing cells; reject invalid row/column counts before calculating defaults.
+
+## [1.0.0] - 2026-10-07
+
+A rewrite. Figures are now plain hashes checked against the plot schema of a pinned
+plotly.js release, instead of hand-written classes that covered a few attributes.
+
+### Added
+
+- `Plotly::Figure` with `add_trace`, an `add_<type>` helper for each of plotly.js' 47 trace
+  types, `update_layout`, `update_traces` (with `selector:`), `update_xaxes`, `update_yaxes`
+  and `update_config`.
+- Validation of attribute names, enumerated values, flag lists, booleans and number ranges
+  against plotly.js 4.1.2, with the attribute path and a spelling suggestion in
+  `Plotly::ValidationError`. `validate: false` turns it off.
+- Underscore paths for nested attributes: `marker_line_width: 2`.
+- `Plotly.make_subplots` with shared axes and subplot titles; `row:` / `col:` on trace and
+  axis updates.
+- `include_plotlyjs:` (`:cdn`, `:inline`, `false` or a URL), `div_id:`, `width:`, `height:`
+  and `full_html:` on `to_html`; `write_html` embeds plotly.js by default so files work offline.
+- `to_json` / `to_h`. Dates and times, `NaN`, ranges, `BigDecimal` and objects with `#to_a`
+  (Numo, Polars, Daru columns) are converted to what plotly.js expects.
+- An example gallery (`rake gallery`) and specs that draw the generated HTML in headless Chrome.
+
+### Changed
+
+- Requires Ruby 3.3 or later.
+- Bundles plotly.js 4.1.2 (was 1.16.2). The CDN URL is pinned to the same release instead of
+  `plotly-latest`, which stopped updating at 1.x.
+- JSON inside `<script>` is escaped so that strings such as `"</script>"` cannot end the
+  element.
+- Charts resize with their container through plotly.js' `responsive` config.
+- No runtime dependencies besides `json` (`faraday`, `uuidtools` and `launchy` are gone).
+
+### Fixed
+
+- Charts render in JupyterLab: notebook output no longer relies on RequireJS, and
+  `to_iruby_mimebundle` keeps IRuby 0.8 from choosing `to_html`, whose script would run
+  before plotly.js loads ([#10](https://github.com/ash1day/rbplotly/issues/10)).
+- Subplots are supported ([#8](https://github.com/ash1day/rbplotly/issues/8)).
+- Tests run without a plot.ly account, and the README explains how to run them
+  ([#9](https://github.com/ash1day/rbplotly/issues/9)).
+
+### Deprecated
+
+- `Plotly::Plot`. It still accepts `data:` / `layout:` and `generate_html(path:, open:)`,
+  and prints a warning; use `Plotly::Figure` and `write_html`. It will be removed in 2.0.
+
+### Removed
+
+- `Plotly.auth`, `Plotly::Client` and `#download_image`, which used the plot.ly cloud API.
+- The attribute classes (`Plotly::Data`, `Layout`, `Axis`, `Marker`, `Line`) and
+  `Object#convert_to`, which was added to every object.
+
+## [0.1.2] - 2017-05-24
+
+The last 0.x release. See the [git history](https://github.com/ash1day/rbplotly/commits/v0.1.2).
+
+[Unreleased]: https://github.com/ash1day/rbplotly/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/ash1day/rbplotly/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/ash1day/rbplotly/compare/v0.1.2...v1.0.0
+[0.1.2]: https://github.com/ash1day/rbplotly/releases/tag/v0.1.2

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 y4ashida
+Copyright (c) 2016-2026 Yoshihiro Ashida
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,88 +1,251 @@
-[![Gem Version](https://badge.fury.io/rb/rbplotly.svg)](https://badge.fury.io/rb/rbplotly)
-[![Dependency Status](https://gemnasium.com/badges/github.com/ash1day/rbplotly.svg)](https://gemnasium.com/github.com/ash1day/rbplotly)
-[![Build Status](https://travis-ci.org/ash1day/rbplotly.svg?branch=master)](https://travis-ci.org/ash1day/rbplotly)
-[![Test Coverage](https://codeclimate.com/github/ash1day/rbplotly/badges/coverage.svg)](https://codeclimate.com/github/ash1day/rbplotly/coverage)
-[![Code Climate](https://codeclimate.com/github/ash1day/rbplotly/badges/gpa.svg)](https://codeclimate.com/github/ash1day/rbplotly)
+# rbplotly
 
-# Rbplotly
+[![Gem Version](https://img.shields.io/gem/v/rbplotly)](https://rubygems.org/gems/rbplotly)
+[![CI](https://github.com/ash1day/rbplotly/actions/workflows/ci.yml/badge.svg)](https://github.com/ash1day/rbplotly/actions/workflows/ci.yml)
 
-Rbplotly, a Ruby visualization library, allows you to create interactive plots.
+**Interactive [Plotly.js](https://plotly.com/javascript/) charts from Ruby.** Hover, zoom and
+pan in the browser, from a few lines of plain Ruby, in a single HTML file you can send anyone.
 
-## Installation
+<img src="docs/images/hero.gif" width="800" alt="Hovering over a line chart made with rbplotly shows the values for each day; dragging zooms into a range and a double-click zooms back out">
 
-Add this line to your application's Gemfile:
+## Why rbplotly
 
-```ruby
-gem 'rbplotly'
+- **All of plotly.js, nothing invented.** Every chart type (47 of them, from bar charts to 3D
+  surfaces, Sankey diagrams and maps) and every attribute in the
+  [plotly.js reference](https://plotly.com/javascript/reference/) works as written there.
+  Plotly publishes no Ruby library; rbplotly is that missing layer.
+- **Mistakes stop at the line that made them.** Figures are checked against the schema of the
+  bundled plotly.js release, so a typo raises an error with the attribute path and a
+  suggestion instead of producing a chart that silently ignores it.
+- **Nothing to sign up for.** Output is HTML: one self-contained file that works offline, a
+  fragment for a Rails view, or inline output in Jupyter. No account, API key or server.
+
+## Quick start
+
+```sh
+gem install rbplotly   # Ruby 3.3+; or add gem "rbplotly" to your Gemfile
 ```
 
-And then execute:
+```ruby
+require "rbplotly"
 
-    $ bundle
+weeks = (1..12).to_a
+plan = [12, 14, 13, 17, 16, 19, 21, 20, 23, 25, 24, 28]
+actual = [10, 15, 13, 18, 17, 18, 23, 22, 22, 27, 26, 31]
 
-Or install it yourself as:
+fig = Plotly::Figure.new
+  .add_bar(x: weeks, y: plan, name: "Plan", marker_color: "#c7d2fe")
+  .add_scatter(x: weeks, y: actual, name: "Actual", mode: :"lines+markers", line_width: 3)
+  .update_layout(title_text: "Weekly sales", xaxis_title_text: "Week",
+    yaxis_title_text: "Units", hovermode: "x unified")
 
-    $ gem install rbplotly
+fig.write_html("sales.html") # add open: true to open it in your browser
+```
 
-## Usage
+<img src="docs/images/quick-start.png" width="800" alt="The chart the code above draws: planned sales as light bars and actual sales as a line over twelve weeks">
+
+`sales.html` is a single file with plotly.js embedded: open it offline, attach it to an email,
+or publish it as is.
+
+## Mistakes stop where you made them
 
 ```ruby
-require 'rbplotly'
+fig.add_scatter(x: [1, 2], y: [3, 1], mode: :line)
+# => Plotly::ValidationError: data[2].mode: "line" is not a flag of mode. Did you mean "lines"?
+#    Join "lines", "markers", "text" with "+", or use "none"
+fig.update_layout(barmode: :stacked)
+# => Plotly::ValidationError: layout.barmode: "stacked" is not one of "stack", "group",
+#    "overlay", "relative". Did you mean "stack"?
+fig.add_bar(y: [1], marker_colour: "red")
+# => Plotly::ValidationError: data[2].marker.colour: marker has no attribute "colour".
+#    Did you mean "color"?
+fig.update_layout(title: "Sales")
+# => Plotly::ValidationError: layout.title: expected a Hash of title attributes, got "Sales".
+#    Plotly.js no longer accepts a plain string here:
+#    use title: {text: "Sales"} or title_text: "Sales"
+```
+
+Validation covers attribute names, enumerated values, flag lists, booleans and number ranges.
+It is stricter than plotly.js on purpose: values that plotly.js would quietly replace with a
+default are reported instead. Colors, data arrays and free-form values are passed through.
+Of the 1308 test figures in plotly.js itself, 1204 pass; the rest contain such ignored input. If you need an attribute from a
+newer plotly.js than the bundled one, turn validation off for that figure:
+`Plotly::Figure.new(validate: false)`.
 
-x = [0, 1, 2, 3, 4]
-trace0 = { x: x, y: [0, 2, 1, 4, 3], type: :scatter, mode: :lines }
-trace1 = { x: x, y: [4, 1, 3, 0, 2], type: :scatter, mode: :'markers+lines' }
-data = [trace0, trace1] # data must be an array
+## Gallery
 
-layout = { width: 500, height: 500 }
+<table>
+  <tr>
+    <td><a href="https://ash1day.github.io/rbplotly/#surface"><img src="docs/images/surface.png" width="400" alt="A 3D surface plot"></a></td>
+    <td><a href="https://ash1day.github.io/rbplotly/#sankey"><img src="docs/images/sankey.png" width="400" alt="A Sankey diagram of visitor flows"></a></td>
+  </tr>
+  <tr>
+    <td><a href="https://ash1day.github.io/rbplotly/#sunburst"><img src="docs/images/sunburst.png" width="400" alt="A sunburst chart of a budget split by group and team"></a></td>
+    <td><a href="https://ash1day.github.io/rbplotly/#distributions"><img src="docs/images/distributions.png" width="400" alt="Histograms and box plots of response times sharing an axis"></a></td>
+  </tr>
+</table>
 
-plot = Plotly::Plot.new(data: data, layout: layout)
+**[See every example running, next to its code →](https://ash1day.github.io/rbplotly/)**
 
-plot.layout.height = 300 # You can assign plot's attributes.
+## Building figures
 
-plot.generate_html(path: './line_chart.html')
+A figure has traces (`data`), a `layout` and a plotly.js `config`. Attribute names are those
+of the [plotly.js reference](https://plotly.com/javascript/reference/); rbplotly adds no names
+of its own.
+
+```ruby
+fig = Plotly::Figure.new(
+  data: [{type: :bar, x: %w[A B C], y: [3, 1, 2]}],
+  layout: {title: {text: "Votes"}, height: 400}
+)
+
+# One add_<type> helper per trace type: add_scatter, add_bar, add_heatmap, add_sankey, ...
+fig.add_scatter(x: %w[A B C], y: [2, 2, 2], mode: :lines, name: "Target")
+
+# Underscores reach into nested attributes:
+# marker_line_width: 2 is marker: {line: {width: 2}}
+fig.update_traces({marker_color: "teal", marker_line_width: 1}, selector: {type: :bar})
+fig.update_layout(yaxis_range: [0, 4], legend_orientation: "h")
 ```
 
-<img src="./docs/images/line_chart.png" width="400">
+Names that contain an underscore themselves (`error_x`, `paper_bgcolor`) keep working.
+Updates merge into what is already there.
 
-Use `#download_image` if you want to get an image by using Plot.ly API. You can get your API KEY [here](https://plot.ly/settings/api).
+### Subplots
 
 ```ruby
-Plotly.auth(<YOUR_USERNAME>, <YOUR_API_KEY>)
-plot.download_image(path: './line_chart.png')
+fig = Plotly.make_subplots(rows: 1, cols: 2, subplot_titles: ["Revenue", "Users"])
+fig.add_bar(x: %w[Q1 Q2 Q3], y: [10, 12, 15], row: 1, col: 1)
+fig.add_scatter(x: %w[Q1 Q2 Q3], y: [200, 260, 310], row: 1, col: 2)
+fig.update_yaxes({title_text: "USD (M)"}, row: 1, col: 1)
 ```
 
-Or use `#show` on IRuby notebooks.
+`shared_xaxes:` and `shared_yaxes:` link the axes of a column or row so they zoom together.
+Traces on x/y axes go on the cell's axes and domain traces (pie, sunburst, ...) fill the cell;
+3D, polar, ternary and map traces cannot be placed by `row:`/`col:` yet.
+
+Use positive relative `column_widths:` and `row_heights:` to size cells. Row heights are
+ordered from top to bottom; spacing is subtracted before distributing the remaining space.
+Enable a right y axis with `specs:`, then select it with `secondary_y: true`:
+
+```ruby
+fig = Plotly.make_subplots(cols: 2, column_widths: [2, 1],
+  specs: [[{secondary_y: true}, {}]])
+fig.add_bar(x: %w[Jan Feb Mar], y: [100, 150, 180], name: "Orders", row: 1, col: 1)
+fig.add_scatter(x: %w[Jan Feb Mar], y: [2, 3, 2.5], name: "Conversion %",
+  row: 1, col: 1, secondary_y: true)
+fig.update_yaxes(title_text: "Orders", row: 1, col: 1, secondary_y: false)
+fig.update_yaxes(title_text: "Conversion", ticksuffix: "%", secondary_y: true)
+```
+
+`specs` currently accepts only `secondary_y` in each cell hash. Existing primary axis
+numbers stay unchanged; secondary axes are numbered after all primary axes.
+`update_traces` and `update_yaxes` accept `secondary_y: true` (right), `false` (left),
+or the default `nil` (both). Axis sharing links only primary axes.
+
+### Animation
+
+Supply `frames:` to the constructor, append with `add_frame`, or replace with `frames=`.
+Define base traces before frames: omitted trace types are inferred from the corresponding
+base trace. A frame's `traces` array maps its data entries to zero-based trace indices.
 
 ```ruby
-plot.show
+fig = Plotly::Figure.new.add_scatter(x: [0, 1], y: [0, 1], mode: :"lines+markers")
+fig.update_layout(xaxis_range: [0, 1], yaxis_range: [0, 3])
+fig.add_frame(name: "first", data: [{y: [1, 2]}])
+fig.add_frame(name: "second", data: [{y: [2, 3]}])
+fig.write_html("animation.html", animation_opts: {frame: {duration: 700}, transition: {duration: 300}})
 ```
 
-## Examples
+HTML and notebook output register frames after drawing, then play them automatically.
+Pass `auto_play: false` to `to_html` or `write_html` to register frames without starting;
+use layout `updatemenus`/`sliders` or JavaScript to trigger playback. Nonempty frames are
+included in `to_h` and `to_json`. Without base data, an omitted trace type defaults to scatter.
 
-- [Basic Usage](https://nbviewer.jupyter.org/github/ash1day/rbplotly/blob/master/examples/Basic%20Usage.ipynb)
-- [Bar Charts](https://nbviewer.jupyter.org/github/ash1day/rbplotly/blob/master/examples/Bar%20%20Charts.ipynb)
-- [Scatter Plots](https://nbviewer.jupyter.org/github/ash1day/rbplotly/blob/master/examples/Scatter%20Plots.ipynb)
-- [Line Charts](https://nbviewer.jupyter.org/github/ash1day/rbplotly/blob/master/examples/Line%20charts.ipynb)
-- [Pie Charts](https://nbviewer.jupyter.org/github/ash1day/rbplotly/blob/master/examples/Pie%20Charts.ipynb)
-- [Histograms](https://nbviewer.jupyter.org/github/ash1day/rbplotly/blob/master/examples/Histograms.ipynb)
-- [Heatmaps](https://nbviewer.jupyter.org/github/ash1day/rbplotly/blob/master/examples/heatmaps.ipynb)
+## Output
 
-Visit [here](https://nbviewer.jupyter.org/github/ash1day/rbplotly/tree/master/examples/) to see more examples.
+| Method | Gives you |
+| --- | --- |
+| `fig.write_html(path)` | A standalone page with plotly.js embedded (works offline). `include_plotlyjs: :cdn` makes it ~5 MB smaller. |
+| `fig.to_html` | An HTML fragment (`<div>` + `<script>`) that loads the pinned plotly.js from the CDN. |
+| `fig.show` | The chart inline in a Jupyter notebook ([IRuby](https://github.com/SciRuby/iruby)), or in your browser otherwise. |
+| `fig.to_json` / `fig.to_h` | The figure as plotly.js reads it, for your own front end or `Plotly.newPlot`. |
 
-## Contributing
+`include_plotlyjs:` accepts `:cdn`, `:inline`, `false` (the page already loads plotly.js) or a
+URL. `to_html` also takes `div_id:`, `width:` and `height:` (Integers are pixels; the default
+is the layout height, or 450px). Charts resize with their container.
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+### In a Rails view
 
-## Thanks
+```erb
+<%# Load plotly.js once in your layout, before this (not deferred), then: %>
+<%= raw @figure.to_html(include_plotlyjs: false, height: 400) %>
+```
+
+All strings in the figure are escaped for use inside `<script>`, so user-provided labels such
+as `"</script>"` cannot break out of the page.
+
+### In Jupyter
+
+With [IRuby](https://github.com/SciRuby/iruby), the last expression of a cell is displayed,
+or call `fig.show`. plotly.js is loaded from the CDN once per notebook, without RequireJS
+(which JupyterLab does not have, and which kept 0.x charts from showing there). Checked with
+JupyterLab 4.6 and IRuby 0.8.
+
+## Data
+
+Any of these can be used where plotly.js expects an array or a value:
+
+- Arrays, Ranges (`x: 1..100`), Sets, Enumerators, and objects with `#to_a` such as
+  `Numo::NArray`, `Polars::Series` or `Daru::Vector`
+- `Date` and `Time` (written as `"2026-10-06 09:30:00"`; plotly.js has no time zones, so it
+  shows the wall-clock time you give it)
+- `Float::NAN` and infinities (written as `null`, which plotly.js draws as a gap)
+- `BigDecimal` and `Rational` (written as floats), Symbols (written as strings)
+
+Map traces that draw country outlines (`scattergeo`, `choropleth`) load them from Plotly's
+CDN. Since plotly.js 3.1 those outlines come from
+[UN Geodata](https://plotly.com/blog/improved-map-accuracy-plotlyjs-un-geodata/), which has
+its own terms of use (attribution to the UN; no commercial use); check them before you publish
+such a map.
+
+## plotly.js version
+
+rbplotly 1.0 targets **plotly.js 4.1.2** (`Plotly::PLOTLY_JS_VERSION`). The CDN URL, the
+embedded copy and the validation schema all come from that release, so what passes
+validation is what the browser draws. New plotly.js releases ship as new rbplotly versions.
+
+## Not included
+
+- **Static images (PNG/SVG/PDF).** Use the camera button in the chart's toolbar, or
+  `Plotly.toImage` in the browser. (The 0.x `download_image` used the plot.ly cloud API,
+  which no longer exists.)
+- **A high-level "plot this data frame" API.** For seaborn-style statistical charts, see
+  [charty](https://github.com/red-data-tools/charty). rbplotly stays a faithful, typed layer
+  over plotly.js.
+
+## Upgrading from 0.x
+
+1.0 is a rewrite. `Plotly::Plot.new(data:, layout:)` still works and prints a deprecation
+warning; `generate_html(path:)` is now `write_html(path)`. Attribute objects
+(`plot.layout.height = 300`) are replaced by `update_layout(height: 300)`, and
+`Plotly.auth` / `download_image` are removed. See [CHANGELOG.md](CHANGELOG.md).
+
+## Development
+
+```sh
+git clone https://github.com/ash1day/rbplotly.git && cd rbplotly
+bin/setup              # bundle install + download the pinned plotly.js
+bundle exec rake       # specs + Standard (lint)
+bundle exec rake spec:browser  # draws generated HTML in headless Chrome (needs Chrome)
+bundle exec rake gallery       # builds the gallery into site/
+```
 
-`rbplotly` is based on [plotly/plotly.py](https://github.com/plotly/plotly.py), so there are a lot of code coming from it.
+No API keys or accounts are needed to run anything. To move to a new plotly.js release, change
+`PLOTLY_JS_VERSION` in `lib/plotly/version.rb`, put the output of `rake plotlyjs:checksum` into
+`rakelib/plotlyjs.rake`, run `rake schema:generate`, and review the schema diff.
+More in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-Copyright (c) 2016 Yoshihiro Ashida. See [LICENSE.txt](LICENSE.txt) for
-further details.
+[MIT](LICENSE.txt). plotly.js, bundled in the gem, is © Plotly, Inc. and also MIT-licensed.