rbplotly 0.1.1 → 1.0.0

data/lib/plotly/schema.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Plotly
+  # The attribute tree of the bundled plotly.js release, generated by `rake schema:generate`.
+  class Schema
+    # The generated schema file.
+    PATH = File.expand_path("schema/plot-schema.json", __dir__)
+    # Numbered subplot ids: xaxis2, scene3 (plotly.js has no xaxis1).
+    SUBPLOT_SUFFIX = /\A(?<base>[a-z]+?)(?<n>[2-9]|[1-9]\d+)\z/
+
+    # One attribute: an object with children, an array of objects, or a leaf value.
+    class Node
+      attr_reader :name
+
+      def initialize(name, spec)
+        @name = name
+        @spec = spec
+      end
+
+      def object? = @spec.key?("attrs")
+
+      def array? = @spec.key?("array")
+
+      def leaf? = @spec.key?("type")
+
+      def subplot? = @spec["subplot"] == true
+
+      # @return [Array<String>] names of the children of an object
+      def attribute_names = @spec.fetch("attrs", {}).keys
+
+      # @return [Node, nil] the child attribute, or nil when plotly.js does not define it
+      def child(key)
+        attrs = @spec["attrs"] or return nil
+        key = key.to_s
+        return Node.new(key, attrs[key]) if attrs.key?(key)
+
+        match = SUBPLOT_SUFFIX.match(key) or return nil
+        base = attrs[match[:base]]
+        Node.new(key, base) if base&.fetch("subplot", false)
+      end
+
+      # @return [Node] the schema of each element of an array of objects
+      def item = Node.new(name.sub(/s\z/, ""), @spec.fetch("array"))
+
+      # @return [String, nil] plotly.js value type of a leaf: "number", "enumerated", "color", ...
+      def type = @spec["type"]
+
+      # @return [Array] allowed values of an enumerated leaf; "/.../" strings are patterns
+      def values = @spec.fetch("values", [])
+
+      # @return [Array<String>] flags of a flaglist leaf, joined with "+"
+      def flags = @spec.fetch("flags", [])
+
+      # @return [Array<String>] flaglist values that stand alone, such as "none"
+      def extras = @spec.fetch("extras", [])
+
+      # Whether the leaf also accepts an array of values, one per point.
+      def array_ok? = @spec["array_ok"] == true
+
+      # @return [Numeric, nil] lower bound of a number leaf
+      def min = @spec["min"]
+
+      # @return [Numeric, nil] upper bound of a number leaf
+      def max = @spec["max"]
+    end
+
+    # @return [Schema] the schema of the bundled plotly.js release, loaded once
+    def self.default
+      @default ||= new(JSON.parse(File.read(PATH)))
+    end
+
+    def initialize(raw)
+      @raw = raw
+    end
+
+    # @return [String] the plotly.js release the schema was generated from
+    def plotly_js_version = @raw.fetch("plotly_js")
+
+    # @return [Array<String>] every trace type: "bar", "scatter", ...
+    def trace_types = @raw.fetch("traces").keys
+
+    # @return [Node, nil]
+    def trace(type)
+      spec = @raw.fetch("traces")[type.to_s]
+      Node.new(type.to_s, spec) if spec
+    end
+
+    # @return [Node] layout attributes, including those trace types add (barmode, ...)
+    def layout = Node.new("layout", @raw.fetch("layout"))
+
+    # @return [Node] plotly.js config options
+    def config = Node.new("config", @raw.fetch("config"))
+  end
+end

data/lib/plotly/serializer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+
+module Plotly
+  # Writes figures as the JSON that plotly.js reads.
+  module Serializer
+    module_function
+
+    # Characters escaped in JSON so it can be embedded in HTML.
+    HTML_UNSAFE = {"<" => "\\u003c", ">" => "\\u003e", "&" => "\\u0026"}.freeze
+
+    # @return [String] JSON that is safe to place inside an HTML <script> element: `<`, `>`
+    #   and `&` (which only occur inside strings) and U+2028/2029 are written as escapes
+    def dump(value)
+      JSON.generate(plain(value), script_safe: true).gsub(/[<>&]/, HTML_UNSAFE)
+    end
+
+    # Converts a value into Hashes, Arrays, Strings, numbers, booleans and nils.
+    def plain(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, plain(v)] }
+      when Array then value.map { |v| plain(v) }
+      when String, Integer, true, false, nil then value
+      when Symbol then value.to_s
+      when Float then value.finite? ? value : nil
+      when Complex then unsupported!(value)
+      when Numeric then plain(value.to_f)
+      when Time, DateTime then timestamp(value)
+      when Date then value.strftime("%Y-%m-%d")
+      when Struct then unsupported!(value) # a record, even though Struct#to_a exists
+      else
+        # Ranges, Sets, Enumerators and data frame columns (Numo::NArray, Polars::Series, ...)
+        value.respond_to?(:to_a) ? plain(value.to_a) : unsupported!(value)
+      end
+    end
+
+    # plotly.js has no time zones: a date string is drawn as the wall-clock time it names.
+    def timestamp(time)
+      fraction = time.strftime("%N").sub(/0+\z/, "")
+      time.strftime("%Y-%m-%d %H:%M:%S") + (fraction.empty? ? "" : ".#{fraction}")
+    end
+
+    def unsupported!(value)
+      raise TypeError, "#{value.inspect} (#{value.class}) cannot be written as plotly.js JSON"
+    end
+  end
+end

