gnuplotrb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d42c4f1c4c5be11d3c393f511a24de68744aeac1
-  data.tar.gz: dc1035d41e16bfd1413f22bfe37194747f8e4966
+  metadata.gz: 636e6f8b249ca52a3dc09d4034cb7596ba650e42
+  data.tar.gz: d8eea39c386a7cc6513b2992b126fc15412318f4
 SHA512:
-  metadata.gz: 6d0d96f5abeec5638c9642cc08f73caf3cbdc00695b820a159d00a52cdba780c928072f65b0ee6d11e163aab52c2ace600c3d78b3be0017a51890636c3aaa100
-  data.tar.gz: 5cf75980f6ba0ddbb262f8062d7bb7c009ad970df5a4ed9988b4256d35badf3d2bb867d91f9bd21d32cf2c8cccd7ab0c03706fc92f6f6e766cd9d82dc12b660a
+  metadata.gz: 2d331f099e12185d350a4b1fe6908a658cfdcc977c3d4657bd621efe510fb854fe1a86fdd780b8f32e1ea69146934e513e8b1de16ead04e8a43c11da093d23eb
+  data.tar.gz: 26c483e4a645ac3b2ef9a680ba8a30cc3975fd68f0ad329e3cf22fae53a26cec5fd8b8743bd57850025c351bae77988dccf40d436c3f49b7a4c8c4344b222e4d

data/README.rdoc

@@ -1,34 +1,100 @@
 = GnuplotRB
 
