bplot 0.0.1 → 0.0.2b

data/ChangeLog

@@ -0,0 +1,54 @@
+=== Version 0.0.2
+
+* New plot API: The new API is incompatible with the old one, but it is
+  a major improvement. Now there are two ways to define plot styles:
+
+  * The syntax string method is more compact than the previous API.
+
+  * The named parameters are less compact but have an easier learning
+    curve than the previous API.
+
+
+* Moved documentation to rdoc.
+
+* Replaced the examples in the README with a full fleged Tutorial.
+
+* Started a ChangeLog and a Roadmap file.
+
+* Bugfix: Parse "with" command more reliably.
+
+* Replaced the "replot" command with "refresh" which is more appropiate
+  for plotting data streams like BPLot does.
+
+* New command: show
+
+=== Version 0.0.1
+
+* Initial release of BPlot using Gnuplot as a backend plotting engine.
+
+[plot] Basic support for 2D plots. Includes setting the title and line
+       and point styles with Gnuplot and Matlab-like syntax:
+  
+         b = BPlot.new
+         b.plot( [1,2,3,4,5], [2,4,8,16,32], 'ps 2 lw 2', 'rh--', 'Exponential')
+         
+         b.plot(x, y, :title => 'Density', :gnuplot => 'lc 3 ps 1.5 lt 4 pt 5 w lp')
+         b.plot(x, y, :title => 'Density', :gnuplot => 'ps 1.5', :matlab => 'rh-')
+         b.plot(x, y, :t => 'Mass', :g => 'ps 2.5', :m => 'bh--')
+         
+         b.plot(x, y, 'ps 2', 'rh-', x, z, 'ps 1.5', 'bs--')
+         b.plot(x, y, 'ps 2', 'rh-', 'Quadratic', x, z, 'ps 1.5', 'bs--', 'Linear')
+
+
+[set] Support for plot settings via the Gnuplot 'set' command:
+
+         b.set('xrange [0:6]')
+         b.set('yrange [0:50]')
+
+[replot] Support for the Gnuplot 'replot' command:
+
+            b.replot
+
+[cmd] Support for sending raw instructions to the Gnuplot backend:
+
+         b.cmd('plot sin(x) tit "A plot without Ruby"')

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2012, Daniel Carrera <dcarrera@gmail.com>
+Copyright (C) 2012 Daniel Carrera <dcarrera@gmail.com>
 
 BPlot is free software; you can redistribute it and/or modify it under
 the terms of the Artistic License 2.0 (reproduced below) as published
@@ -7,15 +7,15 @@ by The Perl Foundation.
 http://www.perlfoundation.org/attachment/legal/artistic-2_0.txt
 
 
-		       The Artistic License 2.0
+= The Artistic License 2.0
 
-	    Copyright (c) 2000-2006, The Perl Foundation.
+Copyright (c) 2000-2006, The Perl Foundation.
 
-     Everyone is permitted to copy and distribute verbatim copies
-      of this license document, but changing it is not allowed.
-
-Preamble
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
 
+== Preamble
+ 
 This license establishes the terms under which a given free software
 Package may be copied, modified, distributed, and/or redistributed.
 The intent is that the Copyright Holder maintains some artistic
@@ -27,60 +27,60 @@ license directly with the Copyright Holder of a given Package.  If the
 terms of this license do not permit the full use that you propose to
 make of the Package, you should contact the Copyright Holder and seek
 a different licensing arrangement. 
+ 
+== Definitions
 
-Definitions
-
-    "Copyright Holder" means the individual(s) or organization(s)
+*   "Copyright Holder" means the individual(s) or organization(s)
     named in the copyright notice for the entire Package.
 
-    "Contributor" means any party that has contributed code or other
+*   "Contributor" means any party that has contributed code or other
     material to the Package, in accordance with the Copyright Holder's
     procedures.
 
-    "You" and "your" means any person who would like to copy,
+*   "You" and "your" means any person who would like to copy,
     distribute, or modify the Package.
 
-    "Package" means the collection of files distributed by the
+*   "Package" means the collection of files distributed by the
     Copyright Holder, and derivatives of that collection and/or of
     those files. A given Package may consist of either the Standard
     Version, or a Modified Version.
 
-    "Distribute" means providing a copy of the Package or making it
+*   "Distribute" means providing a copy of the Package or making it
     accessible to anyone else, or in the case of a company or
     organization, to others outside of your company or organization.
 
-    "Distributor Fee" means any fee that you charge for Distributing
+*   "Distributor Fee" means any fee that you charge for Distributing
     this Package or providing support for this Package to another
     party.  It does not mean licensing fees.
 
-    "Standard Version" refers to the Package if it has not been
+*   "Standard Version" refers to the Package if it has not been
     modified, or has been modified only in ways explicitly requested
     by the Copyright Holder.
 
-    "Modified Version" means the Package, if it has been changed, and
+*   "Modified Version" means the Package, if it has been changed, and
     such changes were not explicitly requested by the Copyright
     Holder. 
 
-    "Original License" means this Artistic License as Distributed with
+*   "Original License" means this Artistic License as Distributed with
     the Standard Version of the Package, in its current version or as
     it may be modified by The Perl Foundation in the future.
 
-    "Source" form means the source code, documentation source, and
+*   "Source" form means the source code, documentation source, and
     configuration files for the Package.
 
-    "Compiled" form means the compiled bytecode, object code, binary,
+*   "Compiled" form means the compiled bytecode, object code, binary,
     or any other form resulting from mechanical transformation or
     translation of the Source form.
 
 
-Permission for Use and Modification Without Distribution
+== Permission for Use and Modification Without Distribution
 
 (1)  You are permitted to use the Standard Version and create and use
 Modified Versions for any purpose without restriction, provided that
 you do not Distribute the Modified Version.
 
 
-Permissions for Redistribution of the Standard Version
+== Permissions for Redistribution of the Standard Version
 
 (2)  You may Distribute verbatim copies of the Source form of the
 Standard Version of this Package in any medium without restriction,
@@ -95,7 +95,7 @@ Package will still be considered the Standard Version, and as such
 will be subject to the Original License.
 
 
