NAME

Chart::Graph::Xrt2d

SYNOPSIS

 #Include module
 use Chart::Graph::Xrt2d qw(xrt2d);

 # Function call
 xrt2d(\%options,
       [\%data_options1, \@data_set1],
       [\%data_options2, \@data_set2],
        .
        .
      );

DESCRIPTION

This module is unmaintained, it worked with Sitraka's XRT, and hasn't been tested against newer versions.

Sitraka (now Quest) makes a number of graphics packages for UNIX systems. XRT is a Motif-based commercial software product that has been adapted by CAIDA using a combination of C drivers and Perl function xrt2d(). The Perl function xrt2d() provides access to the two dimensional graphing capabilities of XRT from Perl. To access the three dimensional graphing using XRT, use xrt3d() also supplied in the Chart::Graph package.

ARGUMENTS

The options to xrt2d() are listed below. Additional control over the resulting graph is possible by using the XRT application itself once the graph has been created.

 +--------------------------------------------------------------------------+
 |                                OPTIONS                                   |
 +----------------+--------------------------+------------------------------+
 | Name           |  Options                 | Default                      |
 +----------------+--------------------------+------------------------------+
 |"output file"   |  (set your own)          | "untitled-xrt2d.gif"         |
 |"output type"   |  "ps","xwd", "png", "jpg"| "xwd"                        |
 |"x-axis title"  |  (set your own)          | "x-axis"                     |
 |"y-axis title"  |  (set your own)          | "y-axis"                     |
 |"set labels"    |  (set your own bar chart | none                         |
 |                |   labels for each set of |                              |
 |                |   data)                  |                              |
 |"point labels"  |  (set your own labels for| none                         |
 |                |   bars themselves)       |                              |
 |"misc labels"   |  (misc annotation that   | none                         |
 |                |   can be added to bar    |                              |
 |                |   chart)                 |                              |
 |"x time"        |  timescale if appropriate| "0"                          |
 |"invert"        |  run bars horizontally   | "0" (vertically)             |
 |                |  instead of vertically.  |                              |
 |                |  1 = horizonally.        |                              |
 |"header"        |  (set your own - can     | "header"                     |
 |                |   be multiple lines)     |                              |
 |"footer"        |  (set your own - can     | "footer"                     |
 |                |   be multiple lines)     |                              |
 |"style"         |  Style of chart - types  | "bar"                        |
 |                |  include: bar, pie, area |                              |
 |                |  stackedbar, stackedarea |                              |
 +----------------+--------------------------+------------------------------+

The xrt2d() function only accepts data in one form. "\@data_sets": a one dimensional array with a prefix of data options.: "[[\%data1_opts, \@data1], [\%data2_opts, \@data2], [\%data3_opts, \@data3]]" -- see example for more details on the syntax.

The data options are listed below.

 +--------------------------------------------------------------------------+
 |                             DATA OPTIONS                                 |
 +----------------+--------------------------+------------------------------+
 | Name           |  Options                 | Default                      |
 +----------------+--------------------------+------------------------------+
 | "color"        | Any valid web page color | none                         |
 +----------------+--------------------------+------------------------------+

DETAILS ON GRAPHICS CONVERTER OPTIONS

The xrt package supports only two graphics formats internally: Postscript and the X windows format XWD. Additional raster graphics formats are supported with Chart::Graph by using one of two graphics converter packages: Imagemagick and Netpbm.

If you need to install a converter package, Imagemagick http://www.imagemagick.org/ is probably preferable simply for its comparatively simplicity. It uses one program convert for all of it's conversion needs, so it is easy to manage and simple for Chart::Graph to use. Many UNIX systems come with some collection of the Netpbm utilities already installed, thus users may be able to start using Chart::Graph without adding any additional converters. Alas, it is unlikely any distributions would include all the converters for the newest graphics formats used by Chart::Graph. In that case it may still preferable to use Imagemagick simply for the sake of avoiding installing over 80 utilities that come with current distributions of Netpbm. For more information on the current distribution of Netpbm go to the current website at: http://netpbm.sourceforge.net/

The xrt package also allows for multiple header and footers with each graph. As a result, instead of just the usual string, an array reference containing the multiple strings for the header and footer text.

EXAMPLES

The following two examples show Chart::Graph::Xrt2d in different roles and producing different styles of output.

HORIZONTAL BAR GRAPH

The following example creates a two, two dimensional bars charts of fictitious stock data from rival restaurants that is displayed in a single graphic file xrt2d-1.jpg.

 #make sure to include Chart::Graph
 use Chart::Graph::Xrt2d qw(xrt2d);

 # Call to xrt2d with two data sources.
 xrt2d({"output file" => "xrt2d-1.jpg",
        "output type" => "jpg",
        "set labels"=> ["Joe's", "Ralph's"],
        # Flip graph from vertical to horizontal
        "invert" => 1,
        "point labels" => ["Jan/Feb", "Mar/Apr", "May/Jun", "Jul/Aug",
                         "Sep/Oct", "Nov/Dec"],
        "x-axis title" => "Month's tracked",
        "y-axis title" => "Stock prices for Rival restaurant chains"
       },
       [{"color" => "MistyRose"}, ["8", "13", "20", "45", "50", "100"]],
       [{"color" => "#000000"},   ["75", "50", "25", "25", "50", "75"]]
    )
 )

VERTICAL BAR GRAPH

The following example is simply a more elaborate instance of the first example. which produces the file xrt2-2.gif. Note the relationship between sets and points. Accidentally reversing the order will cause unpredicable results.

 #make sure to include Chart::Graph
 use Chart::Graph::Xrt2d qw(xrt2d);

 xrt2d({"output file" => "xrt2d-2.gif",
                         "output type" => "gif",
                "set labels" => ["set1", "set2", "set3", "set4"],
                "point labels" => ["point1", "point2", "point3"]},
                # Each entry here corresponds to a set
                [{"color" => "MistyRose"}, ["15", "23", "10"]],
                [{"color" => "#0000FF"}, ["13", "35", "45"]],
                [{"color" => "#00FF00"}, ["15", "64", "24"]],
                [{"color" => "Navy"}, ["18", "48", "32"]],
      );

MORE INFO

For more information on XRT:

 http://www.quest.com/xrt_pds/

CONTACT

Send email to graph-dev@caida.org is 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)