gnuplotrb 0.2.0 → 0.3.0

data/lib/gnuplotrb/mixins/plottable.rb

@@ -6,44 +6,12 @@ module GnuplotRB
   module Plottable
     include OptionHandling
 
-    ##
-    # Terminal object used by this Plottable to pipe data to gnuplot.
-    attr_reader :terminal
-
     ##
     # You should implement #plot in classes that are Plottable
-    def plot(*args)
+    def plot(*_)
       fail NotImplementedError, 'You should implement #plot in classes that are Plottable!'
     end
 
-    ##
-    # Method for inner use.
-    # ====== Overview
-    # Method which outputs plot to specific terminal (possibly some file).
-    # Explicit use should be avoided. This method is called from #method_missing
-    # when it handles method names like #to_png(options).
-    # ====== Arguments
-    # * *terminal* - string corresponding to terminal type (png, html, jpeg etc)
-    # * *path* - path to output file, if none given it will output to temp file
-    #   and then read it and return binary contents of file
-    # * *options* - used in 'set term <term type> <options here>'
-    # ====== Examples
-    #   ## plot here may be Plot, Splot, Multiplot or any other plottable class
-    #   plot.to_png('./result.png', size: [300, 500])
-    #   contents = plot.to_svg(size: [100, 100])
-    #   plot.to_dumb('./result.txt', size: [30, 15])
-    def to_specific_term(terminal, path = nil, **options)
-      if path
-        result = plot(term: [terminal, options], output: path)
-      else
-        path = Dir::Tmpname.make_tmpname(terminal, 0)
-        plot(term: [terminal, options], output: path)
-        result = File.binread(path)
-        File.delete(path)
-      end
-      result
-    end
-
     ##
     # ====== Overview
     # In this gem #method_missing is used both to handle
@@ -98,5 +66,60 @@ module GnuplotRB
       term = meth[0..2] == 'to_' && OptionHandling.valid_terminal?(meth[3..-1])
       term || super
     end
+
+    ##
+    # This method is used to embed plottable objects
+    # into iRuby notebooks. There is
+    # {a notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/basic_usage.ipynb]
+    # with examples of its usage.
+    def to_iruby
+      available_terminals = {
+        'png'      => 'image/png',
+        'pngcairo' => 'image/png',
+        'jpeg'     => 'image/jpeg',
+        'svg'      => 'image/svg+xml',
+        'dumb'     => 'text/plain'
+      }
+      terminal, options = term.is_a?(Array) ? [term[0], term[1]] : [term, {}]
+      terminal = 'svg' unless available_terminals.keys.include?(terminal)
+      [available_terminals[terminal], send("to_#{terminal}".to_sym, **options)]
+    end
+
+    ##
+    # :call-seq:
+    # to_png('file.png') -> creates file with plot
+    # to_svg -> svg file contents
+    # to_canvas('plot.html', size: [300,300]) -> creates file with plot
+    #
+    # ====== Overview
+    # Method which outputs plot to specific terminal (possibly some file).
+    # Explicit use should be avoided. This method is called from #method_missing
+    # when it handles method names like #to_png(options).
+    # ====== Arguments
+    # * *path* - path to output file, if none given it will output to temp file
+    #   and then read it and return binary contents of file
+    # * *options* - used in #plot
+    # ====== Examples
+    #   ## plot here may be Plot, Splot, Multiplot or any other plottable class
+    #   plot.to_png('./result.png', size: [300, 500])
+    #   contents = plot.to_svg(size: [100, 100])
+    #   plot.to_dumb('./result.txt', size: [30, 15])
+    def to_specific_term(terminal, path = nil, **options)
+      if path
+        result = plot(term: [terminal, options], output: path)
+      else
+        path = Dir::Tmpname.make_tmpname(terminal, 0)
+        plot(term: [terminal, options], output: path)
+        result = File.binread(path)
+        File.delete(path)
+      end
+      result
+    end
+
+    ##
+    # Returns terminal object linked with this Plottable object.
+    def own_terminal
+      @terminal ||= Terminal.new
+    end
   end
 end

data/lib/gnuplotrb/multiplot.rb