data/lib/plotly/subplots.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Plotly
+  # Builds a figure with a grid of subplots, each with its own x and y axis.
+  #
+  # Cells are numbered from the top-left, row by row; traces are placed with
+  # `add_trace(..., row:, col:)`. Spacing defaults follow plotly.py.
+  #
+  # @example
+  #   fig = Plotly.make_subplots(rows: 1, cols: 2, subplot_titles: ["Revenue", "Users"])
+  #   fig.add_bar(x: months, y: revenue, row: 1, col: 1)
+  #   fig.add_scatter(x: months, y: users, row: 1, col: 2)
+  #
+  # @param rows [Integer]
+  # @param cols [Integer]
+  # @param shared_xaxes [Boolean] link the x axes of each column and label only the bottom one
+  # @param shared_yaxes [Boolean] link the y axes of each row and label only the left one
+  # @param subplot_titles [Array<String>, nil] one title per cell, in row-major order
+  # @param horizontal_spacing [Float] gap between columns, as a fraction of the figure width
+  # @param vertical_spacing [Float] gap between rows, as a fraction of the figure height
+  # @param figure_options [Hash] passed to {Figure#initialize} (`layout:`, `config:`, `validate:`)
+  # @return [Figure]
+  def self.make_subplots(rows: 1, cols: 1, shared_xaxes: false, shared_yaxes: false, subplot_titles: nil,
+    horizontal_spacing: 0.2 / cols, vertical_spacing: 0.3 / rows, **figure_options)
+    grid = Subplots::Grid.new(rows, cols, horizontal_spacing, vertical_spacing)
+    titles = Array(subplot_titles)
+    if titles.size > grid.cells.size
+      raise ArgumentError, "#{titles.size} subplot titles for #{grid.cells.size} cells"
+    end
+
+    figure = Figure.new(**figure_options)
+    figure.subplot_grid = grid
+    figure.update_layout(grid.axes_layout(shared_xaxes, shared_yaxes))
+    annotations = grid.title_annotations(titles)
+    figure.update_layout(annotations: (figure.layout["annotations"] || []) + annotations) if annotations.any?
+    figure
+  end
+
+  # Grid layout behind {Plotly.make_subplots}.
+  # @api private
+  module Subplots
+    Cell = Struct.new(:row, :col, :index, :x_domain, :y_domain) do
+      def suffix = (index == 1) ? "" : index.to_s
+
+      def axis_ids = ["x#{suffix}", "y#{suffix}"]
+
+      def layout_key(letter) = "#{letter}axis#{suffix}"
+    end
+
+    class Grid
+      attr_reader :rows, :cols
+
+      def initialize(rows, cols, horizontal_spacing, vertical_spacing)
+        unless rows.is_a?(Integer) && cols.is_a?(Integer) && rows.positive? && cols.positive?
+          raise ArgumentError, "rows and cols must be positive integers"
+        end
+
+        @rows = rows
+        @cols = cols
+        width = (1.0 - horizontal_spacing * (cols - 1)) / cols
+        height = (1.0 - vertical_spacing * (rows - 1)) / rows
+        raise ArgumentError, "spacing leaves no room for the subplots" unless width.positive? && height.positive?
+
+        @cells = (1..rows).flat_map do |row|
+          (1..cols).map do |col|
+            x0 = (col - 1) * (width + horizontal_spacing)
+            y1 = 1.0 - (row - 1) * (height + vertical_spacing)
+            Cell.new(row, col, (row - 1) * cols + col, domain(x0, x0 + width), domain(y1 - height, y1))
+          end
+        end
+      end
+
+      # @return [Array<Cell>] every cell, or the cells in the given row and/or column
+      def cells(row = nil, col = nil)
+        @cells.select { |c| (row.nil? || c.row == row) && (col.nil? || c.col == col) }
+      end
+
+      def cell(row, col)
+        found = cells(row, col)
+        return found.first if row && col && found.size == 1
+
+        raise ArgumentError, "row #{row.inspect}, col #{col.inspect} is outside the #{rows}x#{cols} subplot grid"
+      end
+
+      def axes_layout(shared_x, shared_y)
+        @cells.each_with_object({}) do |cell, layout|
+          x_id, y_id = cell.axis_ids
+          layout[cell.layout_key("x")] = {"domain" => cell.x_domain, "anchor" => y_id}.merge(
+            (shared_x && cell.row != rows) ? linked(cell(rows, cell.col).axis_ids[0]) : {}
+          )
+          layout[cell.layout_key("y")] = {"domain" => cell.y_domain, "anchor" => x_id}.merge(
+            (shared_y && cell.col != 1) ? linked(cell(cell.row, 1).axis_ids[1]) : {}
+          )
+        end
+      end
+
+      def title_annotations(titles)
+        titles.each_with_index.filter_map do |title, i|
+          next if title.nil? || title.to_s.empty?
+
+          cell = @cells[i]
+          {
+            "text" => title, "showarrow" => false, "font" => {"size" => 16},
+            "xref" => "paper", "yref" => "paper", "xanchor" => "center", "yanchor" => "bottom",
+            "x" => ((cell.x_domain[0] + cell.x_domain[1]) / 2).round(12), "y" => cell.y_domain[1]
+          }
+        end
+      end
+
+      private
+
+      # Follows another axis' range and leaves the tick labels to it.
+      def linked(axis_id) = {"matches" => axis_id, "showticklabels" => false}
+
+      def domain(from, to) = [from.round(12).clamp(0.0, 1.0), to.round(12).clamp(0.0, 1.0)]
+    end
+  end
+end

