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.

Parameters:

  • *datasets (Sequence of Dataset or Array) —

    either instances of Dataset class or “[data, **dataset_options]”“ arrays

  • options (Hash) —

    see Plot top level doc for options examples

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

#datasets ⇒ Object (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

Parameters:

  • position (Integer) —

    position of dataset BEFORE which datasets will be placed. 0 by default.

  • *datasets (Sequence of Dataset or Array) —

    datasets to insert



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

Parameters:

  • position (Integer) —

    position of dataset BEFORE which datasets will be placed. 0 by default.

  • *datasets (Sequence of Dataset or Array) —

    datasets to insert



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.

Parameters:

  • term (Terminal) (defaults to: nil) —

    Terminal object to plot to

  • :multiplot_part (Boolean) —

    true if this plot is part of a multiplot. For inner use!

  • options (Hash) —

    see options in Plot top level doc. Options passed here have priority over already existing.

Returns:



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

Parameters:

  • position (Integer) (defaults to: -1)) —

    position of dataset that should be removed (by default last dataset is removed)



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

Parameters:

  • position (Integer) (defaults to: -1)) —

    position of dataset that should be removed (by default last dataset is removed)



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

Parameters:

  • position (Integer) (defaults to: 0) —

    position of dataset which you need to replace (by default first dataset is replaced)

  • dataset (Dataset, Array) —

    dataset to replace the old one. You can also give here “[data, **dataset_options]”“ array from which Dataset may be created.



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

Parameters:

  • position (Integer) (defaults to: 0) —

    position of dataset which you need to replace (by default first dataset is replaced)

  • dataset (Dataset, Array) —

    dataset to replace the old one. You can also give here “[data, **dataset_options]”“ array from which Dataset may be created.



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)

Parameters:

  • position (Integer) (defaults to: 0) —

    position of dataset which you need to update (by default first dataset is updated)

  • data (#to_gnuplot_points) (defaults to: nil) —

    data to update dataset with

  • options (Hash) —

    options to update dataset with, see Dataset top level doc



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

Parameters:

  • position (Integer) (defaults to: 0) —

    position of dataset which you need to update (by default first dataset is updated)

  • data (#to_gnuplot_points) (defaults to: nil) —

    data to update dataset with

  • options (Hash) —

    options to update dataset with, see Dataset top level doc



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