@@ -2,6 +2,7 @@ module GnuplotRB
   ##
   # === Overview
   # Multiplot allows to place several plots on one layout.
+  # It's usage is covered in {multiplot notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/multiplot_layout.ipynb].
   class Multiplot
     include Plottable
     ##
@@ -11,32 +12,16 @@ module GnuplotRB
     ##
     # ====== Arguments
     # * *plots* are Plot or Splot objects which should be placed
-    #   on this multiplot
+    #   on this multiplot layout
     # * *options* will be considered as 'settable' options of gnuplot
-    #   ('set xrange [1:10]' for { xrange: 1..10 },
-    #   "set title 'plot'" for { title: 'plot' } etc) just as in Plot.
+    #   ('set xrange [1:10]' for { xrange: 1..10 } etc) just as in Plot.
     #   Special options of Multiplot are :layout and :title.
     def initialize(*plots, **options)
       @plots = plots[0].is_a?(Hamster::Vector) ? plots[0] : Hamster::Vector.new(plots)
       @options = Hamster.hash(options)
-      @terminal = Terminal.new
       OptionHandling.validate_terminal_options(@options)
     end
 
-    ##
-    # Create new Multiplot object with the same set of plots and
-    # given options.
-    def new_with_options(options)
-      self.class.new(@plots, options)
-    end
-
-    ##
-    # Check if given options corresponds to multiplot.
-    # Multiplot special options are :title and :layout.
-    def mp_option?(key)
-      %w(title layout).include?(key.to_s)
-    end
-
     ##
     # ====== Overview
     # This outputs all the plots to term (if given) or to this
@@ -47,15 +32,13 @@ module GnuplotRB
     #   ('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(term = nil, **options)
-      all_options = @options.merge(options)
-      mp_options, plot_options = all_options.partition { |key, _value| mp_option?(key) }
-      plot_options = plot_options.merge(multiplot: mp_options.to_h)
-      terminal = term || (plot_options[:output] ? Terminal.new : @terminal)
-      terminal.set(plot_options)
-      @plots.each { |graph| graph.plot(terminal, multiplot_part: true) }
-      terminal.unset(plot_options.keys)
+    # :term and :output which are ignored in this case).
+    def plot(term = nil, multiplot_part: false, **options)
+      plot_options = mix_options(options) do |plot_opts, mp_opts|
+        plot_opts.merge(multiplot: mp_opts.to_h)
+      end
+      terminal = term || (plot_options[:output] ? Terminal.new : own_terminal)
+      multiplot(terminal, plot_options)
       if plot_options[:output]
         # guaranteed wait for plotting to finish
         terminal.close unless term
@@ -78,10 +61,10 @@ module GnuplotRB
     # * *position* - position of plot which you need to update
     #   (by default first plot is updated)
     # * *options* - options to update plot with
-    # * method also may take a block which returns a plot
+    # * *&block* - method also may take a block which returns a plot
     # ====== Example
     #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
-    #   updated_mp = mp.update_plot(title: 'Sin(x) and Exp(x)') { |sinx| sinx.add_dataset('exp(x)') }
+    #   updated_mp = mp.update_plot(title: 'Sin(x) and Exp(x)') { |sinx| sinx.add('exp(x)') }
     def update_plot(position = 0, **options)
       return self unless block_given? if options.empty?
       replacement = @plots[position].options(options)
@@ -110,20 +93,22 @@ module GnuplotRB
 
     ##
     # ====== Overview
-    # Create new Multiplot with given *plot* added before plot at given *position*.
+    # Create new Multiplot with given *plots* added before plot at given *position*.
     # (by default it adds plot at the front).
     # ====== Arguments
     # * *position* - position before which you want to add a plot
-    # * *plot* - plot you want to add
+    # * *plots* - sequence of plots you want to add
     # ====== Example
     #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
-    #   enlarged_mp = mp.add_plot(Plot.new('exp(x)')).layout([3,1])
-    def add_plot(position = 0, plot)
-      self.class.new(@plots.insert(position, plot), @options)
+    #   enlarged_mp = mp.add_plots(Plot.new('exp(x)')).layout([3,1])
+    def add_plots(*plots)
+      plots.unshift(0) unless plots[0].is_a?(Numeric)
+      self.class.new(@plots.insert(*plots), @options)
     end
 
