Rongo
Jun Makino
Introduction
rongo is a simple, but potentially powerful interactive plotting program. It operates in the way similar to the good old mongo, but with subtle differences.
Here is a very simple session:
> rongo Entering interactive mode * printer test.ps/vcps * data testdata * xco 1 * yco 2 * lim * square * box * xlabel x * ylabel y * color 2 * con * quit
which creates a plot like below:
Currently, this is basically what is implemented. However, the entire power of PGPLOT is accessible from rongo. For example, to draw error bars, you can just use pgerry (or other similar functions).
Thus, if you are familiar with PGPLOT, rongo gives you a very easy and powerful way to use PGPLOT interactively. Also, since a rongo script is actually a Ruby script, you can use the whole power of Ruby to do complex operations.
License
Ruby’s License
www.ruby-lang.org/ja/LICENSE.txt
www.ruby-lang.org/en/LICENSE.txt
Commands implemented so far
The following list *may be* slightly outdated. For the complete list see COMMAND_REFERENCE.
Commands with same names as in mongo (all should be in lowercase):
- angle d - sets angle of text or points to d degrees
- connect - connects (x,y) pairs read by x and ycolumn with line segments
- data fspec - opens the file "fspec" for reading data
- dot - makes a point of the current style at the current location
- draw x y - draws a line to (x,y) from the last coordinate
- erase - erases the graphics screen or initializes a printer plot
- expand e - expands all characters or points by a factor e
- limits (x1 x2 y1 y2) - sets the limits of the plot (no args for auto)
- ltype n - sets the line type to n
- lweight n - sets the line weight to n
- points - draws points of the current style at the (x,y) of x and ycolumn
- psfix (filename) - add the correct boundingbox at the beginning of the file, instead of the end.
- ptype n s - sets the point type to an n-gon of style s
PTYPE n s causes points to be drawn as n sided polygons of a style s, where s refers to: 0 = open 1 = skeletal (center connected to vertices) 2 = starred 3 = solid PTYPE will also accept one argument which is a composite = 10*n + s. - relocate x y - sets the current coordinates to (x,y)
- xcolumn n - reads x data from column n of the current file
- ycolumn n - reads y data from column n of the current file
- xdata array - set xdata from Ruby array array
- ydata array - set ydata from Ruby array array
- xlabel … - writes the label … centered under the x axis
- xlogarithm - takes the logarithm of x values from XCOLUMN
- ylabel … - writes the label … centered left of the y axis
- ylogarithm - takes the logarithm of y values from YCOLUMN
Note that "box" behaves quite differently than in mongo. It’s similar to what is in wip.
Commands not in mongo, or with different semantics/syntax
- TERMINAL devicename - directs output to a graphics terminal
The argument is the same as that for PGOPEN. If no argument is given, "/xserve" is assumed
- printer devicename - directs output to a hardcopy printer.
Another alias for pgopen. If no argument is given, "pgplot.ps/vcps" is assumed
- box (xopt yopt) - makes a box labelled according to arguments
- squareview - force a squre viewport
This command is useful to make a square plot (which I like)
- quit
In mongo, you can use "end", but since "end" is a reserved word in Ruby we need to use something else.
- justification
used as replacement for "putlabel x" You can say
justfication center justfication left justfication right
which will affect the justification of the subsequent texts printed by label command.
- viewport x0 x1 y0 y1
change viewport, relative to the current viewport
- writebuffer filename
write the command history to file filename (works only in the interactive mode)
Here is the original MONGO command list:
- 3DPLOT ALT AZ ZMAX - makes a 3-d plot of data from orientation ALT AZ
- ANGLE D (X1 Y1 X2 Y2) - sets angle of text or points to D degrees
- AXIS A1 A2 ASMALL ABIG AX1 AY1 AX2 AY2 ILABEL ICLOCK - makes an axis
- BOX (m n) - makes a box labelled according to LIMITS and TICKSIZE
- CONNECT - connects (x,y) pairs read by X and YCOLUMN with line segments
- CONTOUR N LEVEL1 … LEVELN - makes a contour plot of data at levels LEVEL
- CURSOR (x y) - turns on the cursor and reads the resulting position
- DATA fspec - opens the file "fspec" for reading data
- DEFINE xxx - creates macro xxx and enters define mode
- DELETE (n1 n2) - removes the commands n1-n2 from the command buffer
- DEVICE n - sends output to device n
- DOT - makes a point of the current style at the current location
- DRAW X Y - draws a line to (x,y) from the last coordinate
- ECOLUMN N - reads the error bar size from column N of the data file
- END - ends define mode, insert mode or exits from the program
- ERASE - erases the graphics screen or initializes a printer plot
- ERRORBAR K - draws error bars on (x,y) pairs in direction 90(K-1)
- EXPAND E - expands all characters or points by a factor E
- FORMAT (…) - uses format (…) for reading from data files.
- GRID (n) - makes a grid at major/all ticks for n = 0/1
- ID - puts an identification label at the upper right corner of a plot
- INPUT fspec - reads plot commands from file "fspec" and executes them
- INSERT (n) - following commands are inserted before command n in command buffer
- HALFTONE (z1 z2 (contrast)) - makes a halftone picture of data
- HARDCOPY - causes a stored printer plot to be plotted
- HELP xxx - prints an explanation of command xxx
- HISTOGRAM (n) - connects (x,y) pairs from X and YCOLUMN as a histogram
- LABEL … - writes the string … at the last coordinate
- LIMITS (X1 X2 Y1 Y2) - sets the limits of the plot (no args for auto)
- LINES L1 L2 - limits the X,Y, and ECOLUMN file read to lines L1-L2
- LIST (xxx) - lists the commands of macro xxx
- LOCATION GX1 GX2 GY1 GY2 - sets the physical location of the plot
- LTYPE n - sets the line type to n
- LWEIGHT n - sets the line weight to n
- PAGE n - after a PRINTER command, directs output to n pages after 0th
- PCOLUMN n - reads point type data from column n of the current data file
- PHYSICAL LX1 LX2 LY1 LY2 - sets physical limits of plot
- PLAYBACK (xxx) - replay macro xxx or commands in the command buffer
- POINTS - draws points of the current style at the (x,y) of X and YCOLUMN
- PRINTER (n (device)) - directs output to a hardcopy printer
- PTYPE n s - sets the point type to an n-gon of style s
- PUTLABEL L … - writes label … at the current location according to L
- RELOCATE X Y - sets the current coordinates to (x,y)
- RESET - empties the command buffer and reads an initialization file
- SET V X (op Y) - sets symbolic variable V to value X or X(op)Y
- SHOW - shows current limits and location
- TERMINAL (n (device)) - directs output to a graphics terminal
- TICKSIZE SMALLX BIGX SMALLY BIGY - sets tick intervals for BOX
- VFIELD - Draws a vector field as a sequence of arrows
- WINDOW nx ny k - Sets the plot location to a subwindow
- WRITE xxx fspec - writes macro xxx to file "fspec"
- XCOLUMN N - reads x data from column N of the current file
- XLABEL … - writes the label … centered under the x axis
- XLOGARITHM - takes the logarithm of x values from XCOLUMN
- YCOLUMN N - reads y data from column N of the current file
- YLABEL … - writes the label … centered left of the y axis
- YLOGARITHM N - takes the logarithm of y values from YCOLUMN
- BUFFER - predefined macro name that refers to the entire command buffer
Installing rongo
preparation
You need NArray and Ruby/PGPLOT, which you can obtain from raa.ruby-lang.org/
NArray is at: raa.ruby-lang.org/list.rhtml?name=narray
Ruby/PGPLOT is at: raa.ruby-lang.org/list.rhtml?name=ruby-pgplot
The following is how I installed them
467 11:20 cd ../na*7 472 11:20 ruby extconf.rb 473 11:20 make 475 11:20 sudo make install 477 11:22 cd .. 479 11:22 cd rb_pgplot-0.1.2/ 486 11:25 ruby extconf.rb --with-pgplot-include=/usr/local/pgplot --with-x11-dir=/usr/X11R6 487 11:25 make 488 11:25 sudo make install
As you can see, NArray is easy to install. For Ruby/PGPLOT, most likely you need to specify similar options (with appropriate values) as I used above.
Install procedure for rongo
- get rongo-xxx.tar.gz from somewhere
- tar xvzf rongo-xxx.tar.gz will extract files under rongo-xxx
- do the following
cd rongo-xxx ruby setup.rb config ruby setup.rb setup (sudo) ruby setup.rb install
This will place the command rdoc and the library files to "default" location of setup, which are normally /usr/local/bin and /usr/local/lib/ruby/site_ruby/version-id/.
Using rongo
rongo [input file name]
should do the job.
The sample script samples/test.rb
printer sample.gif/vgif data testdata xco 1 yco 2 lim square box xlabel x ylabel y color 2 con quit
shows the minimal way to use rongo. Currently, only the very minimal mongo-like commands are implemented, but they are probably good enough to make basic 2D curve plots. For more advanced functions, you can just directly use Ruby or PGPLOT functions. All Ruby/PGPLOT functions can be called from rongo script.
Theory of operation
Simply put, rongo just define simple wrapper for Ruby/PGPLOT, in Rongo. As you can see in the methods list, this module defines fair number of mongo-like methods and support methods.
The rongo command load this Rongo module, and runs Rongo.rongo, which assumes the first command-line option is the script file and executes that file. If no argument is given, rongo enters to the interactive mode, in which it wait for the input from the keyboard and perform ruby "eval" function for the input line.
Before actual execution, however, it does simple editing of the file, so that it allows the user more sloppy use of commands, just it was so in mongo. The same editing is also applied to input line from keyboard.
This editing is done in convert_to_good_ruby_string, which first try to "complete" abbreviated commands. For example. "xco" is completed to "xcolumn". Then it adds commas between each arguments.
To avoid too much problem, completion is suppressed if the first word is a single character. Thus, you can still write a simple ruby statement like
x = 1
but not
xc = 1
Well, you can write this, but it is translated to
xcolumn =, 1
which would cause error. You can still use the form
xc=1
or
xc= 1
since the completion is done for the first word with the word delimiter being whitespace or tab.
For "box", "data", "justification", "label", "printer", "terminal", "xlabel" and "ylabel" commands, rongo supplies double quotation marks for the arguments, if the arguments are not already quoted, so that the arguments are recognized as ruby strings.
Currently, "box" is treated differently from all other commands, in that for "box" arguments are individually quoted, while for all others all arguments are placed in one ruby string. Thus, for box, the translation is:
box BCNTSV BCNTSV -> box "BCNTSV", "BCNTSV"
while for label, translation is:
label Sample text -> label "Sample text"
Single quotes may show strange results.
This is to allow the form
data datafile
instead of
data "datafile"
This is personal preference, but I like the former much more. The problem with this kind of editing is that you cannot pass normal variables or equations to these commands. However, you can work this around by using ruby’s marvelous variable substitution in string literals. Thus, you can still write, for example,
filename = "datafile"
data #{outname}
Limitation
- In the interpreter mode, you cannot run multi-line constructs like
for i in [1..4] p i endThis is because each line is sent to ruby "eval" function. A simple way to go around this problem is to write the multi-line thing to a text file and use "load"
However, "load" bypasses the rongo line editing. So you have to write, for example,
box "BSNTSV", "BSNTSV"
instead of
box BSNTSV BSNTSV
In other words, the file to be loaded must be a valid ruby scipt.
Commands I plan to implement soon
Well, practically all commands I have ever used in MONGO have been implemented, except for commands related to macros. For macros, it’s much easier to use the power of Ruby itself.