gnuplotrb 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 636e6f8b249ca52a3dc09d4034cb7596ba650e42
-  data.tar.gz: d8eea39c386a7cc6513b2992b126fc15412318f4
+  metadata.gz: cec6373d3af74267f75b7e627201944401affe70
+  data.tar.gz: cc9e9d26c4ab999b708b797a4feb2d6d643705d9
 SHA512:
-  metadata.gz: 2d331f099e12185d350a4b1fe6908a658cfdcc977c3d4657bd621efe510fb854fe1a86fdd780b8f32e1ea69146934e513e8b1de16ead04e8a43c11da093d23eb
-  data.tar.gz: 26c483e4a645ac3b2ef9a680ba8a30cc3975fd68f0ad329e3cf22fae53a26cec5fd8b8743bd57850025c351bae77988dccf40d436c3f49b7a4c8c4344b222e4d
+  metadata.gz: 13b66a6ebf312632d79e5f6ab3578fb00e7fa02060855f04ca8c24c680766146bfef1c8f7be038f601e8064e3d1e361b80e727605be6386ed112554e73ff57f1
+  data.tar.gz: 663aee900352e69d581a0fa2830b878441de4a81515d1901b252c647a96eff64c36b166f66326368747d72947d004a8ea18d6a1ccd3130b8c349c2ff242506bd

data/README.rdoc