-    alias_method :<<, :add_plot
-    alias_method :add, :add_plot
+    alias_method :add_plot, :add_plots
+    alias_method :<<, :add_plots
+    alias_method :add, :add_plots
 
     ##
     # ====== Overview
@@ -142,9 +127,64 @@ module GnuplotRB
 
     ##
     # ====== Overview
-    # Equal to #plots[*args] 
+    # Equal to #plots[*args]
     def [](*args)
       @plots[*args]
     end
+
+    private
+
+    ##
+    # Default options to be used for that plot
+    def default_options
+      {
+        layout: [2, 2],
+        title: 'Multiplot'
+      }
+    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(
+        title
+        layout
+      )
+    end
+
+    ##
+    # Create new Multiplot object with the same set of plots and
+    # given options.
+    # Used in OptionHandling module.
+    def new_with_options(options)
+      self.class.new(@plots, options)
+    end
+
+    ##
+    # Check if given options corresponds to multiplot.
+    # Uses #specific_keys to check.
+    def specific_option?(key)
+      specific_keys.include?(key.to_s)
+    end
+
+    ##
+    # Takes all options and splits them into specific and
+    # others. Requires a block where this two classes should
+    # be mixed.
+    def mix_options(options)
+      all_options = @options.merge(options)
+      specific_options, plot_options = all_options.partition { |key, _value| specific_option?(key) }
+      yield(plot_options, default_options.merge(specific_options))
+    end
+
+    ##
+    # Just a part of #plot.
+    def multiplot(terminal, options)
+      terminal.set(options)
+      @plots.each { |graph| graph.plot(terminal, multiplot_part: true) }
+      terminal.unset(options.keys)
+    end
   end
 end

data/lib/gnuplotrb/plot.rb

@@ -14,27 +14,21 @@ module GnuplotRB
     # * *options* will be considered as 'settable' options of gnuplot
     #   ('set xrange [1:10]' for { xrange: 1..10 },
     #   "set title 'plot'" for { title: 'plot' } etc)
-    def initialize(*datasets, **options)
-      @datasets = if datasets[0].is_a? Hamster::Vector
-                    datasets[0]
-                  else
-                    Hamster::Vector.new(datasets).map { |ds| dataset_from_any(ds) }
-                  end
-      @options = Hamster.hash(options)
-      @already_plotted = false
+    def initialize(*datasets)
+      # had to relace **options arg with this because in some cases
+      # Daru::DataFrame was mentioned as hash and added to options
+      # instead of plots
+      @options = Hamster.hash
+      if datasets[-1].is_a?(Hamster::Hash) || datasets[-1].is_a?(Hash)
+        @options = Hamster.hash(datasets[-1])
+        datasets = datasets[0..-2]
+      end
+      @datasets = parse_datasets_array(datasets)
       @cmd = 'plot '
-      @terminal = Terminal.new
       OptionHandling.validate_terminal_options(@options)
       yield(self) if block_given?
     end
 
-    ##
-    # For inner use!
-    # Creates new Plot with existing data and given options.
-    def new_with_options(options)
-      self.class.new(@datasets, options)
-    end
-
     ##
     # ====== Overview
     # This outputs plot to term (if given) or to this plot's own terminal.
@@ -45,21 +39,23 @@ module GnuplotRB
     #   ('set xrange [1:10]', 'set title 'plot'' etc)
     # Options passed here have priority over already existing.
     def plot(term = nil, multiplot_part: false, **options)
-      opts = @options.merge(options)
-      opts = opts.reject { |key, _value| [:term, :output].include?(key) } if multiplot_part
-      terminal = term || (opts[:output] ? Terminal.new : @terminal)
-      full_command = @cmd + @datasets.map { |dataset| dataset.to_s(terminal) }.join(' , ')
-      terminal.set(opts)
-              .puts(full_command)
-              .unset(opts.keys)
-      if opts[:output]
+      fail ArgumentError, 'Empty plots are not supported!' if @datasets.empty?
+      inner_opts = if multiplot_part
+                     @options.merge(options).reject { |key, _| [:term, :output].include?(key) }
+                   else
+                     @options.merge(options)
+                   end
+      terminal = term || (inner_opts[:output] ? Terminal.new : own_terminal)
+      ds_string = @datasets.map { |dataset| dataset.to_s(terminal) }.join(' , ')
+      full_command = @cmd + ds_string
+      terminal.set(inner_opts).stream_puts(full_command).unset(inner_opts.keys)
+      if inner_opts[:output]
         # guaranteed wait for plotting to finish
         terminal.close unless term
         # not guaranteed wait for plotting to finish
         # work bad with terminals like svg and html
