Skip to content

Commit

Permalink
Fix indenting and syntax highlighting
Browse files Browse the repository at this point in the history
  • Loading branch information
@abinoam
abinoam committed Apr 9, 2017
1 parent e86e0ef commit 1972a3a
Showing 1 changed file with 86 additions and 148 deletions.
234 changes: 86 additions & 148 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
# GnuplotRB

GnuplotRB is a plot generator for Ruby based on
[Gnuplot](http://www.gnuplot.info).

Expand All @@ -22,227 +21,166 @@ This software has been developed as a product in Google Summer of Code 2015 (GSo
## Installation
### Dependencies
* Ruby 2.0+
* It is required to install [gnuplot
5.0](http://www.gnuplot.info/download.html) to use that gem.
* It is required to install [gnuplot 5.0](http://www.gnuplot.info/download.html) 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
```sh
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
```sh
git clone https://github.com/sciruby/gnuplotrb.git
cd gnuplotrb
bundle install
rake install
```

GnuplotRB gem is based on [Gnuplot](http://www.gnuplot.info/) so I would
recommend to use [Gnuplot doc](http://www.gnuplot.info/docs_5.0/gnuplot.pdf)
and [GnuplotRB doc at Rubydoc](https://rubygems.org/gems/gnuplotrb) in cases
when docs and examples (as notebooks and plain examples) present here are not
enough to explain how to plot something.
## Getting started
GnuplotRB gem is based on [Gnuplot](http://www.gnuplot.info/) so I would recommend to use [Gnuplot doc](http://www.gnuplot.info/docs_5.0/gnuplot.pdf) and [GnuplotRB doc at Rubydoc](https://rubygems.org/gems/gnuplotrb) 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](https://rubygems.org/gems/gnuplotrb) related to Plottable
module or see examples in [beginners
notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/not
ebooks/basic_usage.ipynb).
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](https://rubygems.org/gems/gnuplotrb) related to Plottable module or see examples in [beginners
notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/basic_usage.ipynb).

#### 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](https://github.com/sciruby/gnuplotrb#possible-datasources).
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](https://github.com/sciruby/gnuplotrb#possible-datasources).

Dataset have several possible options which are explained in [gnuplot
doc](http://www.gnuplot.info/docs_5.0/gnuplot.pdf) (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')
doc](http://www.gnuplot.info/docs_5.0/gnuplot.pdf) (pp. 80-102). Options are passed to Dataset.new as hash and are tranlated into gnuplot format before plotting:

```ruby
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](https://github.com/dilcom/gnuplotrb/issues/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](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/not
ebooks/updating_data.ipynb).

Just as other Plottable object Dataset has several plotting methods which are
desribed in [beginners
notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/not
ebooks/basic_usage.ipynb).

* Hash:

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

* Hashes with underscored keys (see [#7](https://github.com/dilcom/gnuplotrb/issues/7)):

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

* Range:

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

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

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

* Others

```ruby
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](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/updating_data.ipynb).

Just as other Plottable object Dataset has several plotting methods which are desribed in [beginners notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/basic_usage.ipynb).

#### Plot
Plot is a container for several datasets and layout options:
Plot.new(ds1, ds2, ds2, xrange: 1..10)
```ruby
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](http://www.gnuplot.info/docs_5.0/gnuplot.pdf) (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.
Plot's options are explained in [gnuplot doc](http://www.gnuplot.info/docs_5.0/gnuplot.pdf) (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')
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:
```ruby
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](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/not
ebooks/multiplot_layout.ipynb). See examples there.
Updating methods for Multiplot are almost the same as Plot's and Dataset's and are covered in Multiplot's docs and [multiplot notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/multiplot_layout.ipynb). 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](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/not
ebooks/animated_plots.ipynb) and docs at RubyDoc for examples.
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](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/animated_plots.ipynb) and docs at RubyDoc for examples.

### Notebooks

This notebooks are powered by [Ruby kernel](https://github.com/SciRuby/iruby/)
for [IPython/Jupyter](https://jupyter.org/). I placed them here to show some
GnuplotRB's capabilities and ways of using it together with iRuby.
This notebooks are powered by [Ruby kernel](https://github.com/SciRuby/iruby/) for [IPython/Jupyter](https://jupyter.org/). 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](https://github.com/SciRuby/iruby/blob/master/README.md). It also
covers installation of iPython and other dependecies.
* GnuplotRB gem installation covered in
[README](https://github.com/sciruby/gnuplotrb#installation) too.
* iRuby installation is covered in its [README](https://github.com/SciRuby/iruby/blob/master/README.md). It also covers installation of iPython and other dependecies.
* GnuplotRB gem installation covered in [README](https://github.com/sciruby/gnuplotrb#installation) too.


#### Embedding plots into iRuby
Using GnuplotRB inside iRuby notebooks is covered in:

* [Basic usage
notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master
/notebooks/basic_usage.ipynb).

* [Basic usage notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/basic_usage.ipynb).

#### 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](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/maste
r/notebooks/heatmaps.ipynb)
* [Vector
field](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/no
tebooks/vector_field.ipynb) (Thanks, [Alexej](https://github.com/agisga))
* [Math
equations](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/maste
r/notebooks/math_plots.ipynb)
* [3D
visualizations](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/
master/notebooks/3d_plot.ipynb)
* [Histogram](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/mast
er/notebooks/histogram.ipynb)
* [Heatmaps](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/heatmaps.ipynb)
* [Vectorfield](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/vector_field.ipynb) (Thanks, [Alexej](https://github.com/agisga))
* [Math equations](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/math_plots.ipynb)
* [3D visualizations](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/3d_plot.ipynb)
* [Histogram](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/histogram.ipynb)


#### Possible datasources
GnuplotRB may take data in Ruby container or in a file. Supported containers
for now are Arrays, Daru::Vector and Daru::DataFrame. When data given in file,
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](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/no
tebooks/points_from_different_sources.ipynb)
* [Data given in Daru
containers](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/mast
er/notebooks/plotting_from_daru.ipynb)
* [Data given in Daru containers (with
timeseries)](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/mas
ter/notebooks/time_series_from_daru.ipynb)
* [Updating plots with new
data](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/not
ebooks/updating_data.ipynb)
* [Data given in file or Ruby Array](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/points_from_different_sources.ipynb)
* [Data given in Daru containers](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/plotting_from_daru.ipynb)
* [Data given in Daru containers (with timeseries)](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/time_series_from_daru.ipynb)
* [Updating plots with new data](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/updating_data.ipynb)


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

* [Multiplot example
notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master
/notebooks/multiplot_layout.ipynb).

* [Multiplot example notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/multiplot_layout.ipynb).

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

* [Animation example
notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master
/notebooks/animated_plots.ipynb).
* [Animation example notebook](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/animated_plots.ipynb).


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

* [Fitting
data](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/not
ebooks/fitting_data.ipynb)
* [Fitting data](http://nbviewer.ipython.org/github/sciruby/gnuplotrb/blob/master/notebooks/fitting_data.ipynb)


### Plain examples
You may find several examples in [examples
directory](https://github.com/sciruby/gnuplotrb/tree/master/examples).
You may find several examples in [examples directory](https://github.com/sciruby/gnuplotrb/tree/master/examples).

## Contributing

Expand Down

0 comments on commit 1972a3a

Please sign in to comment.