-This is part of ruby gnuplot gem. It already can plot something (see examples and notebooks) but some features still waiting for implementation.
+GnuplotRB is a plot generator for Ruby based on {Gnuplot}[http://www.gnuplot.info].
+
+This software has been developed as a product in Google Summer of Code 2015 (GSoC2015). Its progress may be saw in {SciRuby mailing list}[https://groups.google.com/forum/?fromgroups#!topic/sciruby-dev/lhWvb5hWc3k] or in {project's blog}[http://dilcom.github.io/gnuplotrb/]. 
+
+{<img src="https://badge.fury.io/rb/gnuplotrb.svg" alt="Gem Version" />}[https://rubygems.org/gems/gnuplotrb]
 
 {<img src="https://travis-ci.org/dilcom/gnuplotrb.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/dilcom/gnuplotrb]
 {<img src="https://codeclimate.com/github/dilcom/gnuplotrb/badges/gpa.svg" alt="Code quality" />}[https://codeclimate.com/github/dilcom/gnuplotrb]
 {<img src="https://codeclimate.com/github/dilcom/gnuplotrb/badges/coverage.svg" alt="Test coverage" />}[https://codeclimate.com/github/dilcom/gnuplotrb]
 
+== Table of contents
+* {Installation}[https://github.com/dilcom/gnuplotrb#installation]
+* {Examples}[https://github.com/dilcom/gnuplotrb#examples]
+  * {Notebooks}[https://github.com/dilcom/gnuplotrb#notebooks]
+  * {Plain examples}[https://github.com/dilcom/gnuplotrb#plain-examples]
+* {Contributing}[https://github.com/dilcom/gnuplotrb#contributing]
 
 == Installation
-While gem isn't on rubygems, it may be installed from source.
 === Dependencies
 * Ruby 2.0+
 * It is required to install {gnuplot 5.0}[http://www.gnuplot.info/download.html] to use that gem.
 === Gem installation
-==== Install latest version from repository (may be unstable)
-  git clone https://github.com/dilcom/gnuplotrb.git
-  cd gnuplotrb
-  bundle install
-  rake install
-==== Install latest stable vrsion
+==== Install latest stable version from Rubygems
   gem install gnuplotrb
-==== Install latest stable vrsion using bundler
+==== Install latest stable version using bundler
 * add
     gem 'gnuplotrb'
   to your Gemfile
 * run
     bundle install
+==== Install latest version from source (may be unstable)
+  git clone https://github.com/dilcom/gnuplotrb.git
+  cd gnuplotrb
+  bundle install
+  rake install
+
+== Examples
+=== Notebooks
+
+This notebooks are powered by {Ruby kernel}[https://github.com/SciRuby/iruby/] for {IPython/Jupyter}[https://jupyter.org/].
+I placed them here to show some GnuplotRB's capabilities and ways of using it together with iRuby.
+
+To use GnuplotRB gem with iRuby you need to install them both.
+
+* iRuby installation is covered in its {README}[https://github.com/SciRuby/iruby/blob/master/README.md].
+  It also covers installation of iPython and other dependecies.
+* GnuplotRB gem installation covered in {README}[https://github.com/dilcom/gnuplotrb#installation] too.
+
+==== Embedding plots into iRuby
+Using GnuplotRB inside iRuby notebooks is covered in:
+
+* {Basic usage notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/basic_usage.ipynb].
+
+==== 2D and 3D plots
+GnuplotRB is capable to plot vast range of plots from histograms to 3D heatmaps. Gem's repository contains examples of several plot types:
+
+* {Heatmaps}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/heatmaps.ipynb]
+* {Vector field}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/vector_field.ipynb] (Thanks, {Alexej}[https://github.com/agisga])
+* {Math equations}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/math_plots.ipynb]
+* {3D visualizations}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/3d_plot.ipynb]
+* {Histogram}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/histogram.ipynb]
+
+==== Possible datasources
+GnuplotRB may take data in Ruby container or in a file. Supported containers for now are Arrays, Daru::Vector and Daru::DataFrame.
+When data given in file, GnuplotRB pass filename to Gnuplot *without* reading the file into memory.
+
+Examples of using different datasources:
+
+* {Data given in file or Ruby Array}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/points_from_different_sources.ipynb]
+* {Data given in Daru containers}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/plotting_from_daru.ipynb]
+* {Data given in Daru containers (with timeseries)}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/time_series_from_daru.ipynb]
+* {Updating plots with new data}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/updating_data.ipynb]
+
+==== Multiplot
+You can not only plot several datasets in single coordinate system but place several coordinate systems on a canvas.
+
+* {Multiplot example notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/multiplot_layout.ipynb].
+
+==== Animation
+It's possible to use several plots (Plot, Splot or Multiplot objects) to create gif animation.
+
+* {Animation example notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/animated_plots.ipynb].
+
+==== Fitting data with formula
+GnuplotRB also may be used to fit some data with given math formula.
+
+* {Fitting data}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/fitting_data.ipynb]
+
+=== Plain examples
+You may find several examples in {examples directory}[https://github.com/dilcom/gnuplotrb/tree/master/examples].
 
-== Plain examples
-You may find several examples in {examples directory}[https://github.com/dilcom/gnuplotrb/tree/master/examples]
+== Contributing
 
-== Notebooks with examples
-You may find several iRuby notebooks and readme for them in {notebooks directory}[https://github.com/dilcom/gnuplotrb/tree/master/notebooks]
+1. {Fork repository}[https://github.com/dilcom/gnuplotrb/fork]
+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 a new Pull Request

data/Rakefile

@@ -9,9 +9,9 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.rspec_opts = '--format documentation'
 end
 
-RDoc::Task.new do |rdoc|
+RDoc::Task.new(:doc) do |rdoc|
   rdoc.main = 'README.rdoc'
   rdoc.rdoc_files.include %w(README.rdoc lib)
 end
 
-RuboCop::RakeTask.new
+RuboCop::RakeTask.new(:cop)

data/lib/gnuplotrb/animation.rb

@@ -0,0 +1,102 @@
+module GnuplotRB
+  ##
+  # === Overview
+  # Animation allows to create gif animation with given plots
+  # as frames. Possible frames: Plot, Splot, Multiplot.
+  # More about its usage in {animation notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/animated_plots.ipynb].
+  class Animation < Multiplot
+    ##
+    # *Plot* here is also named as *frame*
+    alias_method :frames, :plots
+    alias_method :update_frame, :update_plot
+    alias_method :replace_frame, :replace_plot
+    alias_method :add_frame, :add_plot
+    alias_method :add_frames, :add_plots
+    alias_method :remove_frame, :remove_plot
+
+    ##
+    # ====== Overview
+    # This method creates a gif animation where frames are plots
+    # already contained by Animation object.
+    # ====== Arguments
+    # * *term* - Terminal to plot to
+    # * *options* - will be considered as 'settable' options of gnuplot
+    #   ('set xrange [1:10]', 'set title 'plot'' etc)
+    # Options passed here have priority over already existing.
+    # Inner options of Plots have the highest priority (except
+    # :term and :output which are ignored).
+    def plot(path = nil, **options)
+      options[:output] ||= path
+      plot_options = mix_options(options) do |plot_opts, anim_opts|
+        plot_opts.merge(term: ['gif', anim_opts])
+      end.to_h
+      need_output = plot_options[:output].nil?
+      plot_options[:output] = Dir::Tmpname.make_tmpname('anim', 0) if need_output
+      terminal = Terminal.new
+      multiplot(terminal, plot_options)
+      # guaranteed wait for plotting to finish
+      terminal.close
+      if need_output
+        result = File.binread(plot_options[:output])
+        File.delete(plot_options[:output])
+      else
+        result = nil
+      end
+      result
+    end
+
+    ##
+    # #to_<term_name> methods are not supported by animation
+    def to_specific_term(*_)
+      fail 'Specific terminals are not supported by Animation'
+    end
+
+    ##
+    # This method is used to embed gif animations
+    # into iRuby notebooks.
+    def to_iruby
+      gif_base64 = Base64.encode64(plot)
+      ['text/html', "<img src=\"data:image/gif;base64, #{gif_base64}\">"]
+    end
+
+    private
+
+    ##
+    # Dafault options to be used for that plot
+    def default_options
+      {
+        animate: {
+          delay: 10,
+          loop: 0,
+          optimize: true
+        }
+      }
+    end
+
+    ##
+    # This plot have some specific options which
+    # should be handled different way than others.
+    # Here are keys of this options.
+    def specific_keys
+      %w(
+        animate
+        size
+        background
+        transparent
+        enhanced
+        rounded
+        butt
+        linewidth
+        dashlength
+        tiny
+        small
+        medium
+        large
+        giant
+        font
+        fontscale
+        crop
+      )
+    end
+  end
+end

data/lib/gnuplotrb/external_classes/array.rb

@@ -1,3 +1,5 @@
+##
+# Methods to take data for GnuplotRB plots.
 class Array
   # taken for example from current gnuplot bindings
   def to_gnuplot_points

data/lib/gnuplotrb/external_classes/daru.rb

@@ -1,10 +1,16 @@
 if defined? Daru
+  ##
+  # See {daru}[https://github.com/v0dro/daru] and
+  # {plotting from daru}[https://github.com/dilcom/gnuplotrb/blob/master/notebooks/plotting_from_daru.ipynb]
   module Daru
+    ##
+    # Methods to take data for GnuplotRB plots.
     class DataFrame
       def to_gnuplot_points
         result = ''
-        self.each_row_with_index do |row, index|
-          result += "#{index.to_s} "
+        each_row_with_index do |row, index|
+          quoted = index.is_a?(String) || index.is_a?(Symbol)
+          result += quoted ? "\"#{index}\" " : "#{index} "
           result += row.to_a.join(' ')
           result += "\n"
         end
@@ -12,14 +18,18 @@ if defined? Daru
       end
     end
 
+    ##
+    # Methods to take data for GnuplotRB plots.
     class Vector
       def to_gnuplot_points
         result = ''
-        self.each_with_index do |value, index|
-          result += "#{index} #{value}\n"
+        each_with_index do |value, index|
+          quoted = index.is_a?(String) || index.is_a?(Symbol)
+          result += quoted ? "\"#{index}\" " : "#{index} "
+          result += "#{value}\n"
         end
         result
       end
     end
   end
-end
+end

data/lib/gnuplotrb/external_classes/string.rb

@@ -1,3 +1,5 @@
+##
+# Methods to take data for GnuplotRB plots.
 class String
   def to_gnuplot_points
     clone

data/lib/gnuplotrb/fit.rb

@@ -0,0 +1,176 @@
+module GnuplotRB
+  ##
+  # ====== Overview
+  # Fit given data with function. Covered in {fit notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/fitting_data.ipynb].
+  # ====== Arguments
+  # * *data* - method accepts the same sources as Dataset.new
+  #   and Dataset object
+  # * *:function* - function to fit data with. Default 'a2*x*x+a1*x+a0'
+  # * *:initials* - initial values for coefficients used in fitting.
+  #   Default: {a2: 1, a1: 1, a0: 1}
+  # * *:via* - coefficients that Gnuplot should change during fitting.
+  #   Default: initials#keys
+  # * *:term_options* - terminal options that should be setted to terminal before fit.
+  #   For example *xrange*, *yrange* etc
+  # * *options* - options passed to Gnuplot's fit such as *using*
+  # ====== Return value
+  # Fit returns hash of 4 elements:
+  # * *:formula_ds* - dataset with best fit curve as data
+  # * *:coefficients* - hash of calculated coefficients. So if you gave {via: [:a, :b, :c]} or
+  #   {initials: {a: 1, b: 1, c: 1} } it will return hash with keys :a, :b, :c and its values
+  # * *:deltas* - Gnuplot calculates possible deltas for coefficients during fitting and
+  #   *deltas* hash contains this deltas
+  # * *:data* - pointer to Datablock with given data
+  # ====== Examples
+  #   fit(some_data, function: 'exp(a/x)', initials: {a: 10}, term_option: { xrange: 1..100 })
+  #   fit(some_dataset, using: '1:2:3')
+  def fit(data, function: 'a2*x*x+a1*x+a0', initials: { a2: 1, a1: 1, a0: 1 }, term_options: {}, **options)
+    dataset = data.is_a?(Dataset) ? Dataset.new(data.data) : Dataset.new(data)
+    opts_str = OptionHandling.ruby_class_to_gnuplot(options)
+    output = gnuplot_fit(function, dataset, opts_str, initials, term_options)
+    res = parse_output(initials.keys, function, output)
+    {
+      formula_ds: Dataset.new(res[2], title: 'Fit formula'),
+      coefficients: res[0],
+      deltas: res[1],
+      data: dataset
+    }
+  end
+
+  ##
+  # ====== Overview
+  # Shortcut for fit with polynomial. Degree here is max power of *x* in polynomial.
+  # ====== Arguments
+  # * *data* - method accepts the same sources as Dataset.new and Dataset object
+  # * *:degree* - degree of polynomial
+  # * *options* - all of this options will be passed to *#fit* so you
+  #   can set here any *term_options*. If you pass here *:initials* hash, it
+  #   will be merged into default initals hash (all values are 1).
+  # ====== Return value
+  # See the same section for #fit.
+  # ====== Examples
+  #   fit_poly(some_data, degree: 5, initials: { a4: 10, a2: -1 }, term_option: { xrange: 1..100 })
+  #   #=> The same as:
+  #   #=> fit(
+  #   #=>   some_data,
+  #   #=>   function: 'a5*x**5 + a4*x**4 + ... + a0*x**0',
+  #   #=>   initals: {a5: 1, a4: 10, a3: 1, a2: -1, a1: 1, a0: 1},
+  #   #=>   term_option: { xrange: 1..100 }
+  #   #=> )
+  def fit_poly(data, degree: 2, **options)
+    sum_count = degree + 1
+    initials = {}
+    sum_count.times { |i| initials["a#{i}".to_sym] = 1 }
+    options[:initials] = initials.merge(options[:initials] || {})
+    function = sum_count.times.map { |i| "a#{i}*x**#{i}" }.join(' + ')
+    fit(data, **options, function: function)
+  end
+
+  ##
+  # :method: fit_<function>
+  # :call-seq:
+  # fit_exp(data, **options) -> Hash
+  # fit_log(data, **options) -> Hash
+  # fit_sin(data, **options) -> Hash
+  #
+  # ====== Overview
+  # Shortcuts for fitting with several math functions (exp, log, sin).
+  # ====== Arguments
+  # * *data* - method accepts the same sources as Dataset.new and Dataset object
+  # * *options* - all of this options will be passed to *#fit* so you
+  #   can set here any *term_options*. If you pass here *:initials* hash, it
+  #   will be merged into default initals hash { yoffset: 0.1, xoffset: 0.1, yscale: 1, xscale: 1 }
+  # ====== Return value
+  # See the same section for #fit.
+  # ====== Examples
+  #   fit_exp(some_data, initials: { yoffset: -11 }, term_option: { xrange: 1..100 })
+  #   #=> The same as:
+  #   #=> fit(
+  #   #=>   some_data,
+  #   #=>   function: 'yscale * (yoffset + exp((x - xoffset) / xscale))',
+  #   #=>   initals: { yoffset: -11, xoffset: 0.1, yscale: 1, xscale: 1 },
+  #   #=>   term_option: { xrange: 1..100 }
+  #   #=> )
+  #   fit_log(...)
+  #   fit_sin(...)
+  %w(exp log sin).map do |fname|
+    define_method("fit_#{fname}".to_sym) do |data, **options|
+      options[:initials] = {
+        yoffset: 0.1,
+        xoffset: 0.1,
+        yscale: 1,
+        xscale: 1
+      }.merge(options[:initials] || {})
+      function = "yscale * (yoffset + #{fname} ((x - xoffset) / xscale))"
+      fit(data, **options, function: function)
+    end
+  end
+
+  private
+
+  ##
+  # It takes some time to produce output so here we need
+  # to wait for it.
+  def wait_for_output(term, variables)
+    # now we should catch 'error' from terminal: it will contain approximation data
+    # but we can get a real error instead of output, so lets wait for limited time
+    start = Time.now
+    output = ''
+    until output_ready?(output, variables)
+      begin
+        term.check_errors
+      rescue GnuplotRB::GnuplotError => e
+        output += e.message
+      end
+      if Time.now - start > Settings.max_fit_delay
+        fail GnuplotError, "Seems like there is an error in gnuplotrb: #{output}"
+      end
+    end
+    output
+  end
+
+  ##
+  # Check if current output contains all the
+  # variables given to fit.
+  def output_ready?(output, variables)
+    output =~ /Final set .*#{variables.join('.*')}/
+  end
+
+  ##
+  # Parse Gnuplot's output to get coefficients and their deltas
+  # from it. Also replaces coefficients in given function with
+  # exact values.
+  def parse_output(variables, function, output)
+    plottable_function = " #{function.clone} "
+    coefficients = {}
+    deltas = {}
+    variables.each do |var|
+      value, error = output.scan(%r{#{var} *= ([^ ]+) *\+/\- ([^ ]+)})[0]
+      plottable_function.gsub!(/#{var}([^0-9a-zA-Z])/) { value + Regexp.last_match(1) }
+      coefficients[var] = value.to_f
+      deltas[var] = error.to_f
+    end
+    [coefficients, deltas, plottable_function]
+  end
+
+  ##
+  # Make fit command and send it to gnuplot
+  def gnuplot_fit(function, data, options, initials, term_options)
+    variables = initials.keys
+    term = Terminal.new
+    term.set(term_options)
+    initials.each { |var_name, value| term.stream_puts "#{var_name} = #{value}" }
+    command = "fit #{function} #{data.to_s(term)} #{options} via #{variables.join(',')}"
+    term.stream_puts(command)
+    output = wait_for_output(term, variables)
+    begin
+      term.close
+    rescue GnuplotError
+      # Nothing interesting here.
+      # If we had an error, we never reach this line.
+      # Error here may be only additional information
+      # such as correlation matrix.
+    end
+    output
+  end
+end

data/lib/gnuplotrb/mixins/error_handling.rb

@@ -13,30 +13,34 @@ module GnuplotRB
     # Check if there were errors in previous commands.
     # Throws GnuplotError in case of any errors.
     def check_errors
-      unless @err_array.empty?
+      return if @err_array.empty?
+      command = ''
+      rest = ''
+      @semaphore.synchronize do
         command = @err_array.first
         rest = @err_array[1..-1].join('; ')
-        message = "Error in previous command (\"#{command}\"): \"#{rest}\""
         @err_array.clear
-        fail GnuplotError, message
       end
+      message = "Error in previous command (\"#{command}\"): \"#{rest}\""
+      fail GnuplotError, message
     end
 
+    private
+
     ##
     # ====== Overview
     # Start new thread that will read stderr given as stream
     # and add errors into @err_array.
     def handle_stderr(stream)
       @err_array = []
+      # synchronize access to @err_array
+      @semaphore = Mutex.new
       Thread.new do
-        until (line = stream.gets).nil? do
+        until (line = stream.gets).nil?
           line.strip!
-          @err_array << line if line.size > 3
+          @semaphore.synchronize { @err_array << line if line.size > 3 }
         end
       end
     end
-
-    private :check_errors,
-            :handle_stderr
   end
 end

data/lib/gnuplotrb/mixins/option_handling.rb

@@ -20,10 +20,19 @@ module GnuplotRB
         zlabel
         rgb
         font
+        background
+        format
+        format_x
+        format_y
+        format_xy
+        format_x2
+        format_y2
+        format_z
+        format_cb
+        timefmt
       )
 
       ##
-      # For inner use!
       # Replacement '_' with ' ' is made to allow passing several options
       # with the same first word of key.
       # See issue #7 for more info.
@@ -89,26 +98,25 @@ module GnuplotRB
       # Now checks only terminal name.
       def validate_terminal_options(options)
         terminal = options[:term]
-        if terminal
-          terminal = terminal[0] if terminal.is_a?(Array)
-          message = 'Seems like your Gnuplot does not ' \
-                    'support that terminal, please see supported ' \
-                    'terminals with Settings::available_terminals'
-          fail(ArgumentError, message) unless valid_terminal?(terminal)
-        end
+        return unless terminal
+        terminal = terminal[0] if terminal.is_a?(Array)
+        message = 'Seems like your Gnuplot does not ' \
+                  'support that terminal, please see supported ' \
+                  'terminals with Settings::available_terminals'
+        fail(ArgumentError, message) unless valid_terminal?(terminal)
       end
     end
 
     ##
     # You should implement #initialize in classes that use OptionsHelper
-    def initialize(*args)
+    def initialize(*_)
       fail NotImplementedError, 'You should implement #initialize' \
                                 ' in classes that use OptionsHelper!'
     end
 
     ##
     # You should implement #new_with_options in classes that use OptionsHelper
-    def new_with_options(*args)
+    def new_with_options(*_)
       fail NotImplementedError, 'You should implement #new_with_options' \
                                 ' in classes that use OptionsHelper!'
     end
@@ -137,8 +145,9 @@ module GnuplotRB
       end
     end
 
+    private
+
     ##
-    # Method for inner use.
     # ====== Arguments
     # * *key* - [Symbol] - option key
     # * *value* - anything treated as options value in gnuplot gem
@@ -151,7 +160,5 @@ module GnuplotRB
         options(key => value)
       end
     end
-
-    private :option
   end
 end