data/lib/plotly/version.rb

@@ -1,3 +1,9 @@
+# frozen_string_literal: true
+
 module Plotly
-  VERSION = '0.1.1'.freeze
+  # The gem version.
+  VERSION = "1.0.0"
+
+  # The plotly.js release this gem's schema, CDN URL and bundled script are built from.
+  PLOTLY_JS_VERSION = "4.1.2"
 end

data/lib/plotly.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "plotly/version"
+
+# Interactive Plotly.js charts from Ruby.
+module Plotly
+  # Raised when a figure uses an attribute or value that the bundled plotly.js schema rejects.
+  class ValidationError < ArgumentError; end
+
+  # Base class for other rbplotly errors.
+  class Error < StandardError; end
+end
+
+require_relative "plotly/schema"
+require_relative "plotly/attributes"
+require_relative "plotly/serializer"
+require_relative "plotly/html"
+require_relative "plotly/figure"
+require_relative "plotly/subplots"
+require_relative "plotly/plot"

data/lib/rbplotly.rb

@@ -1,4 +1,3 @@
-require 'plotly/version'
-require 'plotly/client'
-require 'plotly/util'
-require 'plotly/plot'
+# frozen_string_literal: true
+
+require_relative "plotly"

metadata

@@ -1,189 +1,63 @@
 --- !ruby/object:Gem::Specification
 name: rbplotly
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
-- y4ashida
-autorequire: 
-bindir: exe
+- Yoshihiro Ashida
+bindir: bin
 cert_chain: []
-date: 2016-08-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: faraday
+  name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '2.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
-- !ruby/object:Gem::Dependency
-  name: uuidtools
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-- !ruby/object:Gem::Dependency
-  name: launchy
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.4'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.12'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.12'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.5'
-- !ruby/object:Gem::Dependency
-  name: guard-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.7'
-- !ruby/object:Gem::Dependency
-  name: guard-rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-description: 
+        version: '2.7'
+description: Build Plotly.js figures with plain Ruby hashes, check every attribute
+  against the plot schema of the bundled plotly.js release, and write self-contained
+  HTML that works offline, in Rails views and in Jupyter (IRuby). No account or API
+  key needed.
 email:
 - y4ashida@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".travis.yml"