-Distribution of Modified Versions of the Package as Source 
+== Distribution of Modified Versions of the Package as Source 
 
 (4)  You may Distribute your Modified Version as Source (either gratis
 or for a Distributor Fee, and with or without a Compiled form of the
@@ -104,33 +104,32 @@ from the Standard Version, including, but not limited to, documenting
 any non-standard features, executables, or modules, and provided that
 you do at least ONE of the following:
 
-    (a)  make the Modified Version available to the Copyright Holder
-    of the Standard Version, under the Original License, so that the
-    Copyright Holder may include your modifications in the Standard
-    Version.
-
-    (b)  ensure that installation of your Modified Version does not
-    prevent the user installing or running the Standard Version. In
-    addition, the Modified Version must bear a name that is different
-    from the name of the Standard Version.
-
-    (c)  allow anyone who receives a copy of the Modified Version to
-    make the Source form of the Modified Version available to others
-    under
-		
-	(i)  the Original License or
-
-	(ii)  a license that permits the licensee to freely copy,
-	modify and redistribute the Modified Version using the same
-	licensing terms that apply to the copy that the licensee
-	received, and requires that the Source form of the Modified
-	Version, and of any works derived from it, be made freely
-	available in that license fees are prohibited but Distributor
-	Fees are allowed.
-
-
-Distribution of Compiled Forms of the Standard Version 
-or Modified Versions without the Source
+[a)]  make the Modified Version available to the Copyright Holder
+      of the Standard Version, under the Original License, so that the
+      Copyright Holder may include your modifications in the Standard
+      Version.
+
+[b)]  ensure that installation of your Modified Version does not
+      prevent the user installing or running the Standard Version. In
+      addition, the Modified Version must bear a name that is different
+      from the name of the Standard Version.
+
+[c)] allow anyone who receives a copy of the Modified Version to
+     make the Source form of the Modified Version available to others
+     under
+      
+     [(i)]   the Original License or
+      
+     [(ii)]  a license that permits the licensee to freely copy,
+             modify and redistribute the Modified Version using the same
+             licensing terms that apply to the copy that the licensee
+             received, and requires that the Source form of the Modified
+             Version, and of any works derived from it, be made freely
+             available in that license fees are prohibited but Distributor
+             Fees are allowed.
+
+
+== Distribution of Compiled Forms of the Standard Version or Modified Versions without the Source
 
 (5)  You may Distribute Compiled forms of the Standard Version without
 the Source, provided that you include complete instructions on how to
@@ -147,7 +146,7 @@ the Source, provided that you comply with Section 4 with respect to
 the Source of the Modified Version.
 
 
-Aggregating or Linking the Package 
+== Aggregating or Linking the Package 
 
 (7)  You may aggregate the Package (either the Standard Version or
 Modified Version) with other packages and Distribute the resulting
@@ -164,7 +163,7 @@ include the Package, and Distribute the result without restriction,
 provided the result does not expose a direct interface to the Package.
 
 
-Items That are Not Considered Part of a Modified Version 
+== Items That are Not Considered Part of a Modified Version 
 
 (9) Works (including, but not limited to, modules and scripts) that
 merely extend or make use of the Package, do not, by themselves, cause
@@ -173,7 +172,7 @@ considered parts of the Package itself, and are not subject to the
 terms of this license.
 
 
-General Provisions
+== General Provisions
 
 (10)  Any use, modification, and distribution of the Standard or
 Modified Versions is governed by this Artistic License. By using,
@@ -200,6 +199,7 @@ infringement, then this Artistic License to you shall terminate on the
 date that such litigation is filed.
 
 (14)  Disclaimer of Warranty:
+
 THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS
 IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED
 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR

data/README

@@ -1,6 +1,9 @@
-BPlot -- A ploting module for SciRuby. It provides an API
-         familiar to Gnuplot users and to a lesser extent
-         Matlab users.
+= BPlot
+
+BPlot is a 2D and 3D plotting module for SciRuby. It
+provides an API familiar to Gnuplot users and to a lesser
+extent Matlab users.
+
 
                  \     /
              \    o ^ o    /
@@ -15,8 +18,8 @@ BPlot -- A ploting module for SciRuby. It provides an API
                   (%%%)
                     !
 
-SUMMARY / STATUS
-----------------
+== SUMMARY / STATUS
+
 BPlot is in ALPHA status. Two dimmensional plots seem to work
 well but they really need more testing. Surface plots and some
 other features are not implemented yet.
@@ -31,72 +34,70 @@ no pre-requisites, as BPLot can work with either NMatrix objects
 or with plain ruby arrays. That said, plotting is much easier
 with NMatrix objects.
 
-Try some of the commands below to get a feel of how it works.
 
+== 2D PLOTS
+
+The examples below illustrate how 2D plots work and what features
+they have. Try out the examples to get a feel for BPlot.
+
+  require 'bplot'
+  
+  x = [1,2,3,4,5]
+  y = [1,4,9,16,25]
+  z = [25,20,15,10,5]
+  
+  b = BPlot.new
+
+
+Send a raw command into Gnuplot.
+
+  b.cmd('plot sin(x) title "Plot without Ruby."')
+
+
+Global settings.
+
+  b.set('xrange [0:6]')
+  b.set('yrange [0:30]')
+  b.set('title "Heading for the entire plot"')
+
+
+Replot the most recent plot.
 
-EXAMPLES: 2D PLOTS
--------------------
+  b.replot
 
-require 'bplot'
 
-x = [1,2,3,4,5]
-y = [1,4,9,16,25]
-z = [25,20,15,10,5]
 
-b = BPlot.new
+Basic plots.
 
-#
-# Send a raw command into Gnuplot.
-#
-b.cmd('plot sin(x) title "Plot without Ruby."')
+  b.plot(x, y)
+  b.plot(x, y, 'ps 2', 'rh')
+  b.plot(x, y, 'ps 2', 'rh..-', 'y = x^2')
 
 
-#
-# Gnuplot 'set' command.
-#
-b.set('xrange [0:6]')
-b.set('yrange [0:30]')
-b.set('title "Heading for the entire plot"')
+The 'with' command on the gnuplot string takes precedence.
 
+  b.plot(x, y, 'ps 2 w lp', 'rh')
+  b.plot(x, y, 'ps 2 with steps', 'rh')
 
-#
-# Gnuplot 'replot' command.
-#
-b.replot
 
 
-#
-# Basic plots.
-#
-b.plot(x, y)
-b.plot(x, y, 'ps 2', 'rh')
-b.plot(x, y, 'ps 2', 'rh..-', 'y = x^2')
+Named parameters.
 
-#
-# The 'with' command on the gnuplot string takes precedence.
-#
-b.plot(x, y, 'ps 2 w lp', 'rh')
-b.plot(x, y, 'ps 2 with steps', 'rh')
+  b.plot(x, y, :title => 'Density', :gnuplot => 'lc 3 ps 1.5 lt 4 pt 5 w lp')
+  b.plot(x, y, :title => 'Density', :gnuplot => 'ps 1.5', :matlab => 'rh-')
+  b.plot(x, y, :t => 'Mass', :g => 'ps 2.5', :m => 'bh--')
 
 
-#
-# Named parameters.
-#
-b.plot(x, y, :title => 'Density', :gnuplot => 'lc 3 ps 1.5 lt 4 pt 5 w lp')
-b.plot(x, y, :title => 'Density', :gnuplot => 'ps 1.5', :matlab => 'rh-')
-b.plot(x, y, :t => 'Mass', :g => 'ps 2.5', :m => 'bh--')
 
+Multiple data sets (need not be the same length).
 
-#
-# Multiple data sets (need not be the same length).
-#
-b.plot(x, y, 'ps 2', 'rh-', x, z, 'ps 1.5', 'bs--')
-b.plot(x, y, 'ps 2', 'rh-', 'Quadratic', x, z, 'ps 1.5', 'bs--', 'Linear')
+  b.plot(x, y, 'ps 2', 'rh-', x, z, 'ps 1.5', 'bs--')
+  b.plot(x, y, 'ps 2', 'rh-', 'Quadratic', x, z, 'ps 1.5', 'bs--', 'Linear')
 
 
-# Observe that named parameters must be at the end. Hence, they only apply to the last plot.
+Observe that named parameters must be at the end. Hence, they only apply to the last plot.
 
-b.plot(x, y, 'ps 2', 'rh-',       'Quadratic', x, z, 'ps 1.5', 'bs--', :t => 'Linear') # OK.
-b.plot(x, y, 'ps 2', 'rh-', :t => 'Quadratic', x, z, 'ps 1.5', 'bs--',       'Linear') # ERROR.
+  b.plot(x, y, 'ps 2', 'rh-',       'Quadratic', x, z, 'ps 1.5', 'bs--', :t => 'Linear') # OK.
+  b.plot(x, y, 'ps 2', 'rh-', :t => 'Quadratic', x, z, 'ps 1.5', 'bs--',       'Linear') # ERROR.
 
 

data/Roadmap

@@ -0,0 +1,38 @@
+= Roadmap
+
+== Version 0.0.3
+
+* X and Y error bars.
+
+* Variable, data-dependent point size.
+
+* Pie charts.
+
+* Get NVector working.
+
+* Movies with ffmpeg or avconv (or maybe also mencoder).
+
+== Version 0.0.4
+
+* Surface plots.
+
+* New methods: meshgrid(), splot(), surf(), mesh()
+
+== Version 0.0.5
+
+* Complete coverage of top level Gnuplot functions.
+
+* Proper testing on Windows and Mac.
+
+== Version 0.1.0 (milestone)
+
+* First release that is basically feature complete. It will
+  certainly need bugfixes and additions, but at this point
+  it should be be at least moderately stable.
+
+* From this point on, the API should be stable.
+
+* First beta release.
+
+
+

data/Tutorial

