gnuplotrb 0.2.0

data/lib/gnuplotrb/multiplot.rb

@@ -0,0 +1,150 @@
+module GnuplotRB
+  ##
+  # === Overview
+  # Multiplot allows to place several plots on one layout.
+  class Multiplot
+    include Plottable
+    ##
+    # Array of plots contained by this object.
+    attr_reader :plots
+
+    ##
+    # ====== Arguments
+    # * *plots* are Plot or Splot objects which should be placed
+    #   on this multiplot
+    # * *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.
+    #   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
+    # Multiplot's own terminal.
+    # ====== 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(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)
+      if plot_options[: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?(plot_options[:output])
+      end
+      self
+    end
+
+    ##
+    # ====== Overview
+    # Create new Multiplot object where plot (Plot or Splot object)
+    # at *position* will
+    # be replaced with the new one created from it by updating.
+    # To update a plot you can pass some options for it or a
+    # block, that should take existing plot (with new options if
+    # you gave them) and return a plot too.
+    # ====== Arguments
+    # * *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
+    # ====== 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)') }
+    def update_plot(position = 0, **options)
+      return self unless block_given? if options.empty?
+      replacement = @plots[position].options(options)
+      replacement = yield(replacement) if block_given?
+      replace_plot(position, replacement)
+    end
+
+    alias_method :update, :update_plot
+
+    ##
+    # ====== Overview
+    # Create new Multiplot object where plot (Plot or Splot object)
+    # at *position* will be replaced with the given one.
+    # ====== Arguments
+    # * *position* - position of plot which you need to update
+    #   (by default first plot is updated)
+    # * *plot* - replacement for existing plot
+    # ====== Example
+    #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
+    #   mp_with_replaced_plot = mp.replace_plot(Plot.new('exp(x)', title: 'exp instead of sin'))
+    def replace_plot(position = 0, plot)
+      self.class.new(@plots.set(position, plot), @options)
+    end
+
+    alias_method :replace, :replace_plot
+
+    ##
+    # ====== Overview
+    # Create new Multiplot with given *plot* 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
+    # ====== 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)
+    end
+
+    alias_method :<<, :add_plot
+    alias_method :add, :add_plot
+
+    ##
+    # ====== Overview
+    # Create new Multiplot without plot at given position
+    # (by default last plot is removed).
+    # ====== Arguments
+    # * *position* - position of plot you want to remove
+    # ====== Example
+    #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
+    #   mp_with_only_cos = mp.remove_plot(0)
+    def remove_plot(position = -1)
+      self.class.new(@plots.delete_at(position), @options)
+    end
+
+    alias_method :remove, :remove_plot
+
+    ##
+    # ====== Overview
+    # Equal to #plots[*args] 
+    def [](*args)
+      @plots[*args]
+    end
+  end
+end

data/lib/gnuplotrb/plot.rb

@@ -0,0 +1,152 @@
+module GnuplotRB
+  ##
+  # === Overview
+  # Plot correspond to simple 2D visualisation
+  class Plot
+    include Plottable
+    ##
+    # Array of datasets which are plotted by this object.
+    attr_reader :datasets
+    ##
+    # ====== Arguments
+    # * *datasets* are either instances of Dataset class or
+    #   [data, **dataset_options] arrays from which Dataset may be created
+    # * *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
+      @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.
+    # ====== Arguments
+    # * *term* - Terminal to plot to
+    # * *multiplot_part* - part of a multiplot. Option for inner usage
+    # * *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.
+    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]
+        # 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])
+      end
+      @already_plotted = true
+      self
+    end
+
+    alias_method :replot, :plot
+
+    ##
+    # ====== Overview
+    # Create new Plot object where dataset at *position* will
+    # be replaced with the new one created from it by updating.
+    # ====== Arguments
+    # * *position* - position of dataset which you need to update
+    #   (by default first dataset is updated)
+    # * *data* - data to update dataset with
+    # * *options* - options to update dataset with
+    # ====== Example
+    #   updated_plot = plot.update_dataset(data: [x1,y1], title: 'After update')
+    def update_dataset(position = 0, data: nil, **options)
+      old_ds = @datasets[position]
+      new_ds = old_ds.update(data, options)
+      new_ds.equal?(old_ds) ? self : replace_dataset(position, new_ds)
+    end
+
+    ##
+    # ====== Overview
+    # Create new Plot object where dataset at *position* will
+    # be replaced with the given one.
+    # ====== Arguments
+    # * *position* - position of dataset which you need to update
+    #   (by default first dataset is replaced)
+    # * *dataset* - dataset to replace the old one. You can also
+    #   give here [data, **dataset_options] array from
+    #   which Dataset may be created.
+    # ====== Example
+    #   sinx = Plot.new('sin(x)')
+    #   cosx = sinx.replace_dataset(['cos(x)'])
+    def replace_dataset(position = 0, dataset)
+      self.class.new(@datasets.set(position, dataset_from_any(dataset)), @options)
+    end
+
+    ##
+    # ====== Overview
+    # Create new Plot object where given dataset will
+    # be appended to dataset list.
+    # ====== Arguments
+    # * *dataset* - dataset to add
+    # ====== Example
+    #   sinx = Plot.new('sin(x)')
+    #   sinx_and_cosx = sinx.add(['cos(x)'])
+    #
+    #   cosx_and_sinx = sinx << ['cos(x)']
+    def add_dataset(dataset)
+      self.class.new(@datasets.add(dataset_from_any(dataset)), @options)
+    end
+
+    alias_method :<<, :add_dataset
+
+    ##
+    # ====== Overview
+    # Create new Plot object where dataset at given position
+    # will be removed from dataset list.
+    # ====== Arguments
+    # * *position* - position of dataset that should be
+    #   removed (by default last dataset is removed)
+    # ====== Example
+    #   sinx_and_cosx = Plot.new('sin(x)', 'cos(x)')
+    #   sinx = sinx_and_cosx.remove_dataset
+    #   cosx = sinx_and_cosx.remove_dataset(0)
+    def remove_dataset(position = -1)
+      self.class.new(@datasets.delete_at(position), @options)
+    end
+
+    ##
+    # ====== Overview
+    # The same as Plot#datasets[args]
+    def [](*args)
+      @datasets[*args]
+    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)
+    end
+
+    private :dataset_from_any,
+            :new_with_options
+  end
+end