-- CODE_OF_CONDUCT.md
-- Gemfile
-- Guardfile
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
-- docs/images/line_chart.png
-- examples/basic_bar_chart.ipynb
-- examples/basic_histogram.ipynb
-- examples/basic_pie_chart.ipynb
-- examples/grouped_bar_chart.ipynb
-- examples/heatmaps.ipynb
-- examples/line_and_scatter_plots.ipynb
-- examples/stacked_bar_chart.ipynb
-- lib/plotly/axis.rb
-- lib/plotly/castable.rb
-- lib/plotly/client.rb
-- lib/plotly/data.rb
-- lib/plotly/exportable.rb
-- lib/plotly/layout.rb
-- lib/plotly/offline/exportable.rb
-- lib/plotly/offline/html.rb
-- lib/plotly/offline/plotly.min.js
-- lib/plotly/offline/templates/body.erb
-- lib/plotly/offline/templates/plot.erb
+- lib/plotly.rb
+- lib/plotly/assets/plotly.min.js
+- lib/plotly/attributes.rb
+- lib/plotly/figure.rb
+- lib/plotly/html.rb
 - lib/plotly/plot.rb
-- lib/plotly/util.rb
+- lib/plotly/schema.rb
+- lib/plotly/schema/plot-schema.json
+- lib/plotly/serializer.rb
+- lib/plotly/subplots.rb
 - lib/plotly/version.rb
 - lib/rbplotly.rb
-- rbplotly.gemspec
-homepage: https://github.com/y4ashida/rbplotly
+homepage: https://github.com/ash1day/rbplotly
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/ash1day/rbplotly
+  source_code_uri: https://github.com/ash1day/rbplotly
+  changelog_uri: https://github.com/ash1day/rbplotly/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ash1day/rbplotly/issues
+  documentation_uri: https://rubydoc.info/gems/rbplotly
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -191,16 +65,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
-signing_key: 
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Plot.ly API client and Interface to plotly.js.
+summary: Interactive Plotly.js charts from Ruby, validated against the plotly.js schema
 test_files: []

data/.gitignore

@@ -1,11 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-.ipynb_checkpoints

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---color

data/.rubocop.yml

@@ -1,22 +0,0 @@
-AllCops:
-  TargetRubyVersion: 2.3
-
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-LineLength:
-  Max: 100
-
-MethodLength:
-  Max: 15
-
-Documentation:
-  Enabled: false
-
-ParameterLists:
-  CountKeywordArgs: false
-
-RegexpLiteral:
-  Exclude:
-    - '**/*.gemspec'
-    - '**/Guardfile'

data/.travis.yml

@@ -1,6 +0,0 @@
-language: ruby
-rvm:
-- 2.3.1
-script: bundle exec rake ci
-sudo: false
-cache: bundler

data/CODE_OF_CONDUCT.md

@@ -1,49 +0,0 @@
-# Contributor Code of Conduct
-
-As contributors and maintainers of this project, and in the interest of
-fostering an open and welcoming community, we pledge to respect all people who
-contribute through reporting issues, posting feature requests, updating
-documentation, submitting pull requests or patches, and other activities.
-
-We are committed to making participation in this project a harassment-free
-experience for everyone, regardless of level of experience, gender, gender
-identity and expression, sexual orientation, disability, personal appearance,
-body size, race, ethnicity, age, religion, or nationality.
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery
-* Personal attacks
-* Trolling or insulting/derogatory comments
-* Public or private harassment
-* Publishing other's private information, such as physical or electronic
-  addresses, without explicit permission
-* Other unethical or unprofessional conduct
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-By adopting this Code of Conduct, project maintainers commit themselves to
-fairly and consistently applying these principles to every aspect of managing
-this project. Project maintainers who do not follow or enforce the Code of
-Conduct may be permanently removed from the project team.
-
-This code of conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community.
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting a project maintainer at y4ashida@gmail.com. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. Maintainers are
-obligated to maintain confidentiality with regard to the reporter of an
-incident.
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 1.3.0, available at
-[http://contributor-covenant.org/version/1/3/0/][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -1,4 +0,0 @@
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in rbplotly.gemspec
-gemspec

data/Guardfile

@@ -1,12 +0,0 @@
-guard :rspec, all_after_pass: true, all_on_start: true, cmd: 'bundle exec rspec' do
-  watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})        { |m| "spec/#{m[1]}_spec.rb" }
-  watch(%r{^lib/(.+?)/.+\.rb$})    { |m| "spec/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')     { 'spec' }
-  watch(%r{^spec/support/.+\.rb$}) { 'spec' }
-end
-
-guard :rubocop do
-  watch(%r{.+\.rb$})
-  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
-end

data/Rakefile

@@ -1,9 +0,0 @@
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-RuboCop::RakeTask.new(:style)
-
-task default: :spec
-task ci: [:spec, :style]