@@ -0,0 +1,312 @@
+= BPlot Tutorial (version 0.0.2)
+
+BPlot is a powerful scientific plotting module for SciRuby. It can produce
+high quality 2D (and soon 3D) plots thanks to its Gnuplot backend. Gnuplot
+is a mature free software tool for scientific plotting. BPlot presents a
+convenient API to SciRuby users and converts all instructions into Gnuplot
+commands.
+
+The BPlot API contains a mixture of Matlab features and Gnuplot features.
+The API provides a soft transition for users familiar with either one of
+these plotting tools. Over time, Matlab users are likelky to pick up some
+Gnuplot and Gnuplot users are likely to pick up some Matlab.
+
+
+== Status
+
+BPlot is in ALPHA status. Two dimensional plots seem to work well but they
+really need more testing. Surface plots and some other features are not
+implemented yet. Use at your own risk.
+
+
+== Installation
+
+BPlot is provided as a Ruby gem. Installation should be as easy as:
+
+  gem install bplot
+
+It is recommended that you install and use NMatrix, but BPlot is designed
+to also work with regular Ruby arrains. Therefore, NMatrix is not actually
+a dependency. That said, plotting is likely to be easier with NMatrix.
+
+
+== Getting Started
+
+After installation, start the Ruby shell with the command "irb" (if you have
+Ruby version 1.8, type "irb -rubygems"). Then type the following:
+
+  require 'bplot'
+  
+  b = BPlot.new
+
+
+This code loads the BPlot module and creates an instance of BPLot. Every
+instance of BPlot has its own dedicated Gnuplot process. In this way, BPlot
+lets you control multiple Gnuplot processes from a single script.
+
+
+=== Raw commands
+
+Though not done often, BPlot lets you send raw commands into the Gnuplot
+backend. The *cmd* method allows you to bypass BPlot, so you can use any
+Gnuplot feature that is not implemented in BPlot.
+
+  b.cmd('plot sin(x) title "Plot without Ruby."')
+
+
+=== Settings
+
+The *set* and *unset* methods are thin wrappers around the Gnuplot commands
+of the same names. These methods can be used to set *A LOT* of options.
+However, nothing is drawn until the user issues a plotting command. You can
+use "set" to create any number of output files (postscript, png, svg, EPS
+with LaTeX, etc.).
+
+
+  b.set('terminal postscript enhanced color')
+  b.set('output "myplot.ps"')
+  
+  b.cmd('plot sin(x) title "Plot without Ruby."')
+  
+  b.set('terminal wxt')
+
+
+You can use "set" to set many global options. For example:
+
+  b.set('xrange [0:6]')
+  b.set('yrange [0:30]')
+  b.set('xlabel "This is the X Axis"')
+  b.set('ylabel "This is the Y Axis"')
+  b.set('title "A title for the whole plot"')
+
+As mentioned earlier, these settings will not be visible until you issue 
+another plotting command. However, you can find out their values using
+the *show* command:
+
+ b.show('terminal')
+ b.show('xrange')
+ b.show('title')
+
+
+=== Refresh
+
+This command reformats and redraws the current plot with the latest
+settings. This is useful for viewing a plot with different "set"
+options, or for generating the same plot for several output formats.
+
+  b.refresh
+
+
+=== 2D Plots
+
+By far the most important method is *plot*. This is the command that
+draws 2D plots using NMatrix objectts or Ruby arrays. This method has
+several optional parameters mostly related to the look of individual
+data sets (e.g. colour, line thickness, point style, etc.).
+
+==== Named parameters
+
+The most intuitive way to configure the *plot* command is with named
+parameter. The following example illustrates the +:title+ and +:color+
+options:
+
+  x = [1,2,3,4,5]
+  y = [1,4,9,16,25]
+  
+  b.plot(x, y)
+  b.plot(x, y, :title => "My Data", :color => "blue")
+  b.plot(x, y, :title => "My Data", :color => "#33aa55")
+
+The colour can be specified as an RGB hex string ("#33aa55") or any colour
+name that Gnuplot recognizes. To see a full list type *b.show('colornames')*,
+but some examples include:
+
+  red         dark-red        light-red          black         white
+  green       dark-green      light-green        grey0         gray0
+  blue        dark-blue       light-blue         grey10        gray10
+  cyan        dark-cyan       light-cyan         grey20        gray20
+  magenta     dark-magenta    light-magenta      grey30        gray30
+  grey        dark-grey       light-grey         grey40        gray40
+  gray        dark-gray       light-gray         grey50        gray50
+  pink        dark-pink       light-pink         grey60        gray60
+  orange      dark-orange     light-orange       grey70        gray70
+  yellow      dark-yellow                        grey80        gray80
+  violet      dark-violet                        grey90        gray90
+  coral                       light-coral        grey100       gray100
+
+You can instruct BPlot to connect points with lines using the +:lines+
+option, and you can configure the point style with the +:points+ option.
+Both parameters take a style string that specifies the line-width/point-size
+and the line-type/point-type separated by a semicolon:
+
+  b.plot(x, y, :lines => "2;dashed", :points => "2;open-circle")
+  b.plot(x, y, :lines => "1;dots",   :points => "1.5;filled-square")
+
+You can leave either option blank. For example, `:lines => ";dashed"` defines
+a dashed line of the default thickness ("1"), while `:lines => "2;"` defines
+a line of width "2" of the default line type ("solid"). As shown in the example,
+sizes can be decimal. The valid line and point types are listed below in full:
+
+  Line Types                Point Types
+  ----------                -----------
+  solid                     +                   plus
+  dashed                    x                   cross
+  dots                      *                   star
+  dot-dashed                open-square         solid-square
+  dot-dot-dashed            open-circle         solid-circle
+                            open-diamond        solid-diamond
+                            open-up-triangle    solid-up-triangle
+                            open-down-triangle  solid-down-triangle
+
+==== Style strings
+
+As you write more plots, named parameters quickly become cumbersome. BPlot
+supports a powerful and compact style string that is derived from Matlab
+and Gnuplot. You can insert a single string with the syntax:
+
+  <-MATLAB-STRING-> ; <-DATA-TITLE-> ; <-GNUPLOT-STRING->
+
+The best way to learn this is to see it in action. The Matlab string can
+be used to set the colour, line style and point styles:
+
+  b.plot(x, y, 'r')
+  b.plot(x, y, 'g')
+  b.plot(x, y, 'm')
+  
+  b.plot(x, y, 'go')
+  b.plot(x, y, 'bs')
+  b.plot(x, y, 'm^')
+  
+  b.plot(x, y, 'r-')
+  b.plot(x, y, 'm--')
+  b.plot(x, y, 'k.-')
+  
+  b.plot(x, y, 'rd-')
+  b.plot(x, y, 'rv:')
+  b.plot(x, y, 'rh..-')
+
+
+The meaning of all the symbols available is described below:
+
+  Colours                         Line Styles
+  -------                         -----------
+  r   ==  red                     -     ==  solid
+  g   ==  green                   :     ==  dots
+  b   ==  blue                    --    ==  dashed
+  m   ==  magenta                 .-    ==  dot dashed
+  c   ==  cyan                    ..-   ==  dot dot dashed
+  y   ==  yellow
+  k   ==  black
+  
+  
+  Point Styles
+  ------------
+  +   ==  plus                \
+  x   ==  cross                \
+  *   ==  star                  \
+  o   ==  open circle            \ ___  Matlab styles with direct
+  s   ==  solid square           /      Gnuplot equivalents.
+  ^   ==  solid up triangle     /
+  v   ==  solid down triangle  /
+  d   ==  solid diamond       /
+  
+  <   ==  open up triangle     \
+  >   ==  open down triangle    \ ____  Matlab styles that were mapped
+  p   ==  open diamond          /       to a different Gnuplot style.
+  h   ==  solid circle         /
+  
+  q   ==  open square          \ _____  Non-Matlab style, inserted to add
+                               /        full coverage of Gnuplot styles.
+
+
+As in Matlab, you can add a title after a semicolon (e.g. "rh;My Plot;").
+You can also add a Gnuplot style string after the second semicolon. The
+Gnuplot string gives you access to the full power of Gnuplot. Try the
+examples below:
+
+  b.plot(x, y, 'rh;Quadratic')
+  b.plot(x, y, 'rh;Quadratic;ps 2')
+  
+  b.plot(x, y, 'ro--;y = x^2;ps 2 lw 2')
+  b.plot(x, y, 'rs.-;y = x^2;ps 1.5 lw 1')
+  
+  b.plot(x, y, 'r--;;smooth cspline')
+  b.plot(x, y, 'r--;;with steps')
+  b.plot(x, y, 'r- ;;with impulses')
+
+
+The Matlab portion of the string may some times disagree with the Gnuplot portion.
+For example 'rs--' implies that the plot should display both data points (drawn as
+squares) and lines (drawn as dashed lines). But what if the Gnuplot string specifies
+"with lines" (as opposed to "with linespoints")? If there is a disagreement, the
+Gnuplot instrucion takes presedence. For example:
+
+  b.plot(x, y, 'rs;;with linespoints')
+  b.plot(x, y, 'rs;;with steps')
+
+
+[Warning:] Do not enter a title in the Gnuplot style string. Doing so is not supported
+           and will fail when you least expect it. Use the method provided instead.
+
+==== Multiple plots
+
+You can have any number of data sets plotted in the same window, using the same
+"plot" command. To do this, simply include all the data sets separated by style
+strings (the style strings can be blank).
+
+
+  x  = [1,2,3,4,5]
+  y1 = [1,4,9,16,25]
+  y2 = [25,20,15,10,5]
+  y3 = [20,10,20,10,5]
+  
+  b.plot(x, y1, "", x, y2)
+  b.plot(x, y1, "", x, y2, "", x, y3)
+  b.plot(x, y1, 's;;ps 1',        x, y2, 'h;;ps 2',   x, y3, 'o;;ps 3 lw 1.5')
+  b.plot(x, y1, 's-;;ps 1',       x, y2, 'h--;;ps 2', x, y3, 'o:;;ps 3 lw 1.5')
+  b.plot(x, y1, 'ro--;Quadratic', x, y2, 'b^:;Linear')
+
+[Warning:] Resist the temptation of skipping the blank style strings. Doing so will
+           work for now, but will likely stop working soon, when I add support for
+           plotting error bars.
+
+
+Learning the compact style syntax is especially important for multiple plots because
+they named parameters like :title can only be included once in a plot command, and
+they always apply to the last data set only.
+
+There is also a *multiplot* method which can be "abused" to plot several differnet
+data sets in the same plot, using several different plot commands.
+
+  b.multiplot do
+    b.set('yrange [0:30]')
+    b.plot(x, y1, :color => 'red',  :lines => '1;dashed')
+    b.plot(x, y2, :color => 'blue', :lines => '1;dots')
+    b.plot(x, y3, :color => 'black',:points=> '3;open-circles')
+  end
+
+But the real power of *multiplot* is the ability to place several entirely separate
+plots on the same page, using any layout that you wish. To see an exaple of how this
+works, try the following examples:
+
+  b.multiplot('layout 1,3 title "Multiplot layout 1x3" ') do
+    b.set('title "Quadratic"')
+    b.plot(x, y1, :color => 'red',  :lines => '1;dashed')
+    b.set('title "Linear"')
+    b.plot(x, y2, :color => 'blue', :lines => '1;dots')
+    b.set('title "Zig Zag"')
+    b.plot(x, y3, 'ko--')
+  end
+
+== How to explore more: Gnuplot demos
+
+An excellent way to explore what you can do with BPlot is to go through the Gnuplot
+demos page:
+
+http://gnuplot.sourceforge.net/demo/
+
+Not everything in this page is implemented in BPlot, but this page is a great way
+to explore what's possible with Gnuplot, and Gnuplot ultimately determines what is
+possible with BPlot.
+
+

