Permalink
Browse files

initial import, thank you to the original author!

  • Loading branch information...
1 parent 0d13710 commit 239c570632147dd517874cb193c5282536ee162a @rdp committed Jul 8, 2009
Showing with 862 additions and 0 deletions.
  1. +3 −0 AUTHORS.txt
  2. +25 −0 ChangeLog
  3. +27 −0 LICENSE.txt
  4. +12 −0 README
  5. +2 −0 extconf.rb
  6. +24 −0 gnuplot.gemspec
  7. +295 −0 howto.html
  8. +283 −0 lib/gnuplot.rb
  9. +21 −0 test/arrtest.rb
  10. +31 −0 test/multtest.rb
  11. +19 −0 test/sinwave.rb
  12. +120 −0 test/test_gnuplot.rb
View
@@ -0,0 +1,3 @@
+Gordon James Miller
+Ara T. Howard
+
View
@@ -0,0 +1,25 @@
+Version 2.2 14-Nov-2005
+
+* Formally added the LICENSE.txt file. It is the new BSD license as defined
+ by opensource.org. See that file for details.
+
+* Added Gnuplot.which to try and fix the recurring problem of windows users
+ having to hack code to get things working.
+
+* Added the Gnuplot.gnuplot function so that I can unit test the finding
+ gnuplot executable routine.
+
+* In the Array.to_gplot method the terminating e is added to the output. This
+ is in response to Bug #2209.
+
+Version 2.1 17-Nov-2004
+
+* Array.to_gplot and Array.to_gsplot now support passing in arrays of
+ arbitrary objects. This is in response to a request by Yoshiki Tsunesada
+ (Tracker ID 1063)
+
+Version 2.0 10-Nov-2004
+
+* The 2.0 version of the gnuplot interface is a cross between the original,
+ object oriented version, and the version 1.0 which was simply a string
+ manipulation library.
View
@@ -0,0 +1,27 @@
+Copyright (c) 2004-2005, Gordon James Miller (gmiller@bittwiddlers.com)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ * Neither the name of the BitTwiddlers, Inc. nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
View
@@ -0,0 +1,12 @@
+To install as a rubygem you must have a recent version of rubygems (> 0.8)
+
+ruby gnuplot.gemspec
+gem install gnuplot-<version>.gem
+
+
+To install ruby in the traditional way
+
+ruby extconf.rb
+make install
+
+See the howto.html for details on how to setup the module and generate plots.
View
@@ -0,0 +1,2 @@
+require 'mkmf'
+create_makefile 'gnuplot'
View
@@ -0,0 +1,24 @@
+# -*- ruby -*-
+
+require 'rubygems'
+
+spec = Gem::Specification.new do |s|
+ s.name = 'gnuplot'
+ s.summary = "Utility library to aid in interacting with gnuplot"
+ s.version = "2.2"
+ s.platform = Gem::Platform::RUBY
+ s.date = Time.new
+
+ s.files = [ "lib/gnuplot.rb" ]
+
+ s.autorequire = 'gnuplot.rb'
+ s.author = "Gordon James Miller, Roger Pack"
+ s.email = "rogerpack2005@gmail.com"
+ s.homepage = "http://github.com/rogerdpack/ruby_gnuplot/tree/master"
+end
+
+if $0==__FILE__
+ Gem.manage_gems
+ Gem::Builder.new(spec).build
+end
+spec
View
@@ -0,0 +1,295 @@
+<html>
+ <head>
+ <title> Ruby Gnuplot - How To </title>
+ <style TYPE="text/css">
+ BODY { background: lightyellow; foreground: black; link: #000099;
+ vlink: #000066 }
+
+ H1 { color: green; text-align: center }
+ H2 { color: green; text-align: left }
+ H3 { color: green; text-align: left }
+ </style>
+ </head>
+
+ <body>
+ <h1> Ruby Gnuplot - How To </h1>
+
+ <p align="center">
+ [<a href="http://rubyforge.org/projects/rgplot">Rubyforge Project
+ page</a>]
+ [<a href="ChangeLog">ChangeLog</a>]
+ [<a href="AUTHORS.txt">Authors</a>]
+ [<a href="LICENSE.txt">License</a>]
+ </p>
+
+ <h2> History and Background </h2>
+
+ <p>
+ Gnuplot is a program that has a rich language for the generation of
+ plots. It has a unique place in academia as it was one of the first
+ freely available programs for plot generation. I started using gnuplot
+ over 10 years ago while pursuing my Master's degree in Physics and have
+ been using it actively ever since.
+ </p>
+
+ <h3>Version 0.9 </h3>
+ <blockquote>
+ My first attempt at a Ruby interface to gnuplot was an object interface
+ encapsulating gnuplot language. This was taken directly from the Python
+ gnuplot interface. In spite of my being very familiar with Gnuplot and
+ Ruby and being the author of the RGnuplot package, I found it
+ non-intuitive to use the RGnuplot package. I found myself constantly
+ looking at the code to figure out what I needed to do.
+
+ This was not sufficient and did not sit well.
+ </blockquote>
+
+ <h3>Version 1.0</h3>
+ <blockquote>
+ The second attempt at a Ruby interface was to do absolutely nothing but
+ use Ruby's built in string manipulation methods. This meant that I
+ could simply use my knowledge of Gnuplot without having to worry about
+ objects.
+
+ While in some ways an improvement over Version 0.9, it still did not sit
+ well with me.
+ </blockquote>
+
+ <h3> Version 2.0 </h3>
+ <blockquote>
+ After attending RubyConf 2004 I was inspired by Rich Kilmer's use of
+ Ruby to implement domain specific languages. That is the current
+ implementation of Gnuplot and quite probably the one that I'll stick
+ with for some time. This version combines the direct mapping of the
+ gnuplot language without wrapping with the ruby syntax and mechanism of
+ adding methods to existing classes to interface Ruby objects with
+ gnuplot.
+ </blockquote>
+
+ <h2>Setup </h2>
+
+ <h3>Version 2.2</h3>
+
+ <p> If the 'gnuplot' command is in your path then there is no required
+ setup. If the gnuplot executable for your system is called something other
+ than simply 'gnuplot' then set the RB_GNUPLOT environment variable to the
+ name of the executable. This must either be a full path to the gnuplot
+ command or an executable filename that exists in your PATH environment
+ variable.
+ </p>
+
+
+ <h2> Ruby Gnuplot Concepts </h2>
+
+ <p>
+ Gnuplot has a very simple conceptual model. Calls to <em>Set</em> are
+ made to set parameters and either <em>Plot</em> or <em>Splot</em> is
+ called to generate the actual plot. The <em>dataset</em> to be
+ plotted can be specified in a number of ways, contained in a seperate
+ file, generated from a function, read from standard input, or read
+ immediately after the plot command.
+ </p>
+
+ <p>
+ The object model for the Ruby gnuplot wrapper directly mimics this
+ layout and flow. The following are the standard steps for generating a
+ plot:
+ </p>
+
+ <ol>
+ <li> <p> Instantiate a Plot or Splot object and set parameters by gnuplot
+ variable name.</p> </li>
+
+ <li> <p>Instantiate DataSet objects and attach Ruby objects containing
+ the data to be plotted to the DataSet. Attach properties that modify
+ the plot command using the modifier name.</p>
+ </li>
+
+ <li> <p>Send the Plot/Splot object to a Gnuplot instance for
+ plotting.</p> </li>
+ </ol>
+
+ <p>
+ The Version 2.0 interface makes very heavy use of blocks leading to very
+ readable code.
+ </p>
+
+ <p>Gnuplot.open </p>
+ <blockquote>
+ Instantiates a new Gnuplot process. The path to the executable is
+ determined on a Unix or MacOSX system using the which command. Windows
+ users, I have no idea what to do.
+
+ If a block is given to the function the opened process is passed into
+ the block. This mimics the most common usage of the File.open method.
+ </blockquote>
+
+ <p>Plot.new </p>
+ <p>SPlot.new </p>
+ <blockquote>
+ Create a new Plot or Splot object. DataSets are attached to the object
+ to specify the data and its properties.
+
+ If a block is given to the function, the plot object is passed into the
+ block.
+ </blockquote>
+
+ <p>DataSet.new</p>
+ <blockquote>
+ Associates a Ruby object containing the data to plot with the properties
+ that will be passed to the plot command for that dataset. Any Ruby
+ object can be associated with a DataSet as long as it understands the
+ to_gplot method.
+ </blockquote>
+
+ <p> to_gplot </p>
+ <blockquote>
+ Within Gnuplot, plot data is read in very simple formats. The
+ to_gplot method is expected to write the data of the object in a format
+ that is understandable by Gnuplot. One of the many great things about
+ Ruby is that methods can be added after the original declaration. The
+ gnuplot module defines the to_gplot method on the following classes:
+
+ Array, String, and Matrix.
+
+ Simply define a to_gplot method on your own class to tie the class into
+ gnuplot.
+ </blockquote>
+
+ <h2> Examples </h2>
+
+ <h3> Simple sin wave </h3>
+
+ <p> The following example simply plots the value of sin(x) between the
+ ranges of -10 and 10. A few points to notice:
+ </p>
+
+ <ul>
+ <li><p> The code uses nested blocks to construct the plot. The newly
+ created object is passed to the block so it can be modified in
+ place.
+ </p>
+ </li>
+
+ <li><p> Each of the gnuplot plot variables are modified using the
+ variable name as a method name on the plot object or on the dataset
+ object. The wrapper also takes care of the single quoting that is
+ required on some of the variables like title, ylabel, and xlabel.
+ </p>
+ </li>
+
+ <li><p> The plot object simply has an array of DataSets. The
+ constructor initializes this empty array before yielding to the
+ block. This method uses the &lt;&lt; operator to add the DataSet to
+ the plot.
+ </p>
+ </li>
+
+ <li><p> When the plot block ends, if an IO object is given to the Plot
+ constructor, the plot commands will be written to the IO object.
+ Any object can be passed to the constructor as long as it
+ understands the &lt;&lt; operator.
+ </p>
+ </li>
+ </ul>
+
+ <pre class='code'>
+Gnuplot.open do |gp|
+ Gnuplot::Plot.new( gp ) do |plot|
+
+ plot.xrange "[-10:10]"
+ plot.title "Sin Wave Example"
+ plot.ylabel "x"
+ plot.xlabel "sin(x)"
+
+ plot.data << Gnuplot::DataSet.new( "sin(x)" ) do |ds|
+ ds.with = "lines"
+ ds.linewidth = 4
+ end
+
+ end
+
+end
+ </pre>
+
+ <h3> Plotting discrete points </h3>
+
+ <p>
+ Array data can be plotted quite easily since Arrays have a defined
+ to_gplot method.
+ </p>
+
+ <ul>
+ <li><p>Simply pass an array of data to the constructor of the DataSet
+ object or set the data property of the DataSet. In this example,
+ because there are two arrays, each array will be a single column of
+ data to the gnuplot process.
+ </p>
+ </li>
+ </ul>
+
+ <pre class='code'>
+Gnuplot.open do |gp|
+ Gnuplot::Plot.new( gp ) do |plot|
+
+ plot.title "Array Plot Example"
+ plot.ylabel "x"
+ plot.xlabel "x^2"
+
+ x = (0..50).collect { |v| v.to_f }
+ y = x.collect { |v| v ** 2 }
+
+ plot.data << Gnuplot::DataSet.new( [x, y] ) do |ds|
+ ds.with = "linespoints"
+ ds.notitle
+ end
+ end
+end
+ </pre>
+
+ <h3> Multiple Data Sets </h3>
+
+ <p> As many data sets as are desired can be attached to a plot. Each of
+ these can have their own plot modifiers. Notice in this example how the
+ data array is explicitly set instead of using the &lt;&lt; operator.
+ </p>
+
+ <p> Also in this example, the commands are not written to the Gnuplot
+ process but are instead written to a File called gnuplot.dat. This file
+ can later be run directly by a gnuplot process as it contains only the
+ gnuplot commands.
+ </p>
+
+ <pre class='code'>
+File.open( "gnuplot.dat", "w") do |gp|
+ Gnuplot::Plot.new( gp ) do |plot|
+
+ plot.xrange "[-10:10]"
+ plot.title "Sin Wave Example"
+ plot.ylabel "x"
+ plot.xlabel "sin(x)"
+
+ x = (0..50).collect { |v| v.to_f }
+ y = x.collect { |v| v ** 2 }
+
+ plot.data = [
+ Gnuplot::DataSet.new( "sin(x)" ) { |ds|
+ ds.with = "lines"
+ ds.title = "String function"
+ ds.linewidth = 4
+ },
+
+ Gnuplot::DataSet.new( [x, y] ) { |ds|
+ ds.with = "linespoints"
+ ds.title = "Array data"
+ }
+ ]
+
+ end
+
+end
+
+ </pre>
+
+ </body>
+</html>
Oops, something went wrong.

0 comments on commit 239c570

Please sign in to comment.