@@ -2,17 +2,20 @@
 
 GnuplotRB is a plot generator for Ruby based on {Gnuplot}[http://www.gnuplot.info].
 
-This software has been developed as a product in Google Summer of Code 2015 (GSoC2015). Its progress may be saw in {SciRuby mailing list}[https://groups.google.com/forum/?fromgroups#!topic/sciruby-dev/lhWvb5hWc3k] or in {project's blog}[http://dilcom.github.io/gnuplotrb/]. 
+This software has been developed as a product in Google Summer of Code 2015 (GSoC2015). Its progress may be saw in {SciRuby mailing list}[https://groups.google.com/forum/?fromgroups#!topic/sciruby-dev/lhWvb5hWc3k] or in {project's blog}[http://www.evgrafov.work/gnuplotrb/].
 
 {<img src="https://badge.fury.io/rb/gnuplotrb.svg" alt="Gem Version" />}[https://rubygems.org/gems/gnuplotrb]
 
+{<img src="https://gemnasium.com/dilcom/gnuplotrb.svg" alt="Dependency Status" />}[https://gemnasium.com/dilcom/gnuplotrb]
+
 {<img src="https://travis-ci.org/dilcom/gnuplotrb.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/dilcom/gnuplotrb]
 {<img src="https://codeclimate.com/github/dilcom/gnuplotrb/badges/gpa.svg" alt="Code quality" />}[https://codeclimate.com/github/dilcom/gnuplotrb]
 {<img src="https://codeclimate.com/github/dilcom/gnuplotrb/badges/coverage.svg" alt="Test coverage" />}[https://codeclimate.com/github/dilcom/gnuplotrb]
 
 == Table of contents
 * {Installation}[https://github.com/dilcom/gnuplotrb#installation]
-* {Examples}[https://github.com/dilcom/gnuplotrb#examples]
+* {Getting started}[https://github.com/dilcom/gnuplotrb#getting-started]
+  * {Plottable classes}[https://github.com/dilcom/gnuplotrb#plottable-classes]
   * {Notebooks}[https://github.com/dilcom/gnuplotrb#notebooks]
   * {Plain examples}[https://github.com/dilcom/gnuplotrb#plain-examples]
 * {Contributing}[https://github.com/dilcom/gnuplotrb#contributing]
@@ -36,7 +39,67 @@ This software has been developed as a product in Google Summer of Code 2015 (GSo
   bundle install
   rake install
 
-== Examples
+== 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/dilcom/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/dilcom/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')
+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/dilcom/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/dilcom/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)
+
+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.
+
+==== 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 file\window) 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}[http://nbviewer.ipython.org/github/dilcom/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/dilcom/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/].

data/Rakefile

@@ -1,7 +1,7 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rspec/core'
-require 'rdoc/task'
+require 'yard'
 require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec) do |spec|
@@ -9,9 +9,8 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.rspec_opts = '--format documentation'
 end
 
-RDoc::Task.new(:doc) do |rdoc|
-  rdoc.main = 'README.rdoc'
-  rdoc.rdoc_files.include %w(README.rdoc lib)
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files   = %w(README.rdoc lib)   # optional
 end
 
 RuboCop::RakeTask.new(:cop)

data/gnuplotrb.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.2'
-  spec.add_development_dependency 'rdoc', '~> 4.2'
+  spec.add_development_dependency 'yard', '~> 0.8'
   spec.add_development_dependency 'rubocop', '~> 0.29'
   spec.add_development_dependency 'codeclimate-test-reporter'
   spec.add_development_dependency 'chunky_png'

data/lib/gnuplotrb.rb

@@ -3,6 +3,11 @@ require 'hamster'
 require 'open3'
 require 'base64'
 
+##
+# Require gem if it's available in current gemspace.
+#
+# @param name [String] gem name
+# @return [Boolean] true if gem was loaded, false otherwise
 def require_if_available(name)
   require name
 rescue LoadError

data/lib/gnuplotrb/animation.rb

@@ -1,9 +1,29 @@
 module GnuplotRB
   ##
-  # === Overview
   # Animation allows to create gif animation with given plots
   # as frames. Possible frames: Plot, Splot, Multiplot.
-  # More about its usage in {animation notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/animated_plots.ipynb].
+  # More about its usage in
+  # {animation notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/animated_plots.ipynb].
+  #
+  # == Options
+  # Animations has several specific options:
+  # * animate - allows to get animated gif's. Possible values are true (just turn on animation),
+  #   ot hash with suboptions (:loop - count of loops, default 0 - infinity$; 
+  #   :delay - delay between frames; :optimize - boolean, reduces file size).
+  # * size - size of gif file in pixels (size: [500, 500]) or (size: 500)
+  # * background - background color
+  # * transparent
+  # * enhanced
+  # * font
+  # * fontscale
+  # * crop
+  #
+  # Animation ignores :term option and does not have methods like #to_png or #to_svg.
+  # One can also set animation any options related to Plot and they will be considered
+  # by all nested plots (if they does not override it with their own values).
+  #
+  # Animation inherits all plot array handling methods from Multiplot
+  # and adds aliases for them (#plots -> #frames; #update_frame! -> #update_plot!; etc).
   class Animation < Multiplot
     ##
     # *Plot* here is also named as *frame*
@@ -13,18 +33,25 @@ module GnuplotRB
     alias_method :add_frame, :add_plot
     alias_method :add_frames, :add_plots
     alias_method :remove_frame, :remove_plot
+    alias_method :update_frame!, :update_plot!
+    alias_method :replace_frame!, :replace_plot!
+    alias_method :add_frame!, :add_plot!
+    alias_method :add_frames!, :add_plots!
+    alias_method :remove_frame!, :remove_plot!
 
     ##
-    # ====== Overview
     # This method creates a gif animation where frames are plots
     # already contained by Animation object.
-    # ====== 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.
+    #
+    # Options passed in #plot have priority over those which were set before.
+    #
     # Inner options of Plots have the highest priority (except
     # :term and :output which are ignored).
+    #
+    # @param path [String] path to new gif file that will be created as a result
+    # @param options [Hash] see note about available options in top class documentation
+    # @return [nil] if path to output file given
+    # @return [String] gif file contents if no path to output file given
     def plot(path = nil, **options)
       options[:output] ||= path
       plot_options = mix_options(options) do |plot_opts, anim_opts|
@@ -46,7 +73,7 @@ module GnuplotRB
     end
 
     ##
-    # #to_<term_name> methods are not supported by animation
+    # #to_|term_name| methods are not supported by animation
     def to_specific_term(*_)
       fail 'Specific terminals are not supported by Animation'
     end

data/lib/gnuplotrb/external_classes/array.rb

@@ -2,6 +2,7 @@
 # Methods to take data for GnuplotRB plots.
 class Array
   # taken for example from current gnuplot bindings
+  # @return [String] array converted to Gnuplot format
   def to_gnuplot_points
     return '' if self.empty?
     case self[0]

data/lib/gnuplotrb/external_classes/daru.rb

@@ -6,6 +6,10 @@ if defined? Daru
     ##
     # Methods to take data for GnuplotRB plots.
     class DataFrame
+      ##
+      # Convert DataFrame to Gnuplot format.
+      #
+      # @return [String] data converted to Gnuplot format
       def to_gnuplot_points
         result = ''
         each_row_with_index do |row, index|
@@ -21,6 +25,10 @@ if defined? Daru
     ##
     # Methods to take data for GnuplotRB plots.
     class Vector
+      ##
+      # Convert Vector to Gnuplot format.
+      #
+      # @return [String] data converted to Gnuplot format
       def to_gnuplot_points
         result = ''
         each_with_index do |value, index|

data/lib/gnuplotrb/external_classes/string.rb

@@ -1,7 +1,6 @@
 ##
 # Methods to take data for GnuplotRB plots.
 class String
-  def to_gnuplot_points
-    clone
-  end
+  # @return [String] data converted to Gnuplot format
+  alias_method :to_gnuplot_points, :clone
 end

data/lib/gnuplotrb/fit.rb

@@ -1,176 +1,204 @@
 module GnuplotRB
   ##
-  # ====== Overview
-  # Fit given data with function. Covered in {fit notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/fitting_data.ipynb].
-  # ====== Arguments
-  # * *data* - method accepts the same sources as Dataset.new
-  #   and Dataset object
-  # * *:function* - function to fit data with. Default 'a2*x*x+a1*x+a0'
-  # * *:initials* - initial values for coefficients used in fitting.
-  #   Default: {a2: 1, a1: 1, a0: 1}
-  # * *:via* - coefficients that Gnuplot should change during fitting.
-  #   Default: initials#keys
-  # * *:term_options* - terminal options that should be setted to terminal before fit.
-  #   For example *xrange*, *yrange* etc
-  # * *options* - options passed to Gnuplot's fit such as *using*
-  # ====== Return value
-  # Fit returns hash of 4 elements:
-  # * *:formula_ds* - dataset with best fit curve as data
-  # * *:coefficients* - hash of calculated coefficients. So if you gave {via: [:a, :b, :c]} or
-  #   {initials: {a: 1, b: 1, c: 1} } it will return hash with keys :a, :b, :c and its values
-  # * *:deltas* - Gnuplot calculates possible deltas for coefficients during fitting and
-  #   *deltas* hash contains this deltas
-  # * *:data* - pointer to Datablock with given data
-  # ====== Examples
-  #   fit(some_data, function: 'exp(a/x)', initials: {a: 10}, term_option: { xrange: 1..100 })
-  #   fit(some_dataset, using: '1:2:3')
-  def fit(data, function: 'a2*x*x+a1*x+a0', initials: { a2: 1, a1: 1, a0: 1 }, term_options: {}, **options)
-    dataset = data.is_a?(Dataset) ? Dataset.new(data.data) : Dataset.new(data)
-    opts_str = OptionHandling.ruby_class_to_gnuplot(options)
-    output = gnuplot_fit(function, dataset, opts_str, initials, term_options)
-    res = parse_output(initials.keys, function, output)
-    {
-      formula_ds: Dataset.new(res[2], title: 'Fit formula'),
-      coefficients: res[0],
-      deltas: res[1],
-      data: dataset
-    }
-  end
-
-  ##
-  # ====== Overview
-  # Shortcut for fit with polynomial. Degree here is max power of *x* in polynomial.
-  # ====== Arguments
-  # * *data* - method accepts the same sources as Dataset.new and Dataset object
-  # * *:degree* - degree of polynomial
-  # * *options* - all of this options will be passed to *#fit* so you
-  #   can set here any *term_options*. If you pass here *:initials* hash, it
-  #   will be merged into default initals hash (all values are 1).
-  # ====== Return value
-  # See the same section for #fit.
-  # ====== Examples
-  #   fit_poly(some_data, degree: 5, initials: { a4: 10, a2: -1 }, term_option: { xrange: 1..100 })
-  #   #=> The same as:
-  #   #=> fit(
-  #   #=>   some_data,
-  #   #=>   function: 'a5*x**5 + a4*x**4 + ... + a0*x**0',
-  #   #=>   initals: {a5: 1, a4: 10, a3: 1, a2: -1, a1: 1, a0: 1},
-  #   #=>   term_option: { xrange: 1..100 }
-  #   #=> )
-  def fit_poly(data, degree: 2, **options)
-    sum_count = degree + 1
-    initials = {}
-    sum_count.times { |i| initials["a#{i}".to_sym] = 1 }
-    options[:initials] = initials.merge(options[:initials] || {})
-    function = sum_count.times.map { |i| "a#{i}*x**#{i}" }.join(' + ')
-    fit(data, **options, function: function)
-  end
-
-  ##
-  # :method: fit_<function>
-  # :call-seq:
-  # fit_exp(data, **options) -> Hash
-  # fit_log(data, **options) -> Hash
-  # fit_sin(data, **options) -> Hash
+  # Contains methods relating to Gnuplot's fit function. Covered in
+  # {fit notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/fitting_data.ipynb].
   #
-  # ====== Overview
-  # Shortcuts for fitting with several math functions (exp, log, sin).
-  # ====== Arguments
-  # * *data* - method accepts the same sources as Dataset.new and Dataset object
-  # * *options* - all of this options will be passed to *#fit* so you
-  #   can set here any *term_options*. If you pass here *:initials* hash, it
-  #   will be merged into default initals hash { yoffset: 0.1, xoffset: 0.1, yscale: 1, xscale: 1 }
-  # ====== Return value
-  # See the same section for #fit.
-  # ====== Examples
-  #   fit_exp(some_data, initials: { yoffset: -11 }, term_option: { xrange: 1..100 })
-  #   #=> The same as:
-  #   #=> fit(
-  #   #=>   some_data,
-  #   #=>   function: 'yscale * (yoffset + exp((x - xoffset) / xscale))',
-  #   #=>   initals: { yoffset: -11, xoffset: 0.1, yscale: 1, xscale: 1 },
-  #   #=>   term_option: { xrange: 1..100 }
-  #   #=> )
-  #   fit_log(...)
-  #   fit_sin(...)
-  %w(exp log sin).map do |fname|
-    define_method("fit_#{fname}".to_sym) do |data, **options|
-      options[:initials] = {
-        yoffset: 0.1,
-        xoffset: 0.1,
-        yscale: 1,
-        xscale: 1
-      }.merge(options[:initials] || {})
-      function = "yscale * (yoffset + #{fname} ((x - xoffset) / xscale))"
-      fit(data, **options, function: function)
+  # You can also see original gnuplot's fit in
+  # {gnuplot doc}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf] p. 122.
+  module Fit
+    ##
+    # Fit given data with function.
+    #
+    # Fit waits for output from gnuplot Settings.max_fit_delay and throw exception if gets nothing.
+    # One can change this value in order to wait longer (if huge datasets is fitted).
+    #
+    # @param data [#to_gnuplot_points] method accepts the same sources as Dataset.new
+    #   and Dataset object
+    # @param :function [String] function to fit data with
+    # @param :initials [Hash] initial values for coefficients used in fitting
+    # @param :term_options [Hash] terminal options that should be setted to terminal before fit.
+    #   You can see them in Plot's documentation (or even better in gnuplot doc)
+    #   Most useful here are ranges (xrange, yrange etc) and fit option which tunes fit parameters
+    #   (see {gnuplot doc}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf] p. 122)
+    # @param options [Hash] options passed to Gnuplot's fit such as *using*. They are covered in
+    #   {gnuplot doc}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf] (pp. 69-74)
+    #
+    # @return [Hash] hash with four elements:
+    #   - :formula_ds - dataset with best fit curve as data
+    #   - :coefficients - hash of calculated coefficients. So if you gave
+    #     ``{ initials: {a: 1, b: 1, c: 1} }`` it will return hash with keys :a, :b, :c and its values
+    #   - :deltas - Gnuplot calculates possible deltas for coefficients during fitting and
+    #     deltas hash contains this deltas
+    #   - :data - pointer to Datablock with given data
+    # @example
+    #   fit(some_data, function: 'exp(a/x)', initials: {a: 10}, term_option: { xrange: 1..100 })
+    #   fit(some_dataset, using: '1:2:3')
+    def fit(data, function: 'a2*x*x+a1*x+a0', initials: { a2: 1, a1: 1, a0: 1 }, term_options: {}, **options)
+      dataset = data.is_a?(Dataset) ? Dataset.new(data.data) : Dataset.new(data)
+      opts_str = OptionHandling.ruby_class_to_gnuplot(options)
+      output = gnuplot_fit(function, dataset, opts_str, initials, term_options)
+      res = parse_output(initials.keys, function, output)
+      {
+        formula_ds: Dataset.new(res[2], title: 'Fit formula'),
+        coefficients: res[0],
+        deltas: res[1],
+        data: dataset
+      }
     end
-  end
 
-  private
+    ##
+    # Shortcut for fit with polynomial. Degree here is max power of *x* in polynomial.
+    #
+    # @param data [#to_gnuplot_points] method accepts the same sources as Dataset.new
+    #   and Dataset object
+    # @param :degree [Integer] degree of polynomial
+    # @param options [Hash] all of this options will be passed to #fit so you
+    #   can set here any options listed in its docs. If you pass here :initials hash, it
+    #   will be merged into default initals hash. Formula by default is
+    #   "xn*x**n + ... + x0*x**0", initials by default "{ an: 1, ..., a0: 1 }"
+    #
+    # @return [Hash] hash with four elements:
+    #   - :formula_ds - dataset with best fit curve as data
+    #   - :coefficients - hash of calculated coefficients. So for degree = 3
+    #     it will return hash with keys :a3, :a2, :a1, :a0 and calculated values
+    #   - :deltas - Gnuplot calculates possible deltas for coefficients during fitting and
+    #     deltas hash contains this deltas
+    #   - :data - pointer to Datablock with given data
+    # @example
+    #   fit_poly(some_data, degree: 5, initials: { a4: 10, a2: -1 }, term_option: { xrange: 1..100 })
+    #   #=> The same as:
+    #   #=> fit(
+    #   #=>   some_data,
+    #   #=>   function: 'a5*x**5 + a4*x**4 + ... + a0*x**0',
+    #   #=>   initals: {a5: 1, a4: 10, a3: 1, a2: -1, a1: 1, a0: 1},
+    #   #=>   term_option: { xrange: 1..100 }
+    #   #=> )
+    def fit_poly(data, degree: 2, **options)
+      sum_count = degree + 1
+      initials = {}
+      sum_count.times { |i| initials["a#{i}".to_sym] = 1 }
+      options[:initials] = initials.merge(options[:initials] || {})
+      function = sum_count.times.map { |i| "a#{i}*x**#{i}" }.join(' + ')
+      fit(data, **options, function: function)
+    end
 
-  ##
-  # It takes some time to produce output so here we need
-  # to wait for it.
-  def wait_for_output(term, variables)
-    # now we should catch 'error' from terminal: it will contain approximation data
-    # but we can get a real error instead of output, so lets wait for limited time
-    start = Time.now
-    output = ''
-    until output_ready?(output, variables)
-      begin
-        term.check_errors
-      rescue GnuplotRB::GnuplotError => e
-        output += e.message
+    ##
+    # @!method fit_exp(data, **options)
+    # @!method fit_log(data, **options)
+    # @!method fit_sin(data, **options)
+    #
+    # Shortcuts for fitting with several math functions (exp, log, sin).
+    #
+    # @param data [#to_gnuplot_points] method accepts the same sources as Dataset.new
+    #   and Dataset object
+    # @param options [Hash] all of this options will be passed to #fit so you
+    #   can set here any options listed in its docs. If you pass here :initials hash, it
+    #   will be merged into default initals hash. Formula by default is
+    #   "yscale * (yoffset + #{function name}((x - xoffset) / xscale))", initials by default
+    #   "{ yoffset: 0.1, xoffset: 0.1, yscale: 1, xscale: 1 }"
+    #
+    # @return [Hash] hash with four elements:
+    #   - :formula_ds - dataset with best fit curve as data
+    #   - :coefficients - hash of calculated coefficients. So for this case
+    #     it will return hash with keys :yoffset, :xoffset, :yscale, :xscale and calculated values
+    #   - :deltas - Gnuplot calculates possible deltas for coefficients during fitting and
+    #     deltas hash contains this deltas
+    #   - :data - pointer to Datablock with given data
+    #
+    # @example
+    #   fit_exp(some_data, initials: { yoffset: -11 }, term_option: { xrange: 1..100 })
+    #   #=> The same as:
+    #   #=> fit(
+    #   #=>   some_data,
+    #   #=>   function: 'yscale * (yoffset + exp((x - xoffset) / xscale))',
+    #   #=>   initals: { yoffset: -11, xoffset: 0.1, yscale: 1, xscale: 1 },
+    #   #=>   term_option: { xrange: 1..100 }
+    #   #=> )
+    #   fit_log(...)
+    #   fit_sin(...)
+    %w(exp log sin).map do |fname|
+      define_method("fit_#{fname}".to_sym) do |data, **options|
+        options[:initials] = {
+          yoffset: 0.1,
+          xoffset: 0.1,
+          yscale: 1,
+          xscale: 1
+        }.merge(options[:initials] || {})
+        function = "yscale * (yoffset + #{fname} ((x - xoffset) / xscale))"
+        fit(data, **options, function: function)
       end
-      if Time.now - start > Settings.max_fit_delay
-        fail GnuplotError, "Seems like there is an error in gnuplotrb: #{output}"
+    end
+
+    private
+
+    ##
+    # It takes some time to produce output so here we need
+    # to wait for it.
+    #
+    # Max time to wait is stored in Settings.max_fit_delay, so one
+    # can change it in order to wait longer.
+    def wait_for_output(term, variables)
+      # now we should catch 'error' from terminal: it will contain approximation data
+      # but we can get a real error instead of output, so lets wait for limited time
+      start = Time.now
+      output = ''
+      until output_ready?(output, variables)
+        begin
+          term.check_errors(raw: true)
+        rescue GnuplotRB::GnuplotError => e
+          output += e.message
+        end
+        if Time.now - start > Settings.max_fit_delay
+          fail GnuplotError, "Seems like there is an error in gnuplotrb: #{output}"
+        end
       end
+      output
     end
-    output
-  end
 
-  ##
-  # Check if current output contains all the
-  # variables given to fit.
-  def output_ready?(output, variables)
-    output =~ /Final set .*#{variables.join('.*')}/
-  end
+    ##
+    # Check if current output contains all the
+    # variables given to fit.
+    def output_ready?(output, variables)
+      output =~ /Final set .*#{variables.join('.*')}/
+    end
 
-  ##
-  # Parse Gnuplot's output to get coefficients and their deltas
-  # from it. Also replaces coefficients in given function with
-  # exact values.
-  def parse_output(variables, function, output)
-    plottable_function = " #{function.clone} "
-    coefficients = {}
-    deltas = {}
-    variables.each do |var|
-      value, error = output.scan(%r{#{var} *= ([^ ]+) *\+/\- ([^ ]+)})[0]
-      plottable_function.gsub!(/#{var}([^0-9a-zA-Z])/) { value + Regexp.last_match(1) }
-      coefficients[var] = value.to_f
-      deltas[var] = error.to_f
+    ##
+    # Parse Gnuplot's output to get coefficients and their deltas
+    # from it. Also replaces coefficients in given function with
+    # exact values.
+    def parse_output(variables, function, output)
+      plottable_function = " #{function.clone} "
+      coefficients = {}
+      deltas = {}
+      variables.each do |var|
+        value, error = output.scan(%r{#{var} *= ([^ ]+) *\+/\- ([^ ]+)})[0]
+        plottable_function.gsub!(/#{var}([^0-9a-zA-Z])/) { value + Regexp.last_match(1) }
+        coefficients[var] = value.to_f
+        deltas[var] = error.to_f
+      end
+      [coefficients, deltas, plottable_function]
     end
-    [coefficients, deltas, plottable_function]
-  end
 
-  ##
-  # Make fit command and send it to gnuplot
-  def gnuplot_fit(function, data, options, initials, term_options)
-    variables = initials.keys
-    term = Terminal.new
-    term.set(term_options)
-    initials.each { |var_name, value| term.stream_puts "#{var_name} = #{value}" }
-    command = "fit #{function} #{data.to_s(term)} #{options} via #{variables.join(',')}"
-    term.stream_puts(command)
-    output = wait_for_output(term, variables)
-    begin
-      term.close
-    rescue GnuplotError
-      # Nothing interesting here.
-      # If we had an error, we never reach this line.
-      # Error here may be only additional information
-      # such as correlation matrix.
+    ##
+    # Make fit command and send it to gnuplot
+    def gnuplot_fit(function, data, options, initials, term_options)
+      variables = initials.keys
+      term = Terminal.new
+      term.set(term_options)
+      initials.each { |var_name, value| term.stream_puts "#{var_name} = #{value}" }
+      command = "fit #{function} #{data.to_s(term, without_options: true)} " \
+                "#{options} via #{variables.join(',')}"
+      term.stream_puts(command)
+      output = wait_for_output(term, variables)
+      begin
+        term.close
+      rescue GnuplotError
+        # Nothing interesting here.
+        # If we had an error, we never reach this line.
+        # Error here may be only additional information
+        # such as correlation matrix.
+      end
+      output
     end
-    output
   end
 end