data/lib/bplot.rb

@@ -1,89 +1,4 @@
 =begin
-BPlot -- A ploting module for SciRuby. It provides an API
-         familiar to Gnuplot users and to a lesser extent
-         Matlab users.
-
-                 \     /
-             \    o ^ o    /
-               \ (     ) /
-    ____________(%%%%%%%)____________
-   (     /   /  )%%%%%%%(  \   \     )
-   (___/___/__/           \__\___\___)
-      (     /  /(%%%%%%%)\  \     )
-       (__/___/ (%%%%%%%) \___\__)      A hard-working bee.
-               /(       )\
-             /   (%%%%%)   \
-                  (%%%)
-                    !
-
-EXAMPLES: 2D PLOTS
--------------------
-
-require 'bplot'
-
-x = [1,2,3,4,5]
-y = [1,4,9,16,25]
-z = [25,20,15,10,5]
-
-b = BPlot.new
-
-#
-# Send a raw command into Gnuplot.
-#
-b.cmd('plot sin(x) title "Plot without Ruby."')
-
-
-#
-# Gnuplot 'set' command.
-#
-b.set('xrange [0:6]')
-b.set('yrange [0:30]')
-b.set('title "Heading for the entire plot"')
-
-
-#
-# Gnuplot 'replot' command.
-#
-b.replot
-
-
-#
-# Basic plots.
-#
-b.plot(x, y)
-b.plot(x, y, 'ps 2', 'rh')
-b.plot(x, y, 'ps 2', 'rh--', 'y = x^2')
-
-#
-# The 'with' command on the gnuplot string takes precedence.
-#
-b.plot(x, y, 'ps 2 w lp', 'rh')
-b.plot(x, y, 'ps 2 with steps', 'rh')
-
-
-#
-# Named parameters.
-#
-b.plot(x, y, :title => 'Density', :gnuplot => 'lc 3 ps 1.5 lt 4 pt 5 w lp')
-b.plot(x, y, :title => 'Density', :gnuplot => 'ps 1.5', :matlab => 'rh-')
-b.plot(x, y, :t => 'Mass', :g => 'ps 2.5', :m => 'bh--')
-
-
-#
-# Multiple data sets (need not be the same length).
-#
-b.plot(x, y, 'ps 2', 'rh-', x, z, 'ps 1.5', 'bs--')
-b.plot(x, y, 'ps 2', 'rh-', 'Quadratic', x, z, 'ps 1.5', 'bs--', 'Linear')
-
-
-# Observe that named parameters must be at the end. Hence, they only apply to the last plot.
-
-b.plot(x, y, 'ps 2', 'rh-',       'Quadratic', x, z, 'ps 1.5', 'bs--', :t => 'Linear') # OK.
-b.plot(x, y, 'ps 2', 'rh-', :t => 'Quadratic', x, z, 'ps 1.5', 'bs--',       'Linear') # ERROR.
-
-
-
-========================================
 TODO: SURFACE PLOTS
 -------------------
 
@@ -101,6 +16,7 @@ b.splot(x,y,z)
 #
 # I'll document this function when I implement surface plots.
 #
