As of version 0.5.4, GraphTool ships with a command line tool called "graphtool". This is meant to be a site-admin level tool which requires no XML or Python knowledge. The input data is piped in through stdin and the output is saved as a PNG to disk (or, written to stdout if the output file is "-").

Example

The example used on this page will be one from D0. Each morning, a simple CSV file is updated with the previous day's production summary, grouped by site. We would like to graph the CSV using a StackedBarGraph, where each site's output is a stacked bar.

Input Data

The input data should be specified as CSV (comma-separated values) and piped in through stdin. Having a header is recommended, but optional (the header can additionally be specified via command line). Here's the first couple lines from our example:

080410,condor1.oscer.ou.edu,6662.8,62000
080410,d0cabosg2.fnal.gov,16713.0,202000
080410,grid1.oscer.ou.edu,3374.1,40250
080410,hg.ihepa.ufl.edu,29801.3,366000
080411,condor1.oscer.ou.edu,1054.7,10000
080411,d0cabosg2.fnal.gov,23291.8,294750
080411,pg.ihepa.ufl.edu,1169.7,14500

Our example has no header, but if it did, this is what it might look like:

Date,OSG Site,MB Produced,Merged Events

The header will be used to make labels. Note that the date is in a special format (YYMMDD); GraphTool does not understand this format natively. If the date is in a format GraphTool knows (Unix timestamp or YYYY-MM-DD HH:MM:SS), then setting the column name to "Time" will cause it to be interpreted as a date object.

Command Line Options

The output of GraphTool is controlled by a plethora of command line options. The most important ones are documented here:

• output - Filename to write the graph into; pass "-" to write to stdout.
  
• title - Title of the graph.
  
• header - If there is no header in the CSV, a header entry. The header should have the format of "pivot,group,results1,results2,...", regardless of the column ordering in the CSV.
  
• graph - The name of the graph to use. The available graphs are Bar, Pie, QualityMap, Cumulative, StackedBar, and SimpleStackedBar. The StackedBar graph is assumed to be a graph of time-based data, while the SimpleStackedBar can be any data.
  
• pivot_col - The column number of the column to use as a pivot. Column numbering is zero-based If you don't understand what a pivot and grouping is, check out the GraphTool tutorial. For our case, we want to pivot by site name, so pivot_col=1.
  
• grouping_col - The column number of the grouping column. In our case, we group by date, so grouping_col=0
  
• results_col - The column number(s) of the results column (comma-separated, if necessary). We have one column of results - the number of events - so results_col=3
  
• grouping_format - If the grouping is time-based, the time formatting which the CSV uses. The formatting options are documented here (look in the strftime section).
  
• span - If the graph is time-based, the span is the number of seconds represented by each data point; in our example, there is one entry per day, resulting in a span of 86400.
• Starttime, Endtime - The start and end time of the data in the graph, if the data is organized by time. Alternately, if you don't know the start and end a priori, use:
• Croptime - Set to "True" to crop the x-axis to fit the available data.
  
• (Any other option) - Any unknown option will be passed as metadata to the graph; each graph type has a large number of possible options, some of which are documented here.
  

Example Usage

For our example, we load the data from a webserver using curl:

curl http://physics.lunet.edu/~snow/d0osgprod.csv 2> /dev/null | graphtool -pivot_col=1 -grouping_col=0  \
    -title="D0 OSG Production" -output=~/tmp/d0osgprod2.png -results_col=3 -graph=StackedBar \
    -grouping_format='%y%m%d' -croptime=True -span=86400 -header="OSG Site,Date,Merged Events"

Here's the output: