SciRuby / gnuplotrb

Google Summer of Code 2015 project

GnuplotRB

GnuplotRB is a plot generator for Ruby based on Gnuplot.

This software has been developed as a product in Google Summer of Code 2015 (GSoC2015). Its progress may be saw in SciRuby mailing list or in project's blog.

Table of contents

• Installation
• Getting started
  • Plottable classes
  • Notebooks
  • Plain examples
• Contributing

Installation

Dependencies

• Ruby 2.0+
• It is required to install gnuplot 5.0 to use that gem.

Gem installation

Install latest stable version from Rubygems

gem install gnuplotrb

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/sciruby/gnuplotrb.git
cd gnuplotrb
bundle install
rake install

Getting started

GnuplotRB gem is based on Gnuplot so I would recommend to use Gnuplot doc and GnuplotRB doc at Rubydoc in cases when docs and examples (as notebooks and plain examples) present here are not enough to explain how to plot something.

Plottable classes

Each of plottable classes may be outputted to image file using #to_png, #to_svg, #to_gif and so on methods. You can read more about it in GnuplotRB doc related to Plottable module or see examples in beginners notebook.

Dataset

Single dataset may be created with math formula ('sin(x)') or some data. If your data is stored in a file you can just pass a filename (e.g. 'gnuplotrb.data'). Dataset may also be constructed out of data contained in Ruby classes (Array, Daru containers), see example notebooks.

Dataset have several possible options which are explained in gnuplot doc (pp. 80-102). Options are passed to Dataset.new as hash and are tranlated into gnuplot format before plotting:

Dataset.new(data, with: 'lines', using: '1:2')

Examples of option translation (nested containers allowed):

• Hash:

{ key1: "value1", key2: { nested_key1: "nested_value1" } } # => "key1 value1 key2 nested key1 nested_value1"

• Hashes with underscored keys (see #7):

{ style_data: 'histograms' } #=> "style data histograms"

• Range:

{ xrange: 0..100 } # => "xrange [0:100]"

• Array (often used with nested hashes) and Array of Numeric

['png', { size: [400, 500] }] # => "png size 400,500"

• Others

some_object # => some_object.to_s

Once Dataset created, it may be updated with new data or options. Methods related to updating are explained in a notebook.

Just as other Plottable object Dataset has several plotting methods which are desribed in beginners notebook.

Plot

Plot is a container for several datasets and layout options:

Plot.new(ds1, ds2, ds2, xrange: 1..10)

Datasets contained bu Plot are outputted on single xy plain.

Plot's options are explained in gnuplot doc (pp. 105-181). Plot options are translated into gnuplot format the same way as Dataset's (except adding 'set' before each option). Plot's datasets and Plot itself may be updated with almost the same methods as desribed in Dataset section above.

Splot

Almost the same as Plot but for 3-D plots. See Plot section.

Multiplot

Container for several Plot or Splot objects, each of them is plotted in its own xy(z) space. So Multiplot offers single layout (image filewindow) for several plots. It's grid is tuned by :layout option, and you can also set layout's title:

Multiplot.new(plot1, plot2, splot1, layout: [3, 1], title: 'Three plots on a layout')

Updating methods for Multiplot are almost the same as Plot's and Dataset's and are covered in Multiplot's docs and multiplot notebook. See examples there.

Animation

Animation is a container for several Plot, Splot or Multiplot objects. Each of contained items is considered as frame in gif animation which is creating by #plot call. Animation's frames and options may be modifyed or updated just as other classes above. Animation does not support methods like #to_png and may be plotted only with #plot method. Please see related notebook and docs at RubyDoc for examples.

Notebooks

This notebooks are powered by Ruby kernel for IPython/Jupyter. 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. It also covers installation of iPython and other dependecies.
• GnuplotRB gem installation covered in README too.

Embedding plots into iRuby

Using GnuplotRB inside iRuby notebooks is covered in:

• Basic usage notebook.

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
• Vectorfield (Thanks, Alexej)
• Math equations
• 3D visualizations
• Histogram

Possible datasources

GnuplotRB may take data in Ruby container or in a file. Supported containers for now are Array, 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
• Data given in Daru containers
• Data given in Daru containers (with timeseries)
• Updating plots with new data

Multiplot

You can not only plot several datasets in single coordinate system but place several coordinate systems on a canvas.

• Multiplot example notebook.

Animation

It's possible to use several plots (Plot, Splot or Multiplot objects) to create gif animation.

• Animation example notebook.

Fitting data with formula

GnuplotRB also may be used to fit some data with given math formula.

• Fitting data

Plain examples

You may find several examples in examples directory.

Contributing

1. Fork repository
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