+=begin
 def meshgrid(x,y)
 	warn "Input to meshgrid() must be 1 dimensional" if x.dim > 1
 	warn "Input to meshgrid() must be 1 dimensional" if y.dim > 1
@@ -113,8 +29,26 @@ def meshgrid(x,y)
 	
 	return xx, yy.transpose
 end
+=end
+
 
+# BPlot is a 2D and 3D plotting module for SciRuby. It provides a
+# simple API that will be familiar to Gnuplot users and to a lesser
+# extent Matlab users. BPlot is in ALPHA status. Two dimmensional
+# plots seem to work well but they really need more testing. Also,
+# the API is not yet settled and may change without warning. Many
+# features are not yet implemented, including surface plots.
 class BPlot
+	# === Create new engine
+	# 
+	# Every call to BPlot#new creates a new instance of Gnuplot. You can
+	# have multiple instances of Gnuplot in the same Ruby script.
+	#
+	# === Example
+	#
+	#   b.BPlot.new
+	#   b.cmd('plot sin(x)')
+	# 
 	def initialize()
 		#
 		# Every instance of BPlot has its own gnuplot process.
@@ -130,30 +64,112 @@ class BPlot
 	end
 	
 	#
-	# Command -- Send a raw command into Gnuplot.
-	#            Gives the user more control over Gnuplot.
+	# === Issue raw command
+	# 
+	# Send a raw command to the Gnuplot backend.
+	# This gives the user more control over plotting engine.
+	#
+	# === Example
+	#
+	#   b.BPlot.new
+	#   b.cmd('plot sin(x)')
 	#
 	def cmd(str)
 		@pipe.puts str
 	end
 	
 	#
-	# Settings -- Wrapper for 'set' command in Gnuplot.
+	# === Settings
+	# 
+	# This method is a thin wrapper around the Gnuplot "set" command.
+	# It can be used to set *a lot* of options. However, nothing is
+	# drawn until the user issues a plotting command. See the examples
+	# below for a quick overview. See the Gnuplot documentation for
+	# more details.
+	#
+	# === Examples
+	#
+	#   b.set('terminal enhanced postscript color')
+	#   b.set('output "myplot.ps"')
+	#   b.set('xrange [0:10]')
+	#   b.set('yrange [0:50]')
+	#   b.set('xlabel "This is the X Axis"')
+	#   b.set('ylabel "This is the Y Axis"')
+	#   b.set('title "A title for the whole plot"')
 	#
 	def set(str)
 		@pipe.puts "set #{str}"
 	end
 	
+	# === Settings
+	# 
+	# This method is a thin wrapper around the Gnuplot "unset" command.
+	# It is used to reset settings back to their default values. See
+	# the documentation on "set" for more information. See also the
+	# Gnuplot documentaion for "set" and "unset".
+	def unset(str)
+		@pipe.puts "unset #{str}"
+	end
+	
+	# === Show
 	#
-	# Replot -- Wrapper for the 'replot' command in Gnuplot.
+	# The `set` command can be used to set *lots* of options.  No screen is
+	# drawn, however, until a plotting command is given. The *show* command
+	# shows their settings; show('all') shows all the settings.
 	#
-	def replot
-		@pipe.puts "replot"
+	def show(str)
+		@pipe.puts "show #{str}"
 	end
 	
 	#
-	# 2D plotting -- Mostly like Gnuplot, but adding colours and line/point styles from Matlab.
+	# === Refresh
+	#
+	# This command reformats and redraws the current plot with the latest
+	# settings. This is useful for viewing a plot with different "set"
+	# options, or for generating the same plot for several output formats.
+	#
+	# === Example
 	#
+	#   b.set('terminal postscript')
+	#   b.set('output "myplot.ps"')
+	#   b.refresh
+	#   
+	#   b.set('terminal png')
+	#   b.set('output "myplot.png"')
+	#   b.refresh
+	#
+	def refresh()
+		@pipe.puts "refresh"
+	end
+	
+	# == Multiplot
+	# 
+	# In multiplot mode, multiple plot commands are placed togeher in the
+	# same window. This can be a convenient alternative to having a very
+	# long multiple-line plot command. It allso allows you to add plots
+	# using loops and other constructions.
+	# 
+	# == Examples
+	#
+	#   b.multiplot do
+	#     plot(x, y1)
+	#     plot(x, y2)
+	#     plot(x, y3)
+	#   end
+	#   
+	#   b.multiplot do
+	#     (0..10).each { |t| plot( x, sin(x + v*t) ) }
+	#   end
+	def multiplot(opts='')
+		@pipe.puts "set multiplot #{opts}"
+		yield if block_given?
+		@pipe.puts "unset multiplot"
+	end
+	
+	# == 2D Plotting
+	# 
+	# This is the key method in BPlot, as it is responsible for all 2D plots. This
+	# method is currently in a state of flux and is for the moment undocumented.
 	def plot(*args)
 		
 		data = []
@@ -202,107 +218,116 @@ class BPlot
 	
 	private
 	
-	#
-	# TODO: Can I avoid using strings here?
-	#
-	def finished(args)
-		args.length == 0 or
-					args[0].class.to_s == 'Array' or
-					args[0].class.to_s == 'NMatrix'
-	end
-	
 	#
 	# - Get all the stye information for the next plot from 'args'.
 	# - Return the styles as a string, and the remainder of 'args'.
 	#
 	def styles(args)
 		
