Chart::Graph::Xmgrace
SYNOPSIS
use Chart::Graph::Xmgrace qw(xmgrace);
xmgrace(\%global_options, [\%data_set_options, \@matrix],
[\%data_set_options, \@x_column, \@y_column],
[\%data_set_options, < filename >], ... );
DESCRIPTION
The function xmgrace() is part of the module Chart::Graph that lets
you generate graphs on the fly in perl. It was written as a front-end
application to Xmgrace for hassle-free generation of graphs. xmgrace()
can be supplied with many of the same options and arguments that can
be given to Xmgrace (the UNIX program that evolved from xmgr). For
more information on Xmgrace see the end of this documentation.
ARGUMENTS
Xmgrace has a great deal of options for the overall appearance of a
graph. Chart::Graph::Xmgrace provides control over an essential
subset of them. Others can be easily changed by saving the file using
the grace output file option and then manipulating the file
directing in Xmgrace.
+----------------------------------------------------------------------------+ | GLOBAL OPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ |"title" | (set your own title) | "untitled" | |"subtitle" | (set your own subtitle) | "untitled" | |"type of graph" | "XY chart", "XY graph", | "XY graph" | | | "Bar chart", "Bar graph" | | |"output type" | "png" | "png" | |"output file" | (set your own output file) | "untitled-grace.png" | |"grace output file"| (set your own grace output | "untitled-grace.agr" | | | file) | | |"x-axis label" | (set your own label) | "x-axis" | |"y-axis label" | (set your own label) | "y-axis" | |"x2-axis label" | (set your own label) | undefined | |"y2-axis label" | (set your own label) | undefined | |"logscale x" | "0" or "1" | undefined | |"logscale y" | "0" or "1" | undefined | |"xtics" | (set your own ticks) look at | undefined | | | example | | |"ytics" | (set your own ticks) look at | undefined | | | example | | +-------------------+--------------------------------+-----------------------+
In Xmgrace each set of data has its own options. Because Xmgrace is so complex. a sub-hash of options is needed for all the options associated with each data set. For that reason, only a few data options are noted here.
+----------------------------------------------------------------------------+ | DATA SET OPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ |"title" | (set your own title) | "" | |"options" | \%sub_options |(depends on graph type)| |"data format" | "matrix","columns","file" | "" | |"hidden" | "true" or "false" | "false" | +-------------------+--------------------------------+-----------------------+
Data can be presented to Chart::Graph::Xmgrace Gnuplot in one of three formats for the convenience of the user:
\@matrix: an array reference of [x,y] pairs of data
Alternatively:
\@x_column, \@y_column: two array references of data of equal length. \@x_column is the x-axis data. \@y_column is the y-axis data.
Finally, data can be stored in a file as a parameter to be read into
Chart::Graph::Xmgrace.
since xmgrace allows for many data set options, options is a hash of suboptions (%sub_options below).
%sub_options = (
"symbol" => \%symbol_options,
"line" => \%line_options,
"baseline" => \%baseline_options,
"dropline" => \%dropline_options,
"fill" => \%fill_options,
"avalue" => \%avalue_options
"errorbar" => \%errorbar_options,
);
There are seven types of suboptions as listed below and described in detail in the following tables.
- symbol options
- line options
- baseline options
- dropline options
- fill options
- annotated value options
- errorbar options
+----------------------------------------------------------------------------+ | SYMBOL SUBOPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ | "type" | "0"..."11" | "none" | | | (look at symbol table) | | | "size" | (set own size) | "1.000000" | | "color" | (look at color table) | "auto" | | "pattern" | "0"..."31" | "1" | | "fill color" | "0"..."31" | "1" | | "fill pattern" | "0"..."31" | "1" | | "linewidth" | (set own linewidth) | "1.0" (max. value) | | "linestyle" | "0"..."9" | "1" | | "symbol char" | (not implemented) | "65" | | "char font" | (not implemented) | "0" | | "skip" | "0" or "1" | "0" | +-------------------+--------------------------------+-----------------------+
+----------------------------------------------------------------------------+ | LINE SUBOPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ | "type" | (look at line type) | "1" | | "linestyle" | (look at line style) | "1" | | "linewidth" | (set own width) | "1.0" (max. value) | | "color" | (look at color table) | "auto" | | "pattern" | "0"..."31" | "1" | +-------------------+--------------------------------+-----------------------+
+----------------------------------------------------------------------------+ | BASELINE SUBOPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ | "type" | (look at baseline table) | "0" | | "status" | "on" or "off" | "off" | +----------------------------------------------------------------------------+
+----------------------------------------------------------------------------+ | DROPLINE SUBOPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ | "status" | "on" or "off" | "off" | +-------------------+--------------------------------+-----------------------+
+----------------------------------------------------------------------------+ | FILL SUBOPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ | "type" | "as polygon" or "to baseline" | "as polygon" | | "rule" | "winding" or "even-odd" | "winding" | | "color" | (look at color table) | "auto" | | "pattern" | "0"..."31" | "1" | +----------------------------------------------------------------------------+
+----------------------------------------------------------------------------+ | AVALUE SUBOPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ | "status" | "on" or "off" | "off" | | "type" | "X","Y","XY","string","Z" | "XY" | | "char size" | (set your own size) | "1.000000" | | "font" | "0".."13" | "0" | | "color" | (look at color table) | "auto" | | "rot" | (set own angle) | "0" | | "format" | "0"..."31" | "1" | | "prec" | "0"..."9" | "3" | | "prepend" | (set your own prepend) | "" | | "append" | (set your own apppend) | "" | | "offset" | ["own value", "own value"] | "[0.00, 0.00]" | +----------------------------------------------------------------------------+
+----------------------------------------------------------------------------+ | ERRORBAR SUBOPTIONS: | +-------------------+--------------------------------+-----------------------+ | NAME | OPTIONS | DEFAULT | +-------------------+--------------------------------+-----------------------+ | "status" | "on" or "off" | "off" | | "place" | "normal","opposite","both" | "normal" | | "color" | (look at color table) | "auto" | | "pattern" | "0"..."31" | "1" | | "size" | (set your own size) | "1.000000" | | "font" | "0".."13" | "0" | | "linewidth" | (set own width) | "1.0" (max. value) | | "linestyle" | (look at line type) | "1" | | "riser linewidth"| (set own riser linewidth) | "1.0" | | "riser linestyle"| (look at line type) | "1" | |"riser clip status"| "on" or "off" | "off" | |"riser clip length"| (set own clip length) | "0.100000" | +----------------------------------------------------------------------------+
The suboptions above use the arguments listed below.
+----------------------------------------------------------------------------+ | SYMBOL TYPE: | +--------+-------+--------+------+-------+--------+--------------------------+ | SYMBOL | VALUE | SYMBOL | TYPE | VALUE | SYMBOL | VALUE | +--------+-------+--------+------+-------+--------+--------------------------+ | none | "0" |triangle| up | "4" | plus | "8" | | circle | "1" |triangle| left | "5" | x | "9" | | square | "2" |triangle| down | "6" | star | "10" | | diamond| "3" |triangle| right| "7" | char | "11" | +--------+-------+--------+------+-------+--------+--------------------------+
+-----------------------------------------------------------------+ | LINE TYPE | +------------------------+-------+------------------------+-------+ | LINE TYPE | VALUE | LINE TYPE | VALUE | +------------------------+-------+------------------------+-------+ | none | "0" | right stairs | "3" | | straight | "1" | segments | "4" | | left stairs | "2" | 3-segments | "5" | +------------------------+-------+------------------------+-------+
+-----------------------------------------------------------------+ | LINE STYLE | +------------------------+-------+------------------------+-------+ | LINE STYLE | VALUE | LINE STYLE | VALUE | +------------------------+-------+------------------------+-------+ | none | "0" | solid | "1" | | dotted | "2" | en-dash | "3" | | em-dash | "4" | dot-en dash | "5" | | dot-em dash | "6" | dot-en-dot dash | "7" | | en-dot-en dash | "8" | | | +------------------------+-------+------------------------+-------+
+-----------------------------------------------------------------+ | COLORS | +-------+-----+-------+-----+--------+-----+-----------+----------+ | COLOR |VALUE| COLOR |VALUE| COLOR |VALUE| COLOR | VALUE | | white | "0" | blue | "4" | violet | "8" | indigo | "12" | | black | "1" | yellow| "5" | cyan | "9" | maroon | "13" | | red | "2" | brown | "6" | magenta| "10"| turquoise | "14" | | green | "3" | grey | "7" | orange | "11"| dark green| "15" | +-------+-----+-------+-----+--------+-----+-----------+----------+
EXAMPLES
The following three examples show the various capabilities of the Chart::Graph interface to the Xmgrace program.
GENERAL EXAMPLE
The following example produces the file xmgrace1.png and contains three kinds of data plots. The first plot is an XY plot using triangles for the presentation style and rightstairs lines. The second plot is also an XY plot using lines andtriangle symbols. The last plot is a bar graph.
# Include modules use Chart::Graph::Xmgrace qw(xmgrace);
xmgrace( { "title" => "Example of a XY Chart",
"subtitle" =>"optional subtitle",
"type of graph" => "XY chart",
"output type" => "png",
"output file" => "xmgrace1.png",
"x-axis label" => "my x-axis label",
"y-axis label" => "my y-axis label",
"logscale y" => "1",
"xtics" => [ ["one", "1"], ["two", "2"], ["three", "3"] ],
"ytics" => [ ["one", "1"], ["two", "2"], ["three", "3"] ],
"grace output file" => "xmgrace1.agr",
},
[ { "title" => "XY presentation data1",
"set presentation" => "XY",
"options" => {
"line" => {
"type" => "1",
"color" => "8",
"linewidth" => "1",
"linestyle" => "3",
},
"symbol" => {
"symbol type" => "6",
"color" => "1",
"fill pattern" => "1",
"fill color" => "1",
},
"fill" => {
"type" => "0",
},
},
"data format" => "matrix",
},
[ [1,2],
[2,4],
[3,6],
[4,8],
[5,10],
[6,12],
[7,14],
[8,16],
[9,18],
[10,20] ]
],
[ { "title" => "XY presentation data2",
"options" => {
"line" => {
"type" => "2",
"color" => "4",
},
"symbol" => {
"symbol type" => "1",
"color" => "1",
"fill pattern" => "3",
"fill color" => "5",
},
"fill" => {
"type" => "0",
}
},
"data format" => "columns",
},
[
[1,2,3,4,5,6,7,8,9,10],
[3,6,9,12,15,18,21,24,27,30],
]
],
[ { "title" => "BAR presentation data3",
"set presentation" => "BAR",
"data format" => "file"}, "sample"],
);
NON-STACKING REGIONS
The following shorter example shows how Xmgrace handles regions without stacking the graphs (the default for Xmgrace is to not stack data.)
# Include modules use Chart::Graph::Xmgrace qw(xmgrace);
xmgrace({"title" => "Example of a XY graph",
"subtitle" => "optional subtitle",
"type of graph" => "XY graph",
"output type" => "png",
"output file" => "xmgrace2.png",
"grace output file" => "xmgrace2.agr",
"x-axis label" => "my x-axis label",
"y-axis label" => "my y-axis label"
},
[{"title" => "data",
"options" => {
"fill" => { "type" => "2" },
},
"data format" => "file"
},
"sample"
],
);
MULTIPLE DATA SETS IN MATRIX FORM
The following example shows how to graph more complicated datasets using the Chart-Graph interface to Xmgrace. It produces the file xmgrace3.png.The numbers from this example were generated from the script that created it and saved using the standard Perl module Data-Dumper.
# Include modules use Chart::Graph::Xmgrace qw(xmgrace);
xmgrace({'y-axis label' => 'Percent of widgets',
'output file' => 'xmgrace3.png',
'type of graph' => 'Bar chart',
'output type' => 'png',
'title' => 'Percent of widgets',
'grace output file' => 'xmgrace3.agr',
'subtitle' => 'Data collected from 07/24/2001 to 08/01/2001',
'x-axis label' => 'Date of data sampling'
},
[{'data format' => 'matrix',
'title' => 'Widget A'
},
[
[ '2001-07-24', '32.58' ],
[ '2001-07-25', '30.4291287386216' ],
[ '2001-07-26', '34.4106463878327' ],
[ '2001-07-27', '34.44' ],
[ '2001-07-28', '37.4482270936458' ],
[ '2001-07-29', '37.8769479862376' ],
[ '2001-07-30', '34.9437860832574' ],
[ '2001-07-31', '36.0707388962293' ],
[ '2001-08-01', '40.0591353996737' ]
]
],
[{'data format' => 'matrix',
'title' => 'Widget B'
},
[
[ '2001-07-24', '29.13' ],
[ '2001-07-25', '30.8192457737321' ],
[ '2001-07-26', '29.1775065039023' ],
[ '2001-07-27', '29.82' ],
[ '2001-07-28', '28.9221133447823' ],
[ '2001-07-29', '28.5772110908723' ],
[ '2001-07-30', '29.2109794388737' ],
[ '2001-07-31', '26.8624860250025' ],
[ '2001-08-01', '8.442088091354' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget C'
},
[
[ '2001-07-24', '15.42' ],
[ '2001-07-25', '17.2251675502651' ],
[ '2001-07-26', '15.6093656193716' ],
[ '2001-07-27', '16.02' ],
[ '2001-07-28', '14.526719870694' ],
[ '2001-07-29', '15.1791135397693' ],
[ '2001-07-30', '16.8337891218475' ],
[ '2001-07-31', '16.3227970322187' ],
[ '2001-08-01', '17.7304241435563' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget D'
},
[
[ '2001-07-24', '7.61' ],
[ '2001-07-25', '7.80234070221066' ],
[ '2001-07-26', '7.82469481689013' ],
[ '2001-07-27', '7.57' ],
[ '2001-07-28', '7.72805333872108' ],
[ '2001-07-29', '7.34669095324833' ],
[ '2001-07-30', '7.95097741314697' ],
[ '2001-07-31', '10.7226344140665' ],
[ '2001-08-01', '12.9282218597064' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget E'
},
[
[ '2001-07-24', '10.75' ],
[ '2001-07-25', '9.53285985795739' ],
[ '2001-07-26', '8.375025015009' ],
[ '2001-07-27', '7.79' ],
[ '2001-07-28', '6.32387109809072' ],
[ '2001-07-29', '6.90143695608177' ],
[ '2001-07-30', '6.26962422769169' ],
[ '2001-07-31', '5.43754446590101' ],
[ '2001-08-01', '14.8960032626427' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget F'
},
[
[ '2001-07-24', '3.16' ],
[ '2001-07-25', '2.68080424127238' ],
[ '2001-07-26', '3.08184910946568' ],
[ '2001-07-27', '2.85' ],
[ '2001-07-28', '2.78816042024447' ],
[ '2001-07-29', '2.6006881198138' ],
[ '2001-07-30', '3.0892332624329' ],
[ '2001-07-31', '3.02876308567944' ],
[ '2001-08-01', '3.02814029363785' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget G'
},
[
[ '2001-07-24', '1.14' ],
[ '2001-07-25', '1.28038411523457' ],
[ '2001-07-26', '1.26075645387232' ],
[ '2001-07-27', '1.33' ],
[ '2001-07-28', '2.09112031518335' ],
[ '2001-07-29', '1.27504553734062' ],
[ '2001-07-30', '1.43826597791958' ],
[ '2001-07-31', '1.31110885252566' ],
[ '2001-08-01', '2.76305057096248' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget H'
},
[
[ '2001-07-24', '0.09' ],
[ '2001-07-25', '0.110033009902971' ],
[ '2001-07-26', '0.150090054032419' ],
[ '2001-07-27', '0.07' ],
[ '2001-07-28', '0.111122335589453' ],
[ '2001-07-29', '0.121432908318154' ],
[ '2001-07-30', '0.121543603767852' ],
[ '2001-07-31', '0.111799979672731' ],
[ '2001-08-01', '0.0815660685154976']
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget I'
},
[
[ '2001-07-24', '0.04' ],
[ '2001-07-25', '0.0500150045013504' ],
[ '2001-07-26', '0.0500300180108065' ],
[ '2001-07-27', '0.02' ],
[ '2001-07-28', '0.0303060915243964' ],
[ '2001-07-29', '0.0607164541590771' ],
[ '2001-07-30', '0.0709004355312468' ],
[ '2001-07-31', '0.0203272690314056' ],
[ '2001-08-01', '0.0101957585644372' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget J'
},
[
[ '2001-07-24', '0.03' ],
[ '2001-07-25', '0.0600180054016205' ],
[ '2001-07-26', '0.0400240144086452' ],
[ '2001-07-27', '0.08' ],
[ '2001-07-28', '0.0202040610162643' ],
[ '2001-07-29', '0.0303582270795386' ],
[ '2001-07-30', '0.0607718018839259' ],
[ '2001-07-31', '0.0609818070942169' ],
[ '2001-08-01', '0.0203915171288744' ]
]
],
[
{
'data format' => 'matrix',
'title' => 'Widget K'
},
[
[ '2001-07-24', '0.05' ],
[ '2001-07-25','0.0100030009002701' ],
[ '2001-07-26','0.0200120072043226' ],
[ '2001-07-27', '0.01' ],
[ '2001-07-28','0.0101020305081321' ],
[ '2001-07-29', '0.0303582270795386' ],
[ '2001-07-30', '0.010128633647321' ],
[ '2001-07-31', '0.0508181725785141' ],
[ '2001-08-01', '0.0407830342577488' ]
]
]
) # xmgrace call
MORE INFO
For more information on Xmgrace, please see the Xmgrace web page: http://plasma-gate.weizmann.ac.il/Grace
CONTACT
Send email to graph-dev@caida.org if you have problems, questions, or comments. To subscribe to the mailing list send mail to graph-dev-request@caida.org with a body of "subscribe your@email.com"
AUTHOR
CAIDA Perl development team (cpan@caida.org)