NAME
ygraph - plot and animate 1D data
SYNOPSIS
ygraph [ -cspgrv? ] [ -C columns ] [ -d delay ] [ -k step ] [ -x
xmin,xmax ] [ -y ymin,ymax ] [ -S file1 file2 ] [ -I file ] [ --frame-
integrate file ] [ --time-integrate file ] [ file ... ]
DESCRIPTION
ygraph is a simple program to produce an xy-plot of 1D data. It
features animation, zooming, and the ability to load multiple data sets
into a single plot.
ygraph is intended to be a quick first-glance data reader, so simple,
instinctive use was the major design goal. Most features are directly
available from the control panel and plot window menus. Some data
manipulation functions are present, but fancy plot formatting has been
largely ignored, as there already exist more sophisticated tools for
producing publication quality plots.
The input file format read by ygraph is a slight generalisation of the
historical xgraph format which, for instance, is generated by the
standard I/O methods of the Cactus Computational Toolkit
<URL:http://www.cactuscode.org/>. A more detailed description of the
input file format is given below.
The special filename - can be used to read data from the standard
input:
cat data1.xl | ygraph -
Filenames starting with ’<’ are interpreted and opened as pipe:
ygraph "<cat data1.xl"
Command-line options are as follows:
-c, --no-control-panel
Start without the control panel.
-s, --separate-windows
Start with each requested plot in a separate window.
-p, --no-points
Turn off points drawn at each data point
-g, --no-grid
Don’t draw a grid on the plot background.
-r, --no-range
Don’t draw axis range values on the plot background.
-C, --columns column list
Set (globally) the columns to be read from the input in the
format x:y. Default is 1:2.
-d, --delay time
Delay between successive animation frames. The specified value
time should be an integer representing the number of
milliseconds to delay between frames.
-k, --skip n
Read in only every nth frame of data.
-l, --legend pos
Set the position of the plot legend in the plot window. Valid
pos values are:
a -- the legend is placed above the plot
r -- the legend is placed to the right of the plot
o -- the legend is placed over the plot data
0 -- the legend is turned off (not displayed).
By default, the legend is placed over the plot data, ‘o’.
-S, --subtract file1 file2
Subtract the second listed file from the first. If x-values of
the two plots don’t match, then values of the second are
interpolated linearly to points of the first.
-I, --integrate file
Integrate file assuming f(left boundary)=0
--frame-integrate file
Integrate frames of file
--time-integrate file
Integrate frames of file and multiplying with time given by
comments in the file
-?, --help
List the command line options and exit.
-v, --version
Print a version message and exit.
Filenames are usually treated as regular files that may be compressed
with either gzip or bzip2. If a filename is prefixed with <, it is
treated as a command instead, and data will be read from its standard
input. A filename can also be a single -, which will read data from
ygraph’s standard input.
USAGE
Once the plot window is displayed, most of the available actions should
be obvious from the menu bar and control panel buttons.
ZOOM
To zoom in to a region of the plot, click the mouse left button at the
upper left corner, drag to the lower right corner, and release the
button. A menu option exists to unzoom back to the plot’s original
dimensions.
LOGARITHMIC PLOTS
Logarithmic axes can be set up using the ‘Setting/Range...’ dialog.
Alternatively, the ‘shift-L’ keybinding can be used to toggle between
the following four axis configurations in order: (x,y) =
(linear,linear), (linear,log), (log,log), (log,linear).
DERIVATIVES
The derivative of any displayed plot can be calculated by using the
‘/Plot/Derivative’ menu option from the plot window.
DIFFERENCE BETWEEN DATA SETS
The difference between a pair of data sets can be plotted using the -S
command line option (the next two listed files will be subtracted
pointwise) or the ‘Plot/Subtract A-B...’ menu option. Linear
interpolation of the subtracted data set is used if the data locations
do not line up exactly.
RE-SCALED DATA SETS
The y-values of individual data sets can be rescaled using the
‘Plot/Scale...’ dialog.
POINTER LOCATION
Right-clicking at any point in the plot window will print the pointer
location on the plot background. The labels remain until the window is
refreshed. The ‘c’ keybinding can be used to force a refresh and clean
off the labels.
EXPORT OF IMAGES AND ANIMATIONS
It is possible to export a single frame of a plot using the
‘File/Export image...’ menu option. The extension of the chosen file
name will determine the type of data which is output (eg. jpeg, png,
tiff, ps, etc.).
Currently, support for animations exists only in the form of allowing
the export of multiple frames of a plot, which must then be recombined
afterwards using external software. Multiple frames of an animation
can be saved to a directory using the ‘File/Export animation...’ menu
option. On selecting this option, the user is asked to give a directory
name in which a sequence of images corresponding to the currently
loaded frames of the plot will be saved. By default, the frames are
saved in png format under the names frame_000001.png, frame_000002.png,
etc. The resulting files can be combined to produce an animation using
an external tool, such as the convert utility distributed with
ImageMagick. For example, if the animation frames were saved to the
directory anim_data, then the command
convert -delay 20 anim_data/frame*.png test_anim.gif
could be used to create an animated gif (test_anim.gif) whose frames
consist of the images in anim_data with a delay of 20/100 seconds
between successive frames.
HINTS
· If at any time you lose track of the control panel (eg. by covering
it with other windows), you can raise it by pressing ‘p’ in a plot
window.
· If you find the control panel annoying, don’t forget the ’-c’ command
line option, which suppresses the control panel on startup. You can
use keybindings to control the animation, and call up the control
panel at any time using the ’p’ key.
· If you would like to test convergence of a set of data sets at
different resolutions, you can load them into ygraph and rescale
individual plots using the ‘Plot/Scale...’ dialog.
KEYBINDINGS
The following keybindings are available from the plot window:
h -- go to the first frame
j -- step back one frame
k -- step forward one frame
l -- go to the last frame
space -- play/pause
s -- show all frames
L -- toggle log/linear axes (lin-lin, lin-log, log-log, log-lin)
c -- clean the window
p -- raise the control panel, if it’s hidden behind the plot window
C-n -- open a new plot window
C-o -- open a new file in the current window
C-p -- open a new file in a new window
C-e -- export individual frames as images
C-m -- export multiple frames as images
C-w -- close the plot window
C-d -- take a spatial derivative of the current plot
C-s -- subtract one data set from another
C-m -- rescale data sets
C-u -- unzoom
C-x -- open the plot range dialog
C-p -- toggle the display of dots at each data point
C-g -- toggle display of grid lines
C-r -- toggle display of ranges on the plot window
C-k -- open a window listing the keybindings
C-q -- quit ygraph
Left-mouse -- zoom
Right-mouse -- print the mouse position on the plot
INPUT FILE FORMAT
ygraph reads the standard 1D xgraph data format output by Cactus. The
data can be in the form of an ASCII text file, gzipped or bzipped, in
which case the file will be automatically decompressed as it is read.
XY-data are listed in columns of the form
<x-val1> <y-val1>
<x-val2> <y-val2>
<x-val3> <y-val3>
etc.
where x-val and y-val are floating point coordinates of (x,y) points to
be plotted and are seperated by at least one whitespace character.
Multiple plots are seperated by a blank line. Comment lines are
delimited by beginning the line with a " (double-quote) character, or
by a hash ‘#’ symbol. An optional time value can be assigned to each
data frame by adding a line of the form
"Time = <time-val>
to the head of a set of (x,y) values, where time-val is a floating
point value which will label the particular data set during animation.
The plot can also be assigned a name by a line of the form
"Label = <name>
The assigned name will be used in the legend of the plot.
INPUT DATA EXAMPLE:
"This is just a comment
"Label = Random numbers
"Time = 0.0
0.1 1.343
0.2 1.939
0.3 2.439
0.4 3.949
0.5 5.495
"Time = 0.2
0.1 1.442
0.2 2.303
0.3 3.349
0.4 4.192
0.5 6.029
EXAMPLES
To plot the files data1.xl and data2.xl in the same window, use:
ygraph data1.xl data2.xl
To plot the same pair of files but starting with each in a separate
window, use:
ygraph -s data1.xl data2.xl
To plot columns 1 and 3 from a multi-column data file, use:
cut -f1,3 multicol.dat | ygraph -
To visualize data from multiple columns in one plot, use:
ygraph ’<cut -f1,2 multicol.dat’ ’<cut -f1,3 multicol.dat’
To control the delay between successive frames of the animation of a
data set, use the -d flag. For example, to set the delay to 100ms, use:
ygraph -d 100 data1.xl
To plot a file with the x-range set to (-1,3) and the y-range to
(-2,4), use:
ygraph -x -1,3 -y -2,4 data1.xl data2.xl
To plot data1.xl minus data2.xl, use:
ygraph -S data1.xl data2.xl
AUTHOR
The development of ygraph has been driven by the needs of the Numerical
Relativity Group <URL:http://numrel.aei.mpg.de/> at the Max-Planck-
Institute fuer Gravitationsphysik, Golm, Germany.
ygraph was originally written by Denis Pollney
<firstname.lastname@aei.mpg.de>
<URL:http://numrel.aei.mpg.de/Misc/email.html>. Code has been
contributed by a number of authors, listed in the AUTHORS file of the
source code distribution.
DISTRIBUTION
ygraph is distributed under the GNU General Public License.
More information, recent binaries, and source code can be found at the
author’s homepage <URL:http://www.aei.mpg.de/~pollney/ygraph/>.
REPORTING BUGS
Please report problems to DP at the address above, or to the majordomo
mailing list <ygraph-users@aei.mpg.de>.
SEE ALSO
xgraph(1) convert(1)
11 May 2009