Class: GnuplotRB::Plot

Inherits:
Object
  • Object
show all
Includes:
Plottable
Defined in:
lib/gnuplotrb/plot.rb

Overview

Class corresponding to simple 2D visualisation.

Notebooks

Options

All possible options are exaplained in gnuplot docs (pp. 105-190).

Several common ones:

  • xrange(yrange, zrange, urange, vrange) - set range for a variable. Takes Range (xrange: 0..100), or String (yrange: '[0:100]').

  • title - plot's title. Takes String (title: 'Some new plot').

  • polar (parametric) - plot in polar or parametric space. Takes boolean (true).

  • style_data - set style for plotting data. Takes string, possible values: histogram, points, lines, linespoints, boxes etc. See gnuplot docs for more.

  • term - select terminal used by gnuplot. Examples: { term: 'png' }, { term: ['svg', size: [600, 600]] }. Deprecated due to existance of #to_<term_name> methods. One can use #to_png and #to_svg(size: [600, 600]) instead of passing previous options.

  • output - select filename to output plot to. Should be used together with term. Deprecated due to existance of #to_<term_name> methods. One should use #to_png('file.png') instead of passing { term: 'png', output: 'file.png' }.

Every option may be passed to constructor in order to create plot with it.

Methods #options(several: options, …) and bunch of #option_name(only_an: option) such as #xrange, #using, #polar etc create new Plot object based on existing but with a new options.

Methods with the same names ending with '!' or '=' ('plot.xrange!(1..3)', 'plot.title = “New title”') are destructive and modify state of existing object just as “Array#sort!” do with Array object. See notebooks for examples.

Direct Known Subclasses

Splot

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Plottable

#method_missing, #option_name, #option_name!, #own_terminal, #respond_to?, #title, #title!, #to_canvas, #to_gif, #to_iruby, #to_png, #to_specific_term, #to_svg, #xrange, #xrange!, #yrange, #yrange!

Methods included from OptionHandling

option_to_string, #options, #options!, ruby_class_to_gnuplot, string_key, valid_terminal?, validate_terminal_options

Constructor Details

#initialize(*datasets) {|_self| ... } ⇒ Plot

Returns a new instance of Plot

Yields:

  • (_self)

Yield Parameters:


48
49
50
51
52
53
54
55
56
57
58
59
60
61
# File 'lib/gnuplotrb/plot.rb', line 48

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.empty
  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 '
  OptionHandling.validate_terminal_options(@options)
  yield(self) if block_given?
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class GnuplotRB::Plottable

Instance Attribute Details

#datasetsObject (readonly)

Array of datasets which are plotted by this object.


43
44
45
# File 'lib/gnuplotrb/plot.rb', line 43

def datasets
  @datasets
end

Instance Method Details

#[](*args) ⇒ Object

The same as #datasets


241
242
243
# File 'lib/gnuplotrb/plot.rb', line 241

def [](*args)
  @datasets[*args]
end

#add_datasets(*datasets) ⇒ Object Also known as: add_dataset, <<

Create new Plot object where given datasets will be inserted into dataset list before given position (position = 0 by default).

Examples:

sinx = Plot.new('sin(x)')
sinx_and_cosx_with_expx = sinx.add(['cos(x)'], ['exp(x)'])

cosx_and_sinx = sinx << ['cos(x)']
# sinx IS NOT affected in both cases

178
179
180
181
182
183
# File 'lib/gnuplotrb/plot.rb', line 178

def add_datasets(*datasets)
  datasets.map! { |ds| ds.is_a?(Numeric) ? ds : dataset_from_any(ds) }
  # first element is position where to add datasets
  datasets.unshift(0) unless datasets[0].is_a?(Numeric)
  self.class.new(@datasets.insert(*datasets), @options)
end

#add_datasets!(*datasets) ⇒ Object Also known as: add_dataset!

Updates existing Plot object by inserting given datasets into dataset list before given position (position = 0 by default).

Examples:

sinx = Plot.new('sin(x)')
sinx.add!(['cos(x)'], ['exp(x)'])
# sinx IS affected

199
200
201
202
203
204
205
# File 'lib/gnuplotrb/plot.rb', line 199

def add_datasets!(*datasets)
  datasets.map! { |ds| ds.is_a?(Numeric) ? ds : dataset_from_any(ds) }
  # first element is position where to add datasets
  datasets.unshift(0) unless datasets[0].is_a?(Numeric)
  @datasets = @datasets.insert(*datasets)
  self
end

#plot(term = nil, multiplot_part: false, **options) ⇒ Plot Also known as: replot

Output plot to term (if given) or to this plot's own terminal.


71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# File 'lib/gnuplotrb/plot.rb', line 71

def plot(term = nil, multiplot_part: false, **options)
  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?(inner_opts[:output])
  end
  self
end

#remove_dataset(position = -1)) ⇒ Object

Create new Plot object where dataset at given position will be removed from dataset list.

Examples:

sinx_and_cosx = Plot.new('sin(x)', 'cos(x)')
sinx = sinx_and_cosx.remove_dataset
cosx = sinx_and_cosx.remove_dataset(0)
# sinx_and_cosx IS NOT affected in both cases

220
221
222
# File 'lib/gnuplotrb/plot.rb', line 220

def remove_dataset(position = -1)
  self.class.new(@datasets.delete_at(position), @options)
end

#remove_dataset!(position = -1)) ⇒ Object

Updates existing Plot object by removing dataset at given position.

Examples:

sinx_and_cosx = Plot.new('sin(x)', 'cos(x)')
sinx_and_cosx!.remove_dataset
sinx_and_cosx!.remove_dataset
# sinx_and_cosx IS affected and now is empty

234
235
236
237
# File 'lib/gnuplotrb/plot.rb', line 234

def remove_dataset!(position = -1)
  @datasets = @datasets.delete_at(position)
  self
end

#replace_dataset(position = 0, dataset) ⇒ Object

Create new Plot object where dataset at position will be replaced with the given one.

Examples:

sinx = Plot.new('sin(x)')
cosx = sinx.replace_dataset(['cos(x)'])
# sinx IS NOT affected

141
142
143
# File 'lib/gnuplotrb/plot.rb', line 141

def replace_dataset(position = 0, dataset)
  self.class.new(@datasets.set(position, dataset_from_any(dataset)), @options)
end

#replace_dataset!(position = 0, dataset) ⇒ Object Also known as: []=

Updates existing Plot object by replacing dataset at position with the given one.

Examples:

sinx = Plot.new('sin(x)')
sinx.replace_dataset!(['cos(x)'])
# sinx IS affected

157
158
159
160
# File 'lib/gnuplotrb/plot.rb', line 157

def replace_dataset!(position = 0, dataset)
  @datasets = @datasets.set(position, dataset_from_any(dataset))
  self
end

#update_dataset(position = 0, data: nil, **options) ⇒ Object

Create new Plot object where dataset at position will be replaced with the new one created from it by updating.

Examples:

updated_plot = plot.update_dataset(data: [x1,y1], title: 'After update')
# plot IS NOT affected (if dataset did not store data in a file)

106
107
108
109
110
# File 'lib/gnuplotrb/plot.rb', line 106

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

#update_dataset!(position = 0, data: nil, **options) ⇒ Object

Updates existing Plot object by replacing dataset at position with the new one created from it by updating.

Examples:

plot.update_dataset!(data: [x1,y1], title: 'After update')
# plot IS affected anyway

124
125
126
127
# File 'lib/gnuplotrb/plot.rb', line 124

def update_dataset!(position = 0, data: nil, **options)
  @datasets[position].update!(data, options)
  self
end