Introduction to Xplot

This page is an introduction to using Xplot on FreeBSD and on creating Xplot files using the xplotLib routines.


Using Xplot

path (on FreeBSD machines):  /usr/dirt/bin/xplot-dirt

Xplot reads from a text file (for example, xplotFile.xpl) to generate its plots. These files can be created using the xplotLib routines that are described below.

running Xplot: xplot xplotFile.xpl

Xplot is particulary useful when plotting large amounts of data. The Xplot user interface allows zooming into specific regions on the graph. Postscript files (both full-page and smaller) can also be created.

Xplot User Interface

To zoom in: Drag a rectangle with the left mouse button.
To pop the zoom stack (ie -- go back): Click the leftmouse button.
To scroll: Drag with the middle mouse button.

Zooming or scrolling below the x axis zooms or scrolls only in the x direction. Similarly, zooming or scrolling to the left of the y axis zooms or scrolls only in the y direction.

To close the window: Click the right mouse button.
To exit Xplot: Close all windows.

To drop a full-page postscript file: Click the left button while SHIFT is pressed. The title is used as the filename. Otherwise, "xplot" is used. The file ends in PS.# where # is a serial number.  Xplot is careful not to write over a previously dumped postscript file, and # is incremented until an unused filename is found.

To drop a smaller postscript file: Click the middle button while SHIFT is pressed. This drops a postscript file, but this will be scaled suitably to allow the figure to be included in a document.  If you didn't like the size of the figure produced by SHIFT-Middle, clicking the right button while SHIFT is pressed will produce a postscript plot just like the middle button, but it will take less vertical space.

Version 0.90 Command Line Options

-x and -y used with multiple plots tells xplot to synchronize the x or y ranges respectively between those plots. So, if you zoom in one window, it zooms in all of the windows with the same data type for that axis.

-tile tells xplot to tile its windows instead of placing them on top of one another. It does make the windows ridiculously small sometimes, though.


Mark's Wonderful Additions to Xplot