-        sleep 0.01 until File.size?(opts[:output])
+        sleep 0.01 until File.size?(inner_opts[:output])
       end
-      @already_plotted = true
       self
     end
 
@@ -101,20 +97,25 @@ module GnuplotRB
 
     ##
     # ====== Overview
-    # Create new Plot object where given dataset will
-    # be appended to dataset list.
+    # Create new Plot object where given datasets will
+    # be inserted into dataset list before given position
+    # (position = 0 by default).
     # ====== Arguments
-    # * *dataset* - dataset to add
+    # * *position* - position where to insert given datasets
+    # * *datasets* - sequence of datasets to add
     # ====== Example
     #   sinx = Plot.new('sin(x)')
-    #   sinx_and_cosx = sinx.add(['cos(x)'])
+    #   sinx_and_cosx_with_expx = sinx.add(['cos(x)'], ['exp(x)'])
     #
     #   cosx_and_sinx = sinx << ['cos(x)']
-    def add_dataset(dataset)
-      self.class.new(@datasets.add(dataset_from_any(dataset)), @options)
+    def add_datasets(*datasets)
+      datasets.map! { |ds| ds.is_a?(Numeric) ? ds : dataset_from_any(ds) }
+      datasets.unshift(0) unless datasets[0].is_a?(Numeric)
+      self.class.new(@datasets.insert(*datasets), @options)
     end
 
-    alias_method :<<, :add_dataset
+    alias_method :add_dataset, :add_datasets
+    alias_method :<<, :add_datasets
 
     ##
     # ====== Overview
@@ -138,15 +139,58 @@ module GnuplotRB
       @datasets[*args]
     end
 
+    private
+
+    ##
+    # Checks several conditions and set options needed
+    # to handle DateTime indexes properly.
+    def provide_with_datetime_format(data, using)
+      return unless defined?(Daru)
+      return unless data.is_a?(Daru::DataFrame) || data.is_a?(Daru::Vector)
+      return unless data.index.first.is_a?(DateTime)
+      return if using[0..1] != '1:'
+      @options = @options.merge(
+        xdata: 'time',
+        timefmt: '%Y-%m-%dT%H:%M:%S',
+        format_x: '%d\n%b\n%Y'
+      )
+    end
+
     ##
-    # Method for inner use.
     # Check if given args is a dataset and returns it. Creates
     # new dataset from given args otherwise.
     def dataset_from_any(source)
-      source.is_a?(Dataset) ? source.clone : Dataset.new(*source)
+      ds = case source
+           # when initialized with dataframe (it passes here several vectors)
+           when (defined?(Daru) ? Daru::Vector : nil)
+             Dataset.new(source)
+           when Dataset
+             source.clone
+           else
+             Dataset.new(*source)
+           end
+      data = source.is_a?(Array) ? source[0] : source
+      provide_with_datetime_format(data, ds.using)
+      ds
+    end
+
+    ##
+    # Parses given array and returns Hamster::Vector of Datasets
+    def parse_datasets_array(datasets)
+      case datasets[0]
+      when Hamster::Vector
+        datasets[0]
+      when (defined?(Daru) ? Daru::DataFrame : nil)
+        Hamster::Vector.new(datasets[0].map { |ds| dataset_from_any(ds) })
+      else
+        Hamster::Vector.new(datasets.map { |ds| dataset_from_any(ds) })
+      end
     end
 
-    private :dataset_from_any,
-            :new_with_options
+    ##
+    # Creates new Plot with existing data and given options.
+    def new_with_options(options)
+      self.class.new(@datasets, options)
+    end
   end
 end