[Swift-commit] r5152 - usertools/plotter

[wozniak at ci.uchicago.edu]

Author: wozniak
Date: 2011-09-22 10:48:39 -0500 (Thu, 22 Sep 2011)
New Revision: 5152

Modified:
   usertools/plotter/README.txt
Log:
Fill in the plotter README


Modified: usertools/plotter/README.txt
===================================================================
--- usertools/plotter/README.txt	2011-09-21 17:48:45 UTC (rev 5151)
+++ usertools/plotter/README.txt	2011-09-22 15:48:39 UTC (rev 5152)
@@ -1,6 +1,130 @@
 
+= Swift Plotter
+:toc:
+
 Contains a plotter for simple data sets.
 
 Produces EPS output from two-column data sets using JFreeChart.
 
-User interface is swift_plotter.zsh
+User interface is +swift_plotter.zsh+
+
+The overall idea is to produce high-quality, easily customizable
+plots by using the great feature set in JFreeChart and providing
+a simple, scriptable user interface.
+
+== Usage
+
+The plotter accepts a configuration file, a target output file name
+for the EPS, and a variable number of data files:
+
+----
+swift_plotter.zsh -s my_config.cfg my_output.eps my_data.data
+----
+
+== Configuration
+
+The output is controlled by the configuration (CFG) file which is
+formatted as a Java properties file.  Examples may be found
+in the Swift +log-processing+ directory and the Swift user guide.
+
+Java properties files have a +key=value+ format where comments are
+denoted with *#*.
+
+For example, +load.cfg+ contains:
+----
+# Set the x label to "time"
+xlabel = time
+# Set the y label to "load"
+ylabel = load
+# For the data series in file "load.data", use no shapes
+shape.load.data = none
+# For the data series in file "load.data", use legend label "load"
+label.load.data = load
+----
+
+=== Configuration properties
+
+* Numbers may be formatted in obvious ways.
+  (Cf. Java +Double.parseDouble()+.)
+* True/false may be +true+ or +false+.
+  (Cf. Java +Boolean.parseBoolean()+.)
+* Some properties are set on a per-file basis.  In this case, part of
+  the key is the file name.
+
+
++title+:: Set a plot title.
++xlabel,ylabel+:: Set labels for the X and Y axes.
++width,height+:: Set the width, height of the output EPS in pixels.
+Defaults to 400 by 400.
++xmin,xmax,ymin,ymax+:: Set the visible region of the plot.
+Defaults to an auto-selection made by JFreeChart.
++bw+:: If true, use black and white only.  Default: +false+.
++legend.enabled+:: If true, show a legend.  Default: +true+.
++axis.x,axis.y+:: May be +normal+ or +logarithmic+.
+Default: +normal+.
++label._filename_+:: Set the legend label for the data series from
+file +_filename_+.
++shape._filename_+:: If +none+, use no shape for the data series from
+file +_filename_+.
+
+Example:
+----
+width = 6000
+height = 1000
+xmin = 2
+xmax = 3
+ymin = 4
+ymax = 5
+bw = true
+# Keep X axis normal but use logarithic Y axis
+axis.y = logarithmic
+----
+
+== Output
+
+EPS files were chosen because of the ease of using them in LaTeX
+documents and the relative ease of producing other high-quality
+images from them via ImageMagick:
+
+----
+convert my_output.eps my_output.png
+----
+
+== Data
+
+The data input is two columns of plain text numbers:
+
+----
+1.965 1.5
+
+8 0
+# This is a comment
+1 7 # This is also a comment
+----
+
+As shown, empty lines and +#+ comments are accepted.
+
+== Plotter options
+
+The plotter accepts the following options on the command line.
+
++-s+:: Use a single Y axis.
++-d+:: Use a double Y axis (dual mode).
++-v+:: Turn on verbose output.
+
+== Dual mode
+
+Dual mode allows the user to plot exactly two data series on the
+same plot, with separate X axes.
+
+. Use +-d+ above.
+. Specify two data files.
+. Instead of +ymin+, +ymax+, specify +ymin1+, +ymax1+,
+  +ymin2+, +ymax2+.
+. The first data series will be plotted with respect to a left-hand
+  Y axis and the second data series with respect to a right-hand
+  Y axis.
+
+== Issues, suggestions, and feature requests
+
+Send mail to swift-user at ci.uchicago.edu