data/lib/gnuplotrb/splot.rb

@@ -0,0 +1,18 @@
+module GnuplotRB
+  ##
+  # === Overview
+  # Splot class correspond to simple 3D visualisation
+  class Splot < Plot
+    ##
+    # ==== Arguments
+    # * *datasets* are either instances of Dataset class or
+    #   [data, **dataset_options] arrays
+    # * *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)
+      super
+      @cmd = 'splot '
+    end
+  end
+end

data/lib/gnuplotrb/staff/datablock.rb

@@ -0,0 +1,70 @@
+module GnuplotRB
+  ##
+  # === Overview
+  # This class corresponds to points we want to plot. It may be
+  # stored in temporary file (to allow fast update) or inside
+  # "$DATA << EOD ... EOD" construction. Datablock stores data passed
+  # to constructor and keeps datablock name or path to file where it is stored.
+  class Datablock
+    ##
+    # ====== Parameters
+    # * *data* - sequence of anything with +#to_gnuplot_points+ method.
+    # * *stored_in_file* true here will force this datablock to store its data
+    #   in temporary file.
+    def initialize(data, stored_in_file = false)
+      @stored_in_file = stored_in_file
+      data_str = data.to_gnuplot_points
+      if @stored_in_file
+        @file_name = Dir::Tmpname.make_tmpname('tmp_data', 0)
+        File.write(@file_name, data_str)
+        name = File.join(Dir.pwd, @file_name)
+        ObjectSpace.define_finalizer(self, proc { File.delete(name) })
+      else
+        @data = data_str
+      end
+    end
+
+    ##
+    # ====== Overview
+    # Instantiate one more Datablock with updated data
+    # if data stored in here-doc. Append update to file
+    # if data stored there.
+    # ====== Parameters
+    # * *data* - anything with +#to_gnuplot_points+ method
+    def update(data)
+      data_str = data.to_gnuplot_points
+      if @stored_in_file
+        File.open(@file_name, 'a') { |f| f.puts "\n#{data_str}" }
+        self
+      else
+        Datablock.new("#{@data}\n#{data_str}", false)
+      end
+    end
+
+    ##
+    # ====== Overview
+    # Returns quoted filename if datablock stored in file or outputs
+    # datablock to gnuplot and returns its name otherwise.
+    # * *gnuplot_term* should be given if datablock not stored in file.
+    def name(gnuplot_term = nil)
+      if @stored_in_file
+        "'#{@file_name}'"
+      else
+        fail(ArgumentError, 'No terminal given to output datablock') unless gnuplot_term
+        gnuplot_term.store_datablock(@data)
+      end
+    end
+
+    alias_method :to_s, :name
+
+    ##
+    # ====== Overview
+    # Overridden #clone. Since datablock which store data
+    # in temporary files should not be cloned (otherwise it will cause
+    # double attempt to delete file), this #clone returns self for such
+    # cases. For other cases it just calls default #clone.
+    def clone
+      @stored_in_file ? self : super
+    end
+  end
+end

