Contents
Return to main CLIChart documentation page.
This page documents the clichart tool, which is the main tool in the CLIChart project.
Clichart is a Java program (with shell script and batch file wrappers, for UNIX/Linux and Windows respectively). Its job is to generate a chart from tabular data, and either to display the chart in a window or save it to disk.
Clichart can:
- Accept data from stdin or from a file
- Accept input as comma-separated or whitespace-separated
- Produce charts plotted against time (any units down to seconds), numbers, or just as arbitrary values
- Plot any number of data series, on one or two Y axes
- Treat the first row of data as headers for the data series
- Include titles for the chart, X axis and Y axis/axes
- Plot first or second axis as line or bar chart (histogram)
- Control plot line/var thickness, and whether data points display
- Display charts in an interactive window, allowing full customisation of display
- Save charts as JPEG or PNG, either from the command-line or in the display window
- Operate in CLI server mode, generating 1 or more charts based on commands passed via standard in (either from another script, or from a command file)
- Operate in TCP/IP server mode, generating 1 or more charts based on commands passed via a TCP/IP socket (e.g. from cliserverlib).
You use the tool like this:
clichart [options] [inputFile]
-b,--bar Show as a bar chart, not X-Y line
--bar2 Show second axis as a bar chart, not X-Y line
-c,--csv Expect input as CSV. Default is
whitespace-separated
--cliserver Run the program as a CLI server, reading all
commands from standard in
--colours Override default chart colours. Consists of a
comma-separated list of 'index:colour', where 'index' is the 0-based
series index, and 'colour' is 'red', 'blue', 'green' etc (see
documentation). Indexes not overridden use default colours
--columnlist2 List of columns for second y axis (if any),
comma-separated, 0-based.
-d,--dateformat Format of date/time, in SimpleDateFormat notation.
Defaults to 'HH:mm'
--datapoints Indicate each data point
--datapoints2 Indicate each data point for the second Y axis
-f,--hasheader First row of data provides column headers for the legend
(default is no header row)
--forceyrange Force the y axis to use the limits (minimum/maximum) provided. Default
is to use limits only if chart values would exceed them
--forceyrange2 Force the second y axis (if any) to use the limits (minimum/maximum)
provided. Default is to use limits only if chart values would
exceed them
-g,--height Chart height in pixels (defaults to 600)
-h,--help Show usage (this screen) and exit
-i,--ignoremissing Ignore missing columns (default is to terminate)
--ignoreempty Ignore empty columns (default is to terminate)
-l,--columnlist List of columns, comma-separated, 0-based. X axis
value (if any) must be first. Defaults to '0,1'
--lineweight Line weight (values are 1 - 5)
--lineweight2 Line weight for the second Y axis (values are 1 - 5)
-m,--maxy Maximum value for y axis
--maxy2 Maximum value for second y axis (if any)
--miny Minimum value for y axis
--miny2 Minimum value for second y axis (if any)
-n,--noxvalue Chart has no X axis values - just number the rows
instead
-o,--outputpath Output chart to the given path (otherwise shows in a
window), must be JPG or PNG
-p,--ignoredup Ignore duplicate X axis values (default is to
terminate)
--port Port on which server should listen (only if TCP/IP
server required)
--seriestitles Data series titles, comma-separated. Interpreted in
same order as Y axis values in the column list
--seriestitles2 Second axis data series titles, comma-separated.
Interpreted in same order as second axis column list
-t,--title Title for the chart
-v,--xvalue Chart has simple values as the X axis, not dates or
times
-w,--width Chart width in pixels (defaults to 800)
-x,--xtitle Title for the X axis
-y,--ytitle Title for the Y axis
--ytitle2 Title for the second Y axis (if any)
If no input file is provided, the tabular data is read from standard input.
The data format (-d option) uses format strings specified by Java's SimpleDateFormat (see the specification table here).
The most common format string elements are:
| Format | Meaning |
|---|---|
| yy | Year, 2 digits |
| yyyy | Year, 4 digits |
| MM | Month (1-12), 1 or 2 digits |
| MMM | Month abbreviation, e.g. Jan, Feb |
| dd | Day of the month (1-31), 1 or 2 digits |
| HH | Hour (0-23), 1 or 2 digits |
| mm | Minute (0-60), 1 or 2 digits |
| ss | Second (0-60), 1 or 2 digits |
| SSS | Millisecond (0-999), 1-3 digits |
Other characters (such as ":", ",") are used as-is.
Some common examples:
| Format String | Description | Sample Data |
|---|---|---|
| HH:mm | Hour (24-hour clock) plus minute | 09:32, 23:06 |
| HH:mm:ss | Hour (24-hour clock) plus minute and second | 09:32:12, 23:06:01 |
| dd/MMM/yyyy:HH:mm | Apache log format (without second) | 07/Apr/2006:09:32 |
| dd/MM/yy HH:mm | Short date with 2-digit year, plus hour and minute. You must enclose this in double quotes (") on the command line because of the space in the format string. | 07/04/06 09:32 |
The colour override format (--colours option) allows a list of series indexes (0-based) and colours to be specified - any series index not overridden will use the standard clichart colours. Note that series indexes continue from the first axis to the second, so if you have 2 series on the first axis and one on the second, colour indexes 0 and 1 will refer to the first axis, and index 2 to the second.
Colours can be specified in one of 2 ways:
As a 3-byte hexadecimal number (case-insensitive) specifying the red, green and blue components, e.g. ff0000 for red. This is the same as the system used in HTML
By name, chosen from the following list (case-insensitive):
- black
- blue
- cyan
- darkgrey or darkgray
- grey or gray
- green
- lightgrey or lightgray
- magenta
- orange
- pink
- red
- white
- yellow
For example, to override the first and third series colours, you could use:
0:blue,2:ff00ff
Requirements to run clichart:
Clichart requires Java - see the installation page
The clichart script requires that either:
- You have the JAVA_HOME environment variable set correctly - the Java executable must be found at $JAVA_HOME/bin/java (Linux/UNIX) or %JAVA_HOME%\bin\java.exe (Windows), or
- The Java executable (java for Linux/UNIX or java.exe for Windows) is in you PATH.
Clichart can be used in 3 main modes
Interactive, where the chart is displayed in a window (the default), and
- Right-click on the chart to get the popup context menu
- The chart can be saved using the File | Save as menu item, pressing Control-S, or from the popup menu
- Most aspects of the chart's display can be controlled by using the Properties menu item on the popup menu. However, note that control of a second Y axis is not yet supported
- The popup menu also allows printing and zooming
- The window can be closed using the File | Exit as menu item, or pressing Control-Q
Automatic, where you provide a filename for saving the chart (using the -o option). Clichart will exit after the chart is generated
CLI server, where commands are passed via standard input, either from a script or a command file. See the CLI Server Mode section below.
Clichart is usually executed using the clichart wrapper script. The examples assume that you have used easy_install to install CLIChart, in which case the wrapper script is in your PATH. However, clichart can also be executed directly, by replacing clichart with java -jar clichart-0.5.0.jar (assuming you're using version 0.5.0).
PNG and JPEG image formats are supported for saving of charts, and these are determined based on the file extension, which must be .png, .jpg or .jpeg (case-insensitive). PNG is recommended, as the image files are smaller, and the images are clearer
Arguments containing spaces must be quoted, e.g. with double quotes. This is commonly required when setting chart or axis titles
On Windows, arguments containing colons must be quoted with double quotes. This is commonly required for the -d option, e.g. -d "HH:mm:ss"
Series titles for either axis are comma-separated, so the titles themselves cannot contain commas
If any two data points have the same X axis value, generation of the chart will fail (TODO: insert error message). Timestamps are evaluated to the second, so timestamps must be at least 1 second apart. Alternatively, use the -p option to ignore duplicate values
See the quick start guide for examples of using this tool.
If run in CLI server mode (with the --cliserver option), clichart reads commands from standard in, and responds to each successful command by writing a line starting with 'OK' to standard out. This allows another program, script or batch file to drive clichart to produce any number of charts, without the expense of launching clichart anew for each one. To use this mode, you must already have the tabular data available in files.
Each command consists of a command name and an optional argument, followed by a line ending (LF or CRLF). The command name is generally one of the options supported by clichart, either the short or long form, with the following exceptions noted below. Arguments for commands follow the same rules as for the options, except that everything after the command name to the end of the line is treated as the argument, so you shouldn't use quotes around multi-word arguments.
Differences between clichart options and CLI server commands are as follows:
- The path to the input file for the next chart is specified using the inputPath command, which takes the path to the (tabular data) input file as its argument. This is required
- The outputPath command is also required
- The go command forces generation of a chart using the current options
- Options are retained after generating a chart, so generating the next chart only requires changing the options that should change. The clear command resets the options to their defaults. Note: A number of clichart options do not have any way to reset them to their defaults other than using clear.
- Terminate the session by using the quit command, closing the calling program (e.g. using Ctrl-C), or closing the standard input stream
- For debugging purposes, use the debug-echo command, which echos all commands received to standard error
- Command names are not case-sensitive
- Blank lines and lines starting with # are ignored
- The following options cannot be used as commands: clichart, h and help
- The timeout command sets a timeout (in seconds). If the server does not get any commands within this time period, it will exit. This is intended to make the server mode more robust when used in long-running processes.
There are several different options for using CLI server mode. These include:
Probably the simplest mode of operation. Save all the required commands to a file, then pipe or redirect that file to clichart, e.g.
$ clichart --cliserver < someCommands.txt
Write a shell script or batch file that generates the commands to be run, and pipe the output to clichart. In this case, all output from clichart will appear on standard out, e.g.
$ head myscript.sh #!/bin/sh INPUT_DIR=some/dir echo "inputFile $INPUT_DIR/someData.csv" echo "outputFile someData.png" echo go ... # myscript.sh | clichart --cliserver OK OK OK OK
Here's a sample transcript of a CLI server session. You could run this in any of the ways listed above, but the example shows interacting via the console. Note that $ is the shell prompt in the example below, and all the OK lines are output by clichart, not entered by you. There is no prompt while interacting with the CLI server.
$ bin/clichart --cliserver OK inputpath samples/SystemTemps.csv OK outputpath /home/johnd/tmp/SystemTemps1.png OK csv OK hasheader OK title This is a chart of system temperatures OK go OK quit $