path: /usr/home/bin/xplot-dirt on the FreeBSD machines. (src in /usr/src/xplot-dirt.)

  • Added capability for calculating avg. and std. dev. for the y values of the points shown in the window. (i.e. if you zoom, it recalculates based on the points shown.) The averages and standard deviations are calculated for all points of type "dot". Separate averages and standard deviations are calculated for different colors. The results are printed in the window you're running xplot from and are updated everytime the screen is redrawn. This feature is always on for points with a y-coordinate type of double. (Not anymore: see the 's' command below.)

  • Added ability to dump an xplot format file containing only the points currently shown. The x and y coordinates must be of type double. It does dump your title, xlabel, ylabel, xunits, yunits, and it works for dots and diamonds. It does not record other drawing types (e.g. line, arrow, tick). They should be straight forward to add though. It does not record text items. They weren't straight forward. Hit d in the window, and it will generate a file of the form, "*.PS.#". Just do an 'ls -lt *.PS.*' to find the new file in your directory and then rename it.

  • Added a really hacked way to print the coordinates of a single dot (handy for getting the coordinates of a particular point by zooming in). It only prints the "last" dot so if you have more than one. Ctrl-middle-button and then do something that forces a redraw.

  • Added the ability to turn on and off colors within a particular graph. In the window you wish to work with, hit c for the mapping between colors and their index (0-9) (displayed in the window you started xplot from. Press the appropriate number to toggle whether that color is on or off. For colors greater than 9, hit i in the xplot window. Then, type in the number (in the window you started xplot in) and hit return. While that window is waiting for input xplot is paused waiting for that input.

  • Note: These are "hacks" in that they don't fully support all of xplot's data types, but it should be fairly easy to extend them for other datatypes (ticks, arrow, whatever). Mark says "I just added support for what I need. If you want to add support for other data types. I'll be happy to give you some input." (Michele's hint: look in ~parris/src/xplot-0.90/xplot.c for help.)

  • At Michele's request I changed the postscript dump routine to dump a file named "file.#.ps" where '#' is an incrementing number (to allow for unique file names) and file is the name of the original *.xpl file without the '.xpl' suffix.

  • -geom takes a geometry specification like 600x500+10+20 and creates the initial xplot window of the specified size at the specified coordinates. You can also specify the default geom with *xplot*geom in your X Resources.

  • Bounding box options
    
    -bb_top    Y_VALUE
    -bb_bottom Y_VALUE
    -bb_left   X_VALUE
    -bb_right  X_VALUE
    
    
    The -bb* flags specify the bounding box to use when the window is first displayed. This is the equivalent of zooming in to a box with these coordinates.

  • Dump bounding box: hitting 'b' inside the xplot window will dump the bounding box for the data currently displayed as a series of command line arguments (suitable for cutting and pasting).

  • Stats: 's' toggles on/off the printing of the statistical information for each set of colored dots.

  • Mouse coordinates: Ctrl-Button1 Prints the coordinates of the pointer in the current window. (at Mikkel's request).

  • Other useful keys:
    
    'f'     Turn all colors OFF.
    
    'p'     Drop a post-script file.
    
    'q'     Quit xplot.
    
    'c'     List the colors available and whether they are on or off.
    
    'o'     Turn all colors on.
    
    'd'     dump an xpl file (for doubles only so far).
    
    

  • General Format of Xplot Files

    All Xplot files must begin with the following header: (After the header, everything in the xplot file is a plot command.)
       [x-axis type] [y-axis type]
       title
       [Enter title here]
       xlabel
       [Enter x-axis label here]
       ylabel
       [Enter y-axis label here]
    
    Plot command format: [shape] [x-coordinate] [y-coordinate] [color]

    Text plot command format:
    [text cmd] [x-coordinate] [y-coordinate]
    [text to print]

    Axis types: timeval, double, signed, unsigned (don't use unsigned...)

    Shapes: x, dot (or .), plus (or +), box, diamond, utick, ltick, dtick, rtick, vtick, uarrow, darrow, larrow, rarrow, line, dline (dotted line), invisible (plots an invisible point, so you can control axis range)

    Text cmds: ctext (center on point), rtext (to the right of point), ltext (to the left of point), atext (above the point), btext (below the point)

    Colors: red, blue, yellow, green, white, magenta, orange, purple, chartreuse1, yellow1, khaki1, sienna1, wheat1, tan, salmon, hotpink, LightBlue1, LightGreen, red4 OR {0..16}


    Using xplotLib++ (and xplotLib)

    xplotLib++ path: ~clark/dirt/include/xplotLib++.{c,h}
    (C++ style functions, compile code with g++)

    xplotLib path ~clark/dirt/include/xplotLib.{c,h}

    To use xplotLib++ routines: include and compile xplotLib++.c in your makefile OR use an already compiled xplotLib++.o file found in ~clark/dirt/include/FreeBSD
    (This will be changed later to make using xplotLib++ easier.)

    xplotLib++ routines:

    ** createHeader() must be included before making calls to any other xplotLib++ (or xplotLib) routines.

    void createHeader (FILE* fp, char* xtype, char* ytype, char* title, char* xlabel, char* ylabel, char* dumpFilename, char* xplotFilename);
    void createHeader (FILE* fp, char* xtype, char* ytype, char* title, char* xlabel, char* ylabel, char* dumpFilename);

    fp - pointer to output file that xplot will read from
    xtype - character string of type of x-axis data ("integer", "timeval", "signed", "unsigned", "double")
    ytype- character string of type of y-axis data
    title - title of plot
    xlabel - label of x-axis
    ylabel - label of y-axis
    dumpFilename - filename of data file that is being plotted
    xplotFilename - filename of xplot file being generated

    The title on the graph will be in the following format:
    <title> (dump file: <dumpFilename>) (xplot file: <xplotFilename>)

    void plotDot (FILE*, struct timeval x, double y, char* color);
    void plotDot (FILE*, double x, double y, char* color);

    void plotLine (FILE*, struct timeval x1, double y1, struct timeval x2, double y2, char* color);
    void plotLine (FILE*, double x1, double y1, double x2, double y2,  char* color);

    void plotText (FILE* fp, char* type, struct timeval x, double y, char* text);
    void plotText (FILE* fp, char* type, double x, double y, char* text);
    ** Plots text, type is atext, btext, rtext, ltext, or ctext relative to the point specified.

    void forceZero (FILE* fp, struct timeval x);
    void forceZero (FILE* fp, double x);
    ** Plots an invisible point (x,0), so that y axis starts at 0.

    xplotLib routines:

    void createHeader (FILE* fp, char* xtype, char* ytype, char* title, char* xlabel, char* ylabel, char* dumpFilename, char* xplotFilename);

    void plotter_time_un_line (FILE*, struct timeval x1, unsigned y1, struct timeval x2, unsigned y2, char* color);
    ** Plots a line with unsigned values on the y-axis vs timeval values on the x-axis

    void plotter_time_sign_line (FILE*, struct timeval x1, int y1, struct timeval x2, int y2, char* color);
    ** Plots a line with signed values on the y-axis vs timeval values on the x-axis

    void plotter_time_double_line (FILE*, struct timeval x1, double y1, struct timeval x2, double y2, char* color);
    ** Plots a line with double values on the y-axis vs timeval values on the x-axis

    void plotter_un_un_line (FILE*, unsigned x1, unsigned y1, unsigned x2, unsigned y2, char* color);
    ** Plots a line with unsigned values on the y-axis vs unsigned values on the x-axis

    void plotter_time_un_dot (FILE*, struct timeval x, unsigned y, char* color);
    ** Plots a dot with unsigned values on the y-axis vs timeval values on the x-axis

    void plotter_un_un_dot (FILE*, unsigned x, unsigned y, char* color);
    ** Plots a dot with unsigned values on the y-axis vs unsigned values on the x-axis

    void plotter_time_sign_dot (FILE*, struct timeval x, int y, char* color);
    ** Plots a dot with signed values on the y-axis vs timeval values on the x-axis

    void plotter_time_double_dot (FILE*, struct timeval x, double y, char* color);
    ** Plots a dot with double values on the y-axis vs timeval values on the x-axis

    If there are any other routines that you think would be useful, please let me know.


    xplotLib++ Example

    #include "xplotLib++.h"
    void main (int argc, char* argv[])
    {
       struct timeval recvTime, lastPlotTime;
       double intervalPercent, lastIntPercent;
       FILE* dumpFP, *outFP;
       char dump[255]="", outfile[255]="";
       ...
    
       createHeader (outFP, "timeval", "double", 
                     "loss percentage vs. receive time", "receive time", 
                     "loss percentage", dump, outfile);
       ...
    
       plotDot (outFP, recvTime, intervalPercent, "red");
    
       plotLine (outFP, lastPlotTime, lastIntPercent, recvTime, intervalPercent, 
                 "yellow");
    }
    

    Other examples (that were included with Xplot) can be found at /usr/src/xplot-0.90/demo.* on the FreeBSD machines.


    Help! My Time-Sequence Number Graphs Don't Plot!

    New tcptrace (with double default for tsg instead of unsigned): ~clark/bin/tcptrace
    (source is in ~clark/src/tcptrace/)

    According to the xplot README, "xplot does not behave well when you wrap around the end of a coordinate space. This is particularly likely if the unsigned coordinate type is used and you attempt to scroll or zoom to values below zero. Because of this, the unsigned coordinate type is not recommended. However, unsigned is the only reasonable choice for TCP sequence numbers. A 64-bit signed integer coordinate type should be added to xplot someday. For typical applications, double should be used for both coordinate types."

    If you used tcptrace to generate time-sequence-number plots and your plots don't show up properly, it is probably because the sequence numbers are greater than what can be represented in 31 bits.

    Change the first line of your files from:

    timeval unsigned
    to
    timeval double
    This should solve the problem.
    Other DiRT documents
    Author: Michele Clark

    Last updated: October 10, 1998