data/lib/gnuplotrb/staff/dataset.rb

@@ -0,0 +1,233 @@
+module GnuplotRB
+  ##
+  # === Overview
+  # Dataset keeps control of Datablock or String (some math functions like
+  # this 'x*sin(x)' or filename) and options related to original dataset
+  # in gnuplot (with, title, using etc).
+  class Dataset
+    include OptionHandling
+    ##
+    # Data represented by this dataset
+    attr_reader :data
+
+    ##
+    # Order is significant for some options
+    OPTION_ORDER = %w(index using axes title)
+
+    ##
+    # Hash of init handlers for data given in 
+    # different containers.
+    INIT_HANDLERS = Hash.new(:init_default).merge(
+      String =>          :init_string,
+      Datablock =>       :init_dblock
+    )
+    INIT_HANDLERS.merge!(
+      Daru::DataFrame => :init_daru_frame,
+      Daru::Vector =>    :init_daru_vector
+    ) if defined? Daru
+
+    ##
+    # ====== Overview
+    # Creates new dataset out of given string with
+    # math function or filename. If *data* isn't a string
+    # it will create datablock to store data.
+    # ====== Parameters
+    # * *data* - String, Datablock or something acceptable by
+    #   Datablock.new as data (e.g. [x,y] where x and y are arrays)
+    # * *options* - hash of options specific for gnuplot
+    #   dataset, and some special options ('file: true' will
+    #   make data to be stored inside temporary file).
+    # ====== Examples
+    # Math function:
+    #   Dataset.new('x*sin(x)', with: 'lines', lw: 4)
+    # File with points:
+    #   Dataset.new('points.data', with: 'lines', title: 'Points from file')
+    # Some data (creates datablock stored in memory):
+    #   x = (0..5000).to_a
+    #   y = x.map {|xx| xx*xx }
+    #   points = [x, y]
+    #   Dataset.new(points, with: 'points', title: 'Points')
+    # The same data but datablock stores it in temp file:
+    #   Dataset.new(points, with: 'points', title: 'Points', file: true)
+    def initialize(data, **options)
+      self.send(INIT_HANDLERS[data.class], data, options)
+    end
+
+    ##
+    # Method for inner use.
+    def init_string(data, options)
+      @type, @data= if File.exist?(data)
+        [:datafile, "'#{data}'"]
+      else
+        [:math_function, data.clone]
+      end
+      @options = Hamster.hash(options)
+    end
+
+    ##
+    # Method for inner use.
+    def init_dblock(data, options)
+      @type = :datablock
+      @data = data.clone
+      @options = Hamster.hash(options)
+    end
+
+    ##
+    # Method for inner use.
+    # TODO: make it better
+    def init_daru_frame(data, options)
+      options[:title] ||= data.name
+      if options[:using]
+        options[:using] = " #{options[:using]} "
+        data.vectors.to_a.each_with_index do |daru_index, array_index|
+          options[:using].gsub!(/([\:\( ])#{daru_index}([\:\) ])/) { "#{$1}#{array_index + 2}#{$2}"}
+        end
+        options[:using].gsub!(/index/) { 1 }
+        options[:using].strip!
+      else
+        new_opt = (2...(2 + data.vectors.size)).to_a.join(':')
+        options[:using] = "#{new_opt}:xtic(1)"
+      end
+      init_default(data, options)
+    end
+
+    ##
+    # Method for inner use.
+    def init_daru_vector(data, options)
+      options[:using] ||= '2:xtic(1)'
+      options[:title] ||= data.name
+      init_default(data, options)
+    end
+
+    ##
+    # Method for inner use.
+    def init_default(data, file: false, **options)
+      @type = :datablock
+      @data = Datablock.new(data, file)
+      @options = Hamster.hash(options)
+    end
+
+    ##
+    # ====== Overview
+    # Converts Dataset to string containing gnuplot dataset.
+    # ====== Parameters
+    # * *terminal* - must be given if data given as Datablock and
+    #   it does not use temp file so data should be piped out
+    #   to gnuplot via terminal before use.
+    # ====== Examples
+    #   Dataset.new('points.data', with: 'lines', title: 'Points from file').to_s
+    #   #=> "'points.data' with lines title 'Points form file'"
+    #   Dataset.new(points, with: 'points', title: 'Points').to_s
+    #   #=> "$DATA1 with points title 'Points'"
+    def to_s(terminal = nil)
+      "#{@type == :datablock ? @data.name(terminal) : @data } #{options_to_string}"
+    end
+
+    ##
+    # ====== Overview
+    # Create string from own options
+    def options_to_string
+      options.sort_by { |key, _| OPTION_ORDER.find_index(key.to_s) || 999 }
+             .map { |key, value| OptionHandling.option_to_string(key, value) }
+             .join(' ')
+    end
+
+    ##
+    # ====== Overview
+    # Creates new dataset with updated data (given
+    # data is appended to existing) and merged options.
+    # Data is updated only if Dataset stores it in Datablock.
+    # Method does nothing if no options given and data isn't stored
+    # in in-memory Datablock.
+    # ====== Parameters
+    # * *data* - data to append to existing
+    # * *options* - hash to merge with existing options
+    # ====== Examples
+    # Updating dataset with Math formula or filename given:
+    #   dataset = Dataset.new('file.data')
+    #   dataset.update('asd')
+    #   #=> nothing updated
+    #   dataset.update('asd', title: 'File')
+    #   #=> Dataset.new('file.data', title: 'File')
+    # Updating dataset with data stored in Datablock:
+    #   in_memory_points = Dataset.new(points, title: 'Old one')
+    #   in_memory_points.update(some_update, title: 'Updated')
+    #   #=> Dataset.new(points + some_update, title: 'Updated')
+    #   temp_file_points = Dataset.new(points, title: 'Old one', file: true)
+    #   temp_file_points.update(some_update)
+    #   #=> data updated but no new dataset created
+    #   temp_file_points.update(some_update, title: 'Updated')
+    #   #=> data updated and new dataset with title 'Updated' returned
+    def update(data = nil, **options)
+      if data && @type == :datablock
+        new_datablock = @data.update(data)
+        if new_datablock == @data
+          update_options(options)
+        else
+          Dataset.new(@data.update(data), @options.merge(options))
+        end
+      else
+        update_options(options)
+      end
+    end
+
+    ##
+    # ====== Overview
+    # Own implementation of #clone. Creates new Dataset if
+    # data stored in datablock and calls super otherwise.
+    def clone
+      if @type == :datablock
+        Dataset.new(@data, **@options)
+      else
+        super
+      end
+    end
+
+    ##
+    # ====== Overview
+    # Creates new dataset with existing options merged with
+    # the given ones. Does nothing if no options given.
+    # ====== Parameters
+    # * *options* - hash to merge with existing options
+    # ====== Examples
+    # Updating dataset with Math formula or filename given:
+    #   dataset = Dataset.new('file.data')
+    #   dataset.update_options(title: 'File')
+    #   #=> Dataset.new('file.data', title: 'File')
+    def update_options(**options)
+      if options.empty?
+        return self
+      else
+        Dataset.new(@data, @options.merge(options))
+      end
+    end
+
+    ##
+    # Method for inner use.
+    # Needed by OptionHandling to create new object when
+    # options are changed.
+    def new_with_options(options)
+      self.class.new(@data, options)
+    end
+
+    ##
+    # ====== Overview
+    # You may set options using #option_name(option_value) method.
+    # A new object will be constructed with selected option set.
+    # And finally you can get current value of any option using
+    # #options_name without arguments.
+    # ====== Examples
+    #   dataset = Dataset.new('file.data')
+    #   dataset.title #=> nil
+    #   new_dataset = dataset.title('Awesome plot')
+    #   dataset.title #=> nil
+    #   new_dataset.title #=> 'Awesome plot'
+    def method_missing(meth_id, *args)
+      option(meth_id, *args)
+    end
+
+    private :init_default,
+            *INIT_HANDLERS.values,
+            :new_with_options
+  end
+end