-		g_with = ''
-		m_with = ''
-		str_index = 0
-		this_plot = " '-' "
-		while !finished(args)
-			if args[0].is_a?(String)
-				
-				g_with << gnu_with(args[0]) 		if str_index == 0
-				m_with << mat_with(args[0]) 		if str_index == 1
-				
-				this_plot << gnu_style(args.shift)	if str_index == 0
-				this_plot << mat_style(args.shift)	if str_index == 1
-				this_plot << tit_style(args.shift)	if str_index == 2
-				
-				str_index += 1
-				
-			elsif args[0].is_a?(Hash)
-				opts = args.shift
-				
-				# Gnuplot style.
-				g_with << gnu_with(opts[:g])			if opts[:g]
-				g_with << gnu_with(opts[:gn])			if opts[:gn]
-				g_with << gnu_with(opts[:gnu])			if opts[:gnu]
-				g_with << gnu_with(opts[:gnup])			if opts[:gnup]
-				g_with << gnu_with(opts[:gnupl])		if opts[:gnupl]
-				g_with << gnu_with(opts[:gnuplo])		if opts[:gnuplo]
-				g_with << gnu_with(opts[:gnuplot])		if opts[:gnuplot]
-				
-				this_plot << gnu_style(opts[:g])		if opts[:g]
-				this_plot << gnu_style(opts[:gn])		if opts[:gn]
-				this_plot << gnu_style(opts[:gnu])		if opts[:gnu]
-				this_plot << gnu_style(opts[:gnup])		if opts[:gnup]
-				this_plot << gnu_style(opts[:gnupl])	if opts[:gnupl]
-				this_plot << gnu_style(opts[:gnuplo])	if opts[:gnuplo]
-				this_plot << gnu_style(opts[:gnuplot])	if opts[:gnuplot]
+		with  = ''
+		title = ''
+		color = ''
+		style = " '-' "
+		
+		if args[0].is_a?(String)
+			
+			opts = args.shift
+			opts = opts.split(/;/)
+			
+			#
+			# Gnuplot 'with' beats Matlab's.
+			#
+			with = gnu_with(opts[2]) if opts[2]
+			with = mat_with(opts[0]) if with == ''
+			
+			style << mat_style(opts[0])
+			style << gnu_style(opts[2]) if opts[2]
+			
+			title = opts[1] if opts.length >= 1
+		end
+		
+		if args[0].is_a?(Hash)
+			#
+			# Incidentally, if we are here, this is the end of the plot command.
+			#
+			opts = args.shift
+			
+			title  = opts[:title]  if opts[:title]
+			color  = opts[:color]  if opts[:color]
+			
+			#
+			# Infer the 'with' command for :lines and :points.
+			#
+			if opts[:lines]
+				lw, lt = opts[:lines].split(/;/)
 				
+				lw = 1  if lw == ''
+				lt = 1  if lt == '' or lt == nil
+				lt = 1  if lt.to_s =~ /solid/i
+				lt = 2  if lt.to_s =~ /dashed/i
+				lt = 3  if lt.to_s =~ /dots/i
+				lt = 4  if lt.to_s =~ /dot-dashed/i
+				lt = 5  if lt.to_s =~ /dot-dot-dashed/i
 				
-				# Matlab style.
-				m_with << mat_with(opts[:m])			if opts[:m]
-				m_with << mat_with(opts[:ma])			if opts[:ma]
-				m_with << mat_with(opts[:mat])			if opts[:mat]
-				m_with << mat_with(opts[:matl])			if opts[:matl]
-				m_with << mat_with(opts[:matla])		if opts[:matla]
-				m_with << mat_with(opts[:matlab])		if opts[:matlab]
+				style << " lw #{lw} lt #{lt} "
+			end
+			if opts[:points]
+				ps, pt = opts[:points].split(/;/)
 				
-				this_plot << mat_style(opts[:m])		if opts[:m]
-				this_plot << mat_style(opts[:ma])		if opts[:ma]
-				this_plot << mat_style(opts[:mat])		if opts[:mat]
-				this_plot << mat_style(opts[:matl])		if opts[:matl]
-				this_plot << mat_style(opts[:matla])	if opts[:matla]
-				this_plot << mat_style(opts[:matlab])	if opts[:matlab]
+				ps = 1  if ps == ''
+				pt = 1  if pt == ''
+				pt = 1  if pt == '+'
+				pt = 2  if pt == 'x' or pt == 'X'
+				pt = 3  if pt == '*'
+				pt = 1  if pt.to_s =~ /plus/i
+				pt = 2  if pt.to_s =~ /cross/i
+				pt = 3  if pt.to_s =~ /star/i
+				pt = 4  if pt.to_s =~ /open-square/i
+				pt = 5  if pt.to_s =~ /solid-square/i
+				pt = 6  if pt.to_s =~ /open-circle/i
+				pt = 7  if pt.to_s =~ /solid-circle/i
+				pt = 8  if pt.to_s =~ /open-up-triangle/i
+				pt = 9  if pt.to_s =~ /solid-up-triangle/i
+				pt = 10 if pt.to_s =~ /open-down-triangle/i
+				pt = 11 if pt.to_s =~ /solid-down-triangle/i
+				pt = 12 if pt.to_s =~ /open-diamond/i
+				pt = 13 if pt.to_s =~ /solid-diamond/i
 				
-				# Title.
-				this_plot << tit_style(opts[:t])		if opts[:t]
-				this_plot << tit_style(opts[:ti])		if opts[:ti]
-				this_plot << tit_style(opts[:tit])		if opts[:tit]
-				this_plot << tit_style(opts[:titl])		if opts[:titl]
-				this_plot << tit_style(opts[:title])	if opts[:title]
+				style << " ps #{ps} pt #{pt} "
 			end
 			
+			#
+			# "with" strings from both Matlab and Gnuplot take precedence.
+			#
+			# In other words:  Gnuplot > Matlab > Named parameters. 
+			#
+			if with == ''
+				with = 'with lines'       if opts[:lines]
+				with = 'with points'      if opts[:points]
+				with = 'with linespoints' if opts[:lines] and opts[:points]
+			end
 		end
 		
 		
-		# - The user may insert a 'with' in the gnuplot string which conflicts with matlab.
-		# - In this case, the gnuplot string takes precdence.
-		# - If you insert the word "with" in a title inside the gnuplot string... it's your
-		#   own fault. I told you to put the title in the :title parameter.
-		
-		this_plot << g_with
-		this_plot << m_with if g_with == ''
-		
 		#
-		# If there is no title, add a blank one.
+		# Finish up the command (title, colour, 'with', etc).
 		#
-		this_plot << " title '' " if this_plot !~ /tit/
+		style << " lc rgb \"#{color}\" " if color != ''
+		style << " title  \"#{title}\" "
+		style << with if with
 		
-		#
-		# Return 'this_plot' and what is left of 'args'.
-		#
-		return this_plot, args
+		return style, args
 	end
 	
 	
 	def gnu_with(s)
-		s =~ /w/ ? s.scan(/([wW][iI]?[tT]?[hH]? +\w+)/).last.first : ''
+		regex = /\b([wW][iI]?[tT]?[hH]? +\w+)/
+		s =~ regex ? s.scan(regex).last.first : ''
+	end
+	def gnu_style(str)
+		str.gsub(/\b([wW][iI]?[tT]?[hH]? +\w+)/, '')
 	end
+	
 	def mat_with(s)
 		wp = s =~ /[xsovdph<>+*^]/ ? true : false
 		wl = s =~ /[-:.]/ ? true : false
@@ -311,13 +336,6 @@ class BPlot
 		return " with points "		if wp
 		return " with lines "       if wl
 	end
-	
-	def tit_style(str)
-		" title \"#{str}\" "
-	end
-	def gnu_style(str)
-		str.gsub(/([wW][iI]?[tT]?[hH]? +\w+)/, '')
-	end
 	def mat_style(mat)
 		style = '';
 		
@@ -341,10 +359,15 @@ class BPlot
 		style << " pt 13 " if mat =~ /d/
 		
 		# Styles I cannot duplicate properly:
-		style << " pt 8  " if mat =~ /</
-		style << " pt 10 " if mat =~ />/
-		style << " pt 4  " if mat =~ /p/
-		style << " pt 7  " if mat =~ /h/
+		style << " pt 8  " if mat =~ /</  # open up triangle.
+		style << " pt 10 " if mat =~ />/  # open down triangle.
+		style << " pt 12 " if mat =~ /p/  # open diamond
+		style << " pt 7  " if mat =~ /h/  # solid circle
+		
+		#
+		# Extra remaining style (non-Matlab).
+		#
+		style << " pt 4  " if mat =~ /q/  # open square
 		
 		# Line styles
 		style << " lt 1 " if mat =~ /-/ and mat !~ /--/ and mat !~ /\.-/ and mat !~ /\.\.-/

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: bplot
 version: !ruby/object:Gem::Version
-  version: 0.0.1
-  prerelease: 
+  version: 0.0.2b
+  prerelease: 5
 platform: ruby
 authors:
 - Daniel Carrera
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-07 00:00:00.000000000 Z
+date: 2012-08-11 00:00:00.000000000 Z
 dependencies: []
 description: A 2D and 3D plotting module for SciRuby that uses syntax from Gnuplot
   and to a lesser degree Matlab.
@@ -20,6 +20,9 @@ extra_rdoc_files: []
 files:
 - README
 - LICENSE
+- Tutorial
+- ChangeLog
+- Roadmap
 - lib/bplot.rb
 homepage: http://rubygems.org/gems/bplot
 licenses: []
@@ -31,26 +34,14 @@ post_install_message: ! "*******************************************************
   is a bee.\n               /(       )\\             I like bees.\n             /
   \  (%%%%%)   \\\n                  (%%%)\n                    !\n\n              ***
   WARNING ***\n\nBPlot is in ALPHA status. Two dimmensional plots seem to work\nwell
-  but they really need more testing. Surface plots and some\nother features are not
-  implemented yet.\n\nBPlot uses Gnuplot as the plotting engine, so you need to have\nGnuplot
-  installed and in your PATH. BPlot lets you use straight\nGnuplot commands, but it
-  also borrows some useful style syntax\nfrom Matlab to make plotting even better.\n\nBPlot
-  can work with either NMatrix objects or with plain Ruby\narrays. Try some of the
-  commands below to get a feel of how\nit works:\n\nrequire 'bplot'\n\nx = [1,2,3,4,5]\ny
-  = [1,4,9,16,25]\nz = [25,20,15,10,5]\n\nb = BPlot.new\n\n# Send a raw command into
-  Gnuplot.\nb.cmd('plot sin(x) title \"Plot without Ruby.\"')\n\n# Gnuplot 'set' command.\nb.set('xrange
-  [0:6]')\nb.set('yrange [0:30]')\nb.set('title \"Heading for the entire plot\"')\n\n#
-  Gnuplot 'replot' command.\nb.replot\n\n# Basic plots.\nb.plot(x, y)\nb.plot(x, y,
-  'ps 2', 'rh')\nb.plot(x, y, 'ps 2', 'rh--', 'y = x^2')\n\n# The 'with' command on
-  the gnuplot string takes precedence.\nb.plot(x, y, 'ps 2 w lp', 'rh')\nb.plot(x,
-  y, 'ps 2 with steps', 'rh')\n\n# Named parameters.\nb.plot(x, y, :title => 'Mass',
-  :gnuplot => 'ps 1.5', :matlab => 'rh-')\nb.plot(x, y, :t => 'Mass', :g => 'ps 2.5',
-  :m => 'rh-')\n\n# Multiple data sets (need not be the same length).\nb.plot(x, y,
-  'ps 2', 'rh-', x, z, 'ps 1.5', 'bs--')\nb.plot(x, y, 'ps 2', 'rh-', 'Quadratic',
-  x, z, 'ps 1.5', 'bs--', 'Linear')\n\n# Named parameters only allowed for the last
-  data set.\nb.plot(x, y, 'ps 2', 'rh-',       'Quadratic', x, z, 'ps 1.5', 'bs--',
-  :t => 'Linear') # OK.\nb.plot(x, y, 'ps 2', 'rh-', :t => 'Quadratic', x, z, 'ps
-  1.5', 'bs--',       'Linear') # ERROR.\n\n***********************************************************\n"
+  but they really need more testing. Many features such as\nsurface plots have not
+  been implemented yet. The backend uses\nGnuplot, so you must have Gnuplot installed
+  and in your PATH.\n\nThe plotting command mixes Matlab and Gnuplot syntax. The addition\nof
+  Matlab syntax to Gnuplot makes plotting immensely easier while\nstill retaining
+  the power of Gnuplot. BPlot provides a comfortable\nenvironment for Matlab and Gnuplot
+  users. Matlab users will learn\nsome Gnuplot and Gnuplot users will leran some Matlab.\n\nDon't
+  forget to read the tutorial!\n\nBPlot comes with a nice tutorial that documents
+  every feature.\nIf you don't have a copy of the tutorial, you can get one here:\n\nhttps://github.com/dcarrera/bplot/blob/master/Tutorial\n\n\n***********************************************************\n"
 rdoc_options: []
 require_paths:
 - lib
@@ -63,9 +54,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11