Skip to topic | Skip to bottom
Home
 
TWiki
TWiki.ChartPluginr1.8 - 17 Nov 2004 - 01:56 - PeterThoenytopic end

Start of topic | Skip to actions

Chart Plugin (v1.401)

This plugin creates PNG or GIF charts to visualize TWiki tables using a default linear scale or an optional semilogarithmic scale.

Five types of charts, line, area, bar, scatter and combo, are currently available:

Type of Chart Name What it Does Example
Area area Shows a chart using areas under a line to represent the data
Bar bar Shows a chart using bars to represent the data
Line line Shows a chart using simple lines, points only, or lines with points to represent the data.
Note: Any areas that fall behind already drawn areas are drawn as lines to make them visible
Scatter scatter Shows a scatter chart (XY data points) and allows mixing area or bar with line, point, and pline
Combo combo Shows a chart combining the features from area or bar with line, point, and pline
Note: Formally known as arealine which is still supported

The %CHART{...}% variable gets expanded to an image representing the chart. Parameters and global settings determine the type of chart, dimensions, and values.

ChartPlugin Global Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, for example, %CHARTPLUGIN_SHORTDESCRIPTION%

  • One line description, shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Create PNG or GIF charts to visualize TWiki tables

  • Set DEBUG to 1 to get debug messages in data/debug.txt. Default: 0
    • Set DEBUG = 0

  • Default chart used: area, line, bar, scatter or combo. Default: line
    • Set TYPE = line

  • Default dimensions, scale and colors for a chart. See details in the syntax rules.
    • Set WIDTH = 400
    • Set HEIGHT = 250
    • Set AREA_COLORS = #FF3333, #FFFF33, #33FF33, #CC66FF, #99FFFF, #FFCC00, #008000, #FF8080, #3366CC, #800080
    • Set LINE_COLORS = #FF0000, #FFCC00, #00CC00, #FF00FF, #33CCCC, #FF8000, #009900, #FF6666, #3333FF, #800080
    • Set BGCOLOR = #FFFFFF, #FFFFFF

  • Define the grid color. When xgrid/ygrid = "on", then just use the first color when drawing grid lines. When their value is "dot", then use the full specification for drawing the grid lines ("transparent" can be used to introduce holes in the line).
    • Set GRIDCOLOR = #808080, #808080, #808080, transparent, transparent, transparent
    • Set NUMYGRIDS = 9

  • Define what to do when an empty table cell is found. "none" means assume no default value. A value of "10" would mean empty cells would be assumed to have a value of 10
    • Set DEFAULTDATA = none

  • Define the default scale: linear or semilog
    • Set SCALE = linear

  • Define the number of pixels wide lines are drawn with
    • Set LINEWIDTH = 3

  • Define the number of pixels (in both the X and Y directions) to use when drawing a point
    • Set POINTSIZE = 5

  • Define bar chart specific parameters. BARSPACE defines the space (in pixels) between bars. BARLEADINGSPACE defines the leading space (in pixels) before the first bar. BARTRAILINGSPACE defines the trailing space (in pixels) after the last bar
    • Set BARLEADINGSPACE = 6
    • Set BARTRAILINGSPACE = 6
    • Set BARSPACE = 5

Syntax Rules

The %CHART{...}% variable gets expanded to an image representing the chart.

  • Some parameters expect a range of table cells, using SpreadSheetPlugin syntax:
    • A table cell can be addressed as R1:C1. Cell addresses:
      R1:C1 R1:C2 R1:C3 R1:C4
      R2:C1 R2:C2 R2:C3 R2:C4
  • A range of table cells is defined by two cell addresses separated by "..". For example, "row 1-20, column 3" is: R1:C3..R20:C3 and "row 15-5, column 2" is: R15:C2..R5:C2

%CHART% Parameter Comment Default
type The type of chart to create. One of "area", "bar", "line", "scatter", "combo" Global TYPE setting
subtype Sub type of chart. Supported values depend on chart type:  
^ - for type="area" =   subtype="area" "area"
^ - for type="bar" =    subtype="bar" "bar"
^ - for type="line" =   subtype="line, point, pline" (point line) "line"
^ - for type="scatter" subtype="area, bar, line, point, pline"
Note: you cannot mix area and bar on the same chart.
Note: It is not recommended using showing a bar on a scatter chart as the X axis placement is skewed with bar and will not exactly line up with drawn X axis values which will defeat the purpose of using scatter in the first place.
"point"
^ - for type="combo"   subtype="area, bar, line, point, pline" (note: you can not mix area and bar on the same chart) All but the last data set are drawn as "area" and the last is drawn as "line"
^ You can use a comma delimited list of values to set a specific subtype for each data set. For example "area, area, point, line" would say that the first two data sets are areas, the third is point and the last one is a line  
scale The scale to use when creating the chart. "linear" or "semilog" Global SCALE setting
name Name to uniquely identify the chart file that is auto-created. None; is required for all charts
web The web in which to find topic (specified below) in which to find the TWiki tables The current web
topic The topic in which to find the TWiki tables The current topic
table TWiki table used to build the chart. A numerical value refers to the table number, where "1" is the first table seen in a topic. Any other non-numeric string refers to a named table defined by the TABLE variable with a name parameter. For example, table="trends" refers to the table that is preceded by %TABLE{ name="trends" }%. "1"
title The title placed at the top of the chart None
xlabel The label placed under the X axis describing the X values None
ylabel The label placed to the left of the Y axis describing the Y values None
data The source data to build the chart, defined as a range of table cells. For example for type="line", a data="R2:C3..R999:C6" would say that four lines were to be drawn with first line being rows 2-999 column 3 and last line being rows 2-999 column 6. None; is required for all charts
defaultdata If there is sparse data, then use the value specified by defaultdata to fill in the missing data. A value of "none" means only draw actual data points. Global DEFAULTDATA setting
xaxis X-Axis labels: The values are defined as a range of table cells. In case of scatter graph, xaxis represents the actual X values. The range also defines the orientation -- row or column oriented (if specified). For example "R2:C2..R999:C2" would take all of column 2 starting at row 2 and going through row 999. It would also denote that all remaining data is oriented columnar. None. Is required for type="scatter". If not specified, then no X axis labels shown and data assumed to be in columnar format.
xaxisangle Angle the X-Axis labels are drawn. Only two angles are supported at this time, "0" draws horizontal labels, other numbers draw vertical labels "0"
yaxis Y-Axis labels: "on" to show the labels, "off" for no labels. "off"
ymin Minimum value drawn on the Y axis The minimum value specified by data
ymax Maximum value drawn on the Y axis The maximum value specified by data
xgrid Grid shown for X axis: "on" for solid grid lines, "dot" for dotted grid lines, "off" for none. "dot"
ygrid Grid shown for Y axis: "on" for solid grid lines, "dot" for dotted grid lines, "off" for none. "dot"
numygrids Number of Y axis grids drawn Global NUMYGRIDS setting
ytics Number of tic marks to draw between Y axis grid lines. If scale="semilog", then ytics="10", else defaults to "0"
numxgrids Number of X axis grids drawn. This can be used if there are a large number of X axis data points such that the X axis labels overlap. Draw all X-Axis labels
datalabel Show data labels: "on" for labels, "box" for label in a box, "off" for none. It can also be a list like "off, off, off, box" to show values in a box for the fourth set of data points only. "off"
legend Legend shown to the right of the chart. For example "R1:C3..R1:C6" would take all of row 1 starting at column 3 and going through column 6 as the name/legend of each set of data points None; no legend if not specified
width Defines the overall width of the chart in pixels. Global WIDTH setting
height Defines the overall height of the chart in pixels. Global HEIGHT setting
alt Alternate text for chart image Empty alt tag
colors A list of colors defining the color of each set of data points. Global LINE_COLORS setting for lines; global AREA_COLORS setting for area
bgcolor Background color of the area surrounding the chart. For example, "#E7E7E7" sets a light gray background. Optionally specify a second values for the chart background itself. For example, "#E7E7E7, #FFFFC0" defines a chart with a light yellow background on a light gray surrounding. Global BGCOLOR setting
gridcolor Colors/style of the grid (if any). If xgrid or ygrid = "on" then use the first gridcolor for drawing solid grid lines. If xgrid or ygrid = "dot", then use the full set of colors to define the line style for drawing the grid lines ("transparent" can be used to introduce holes in the line)" Global GRIDCOLOR setting
linewidth Width of data lines in pixel Global LINEWIDTH setting
pointsize Size of data points in pixel Global POINTSIZE setting
(other parameters) Other parameters are passed on to the img tag. Useful to add additional image parameters like align="right" None

Note: To support legacy syntax, datatype maps to subtype, arealine maps to combo.

Examples

Assuming the following three TWiki tables. The first shows the data oriented in columns while the seconds shows the data oriented in rows

Table 1: %TABLE{name="exampleTable1"}%
Year Actual
1998 9
1999 14
2000 19
2001 25
2002 39

  Table 2: %TABLE{name="exampleTable2"}%
Year 1998 1999 2000 2001 2002
Low 8 10 13 17 22
Target 10 12 17 20 25
High 12 15 19 24 29
Actual 9 14 15 19 27

  Table 3: %TABLE{name="exampleTable3"}%
X Y1 Y2 Y3
3 1 3 7
6 5 8 10
11 3 5 9
10 1 3 7
8 2 3 8

Type of chart You type You should get... ...if installed
area Multiple area

%CHART{ type="area" name="area1" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%
ChartPlugin error: Required Perl module 'GD' not found
bar Multiple bars

%CHART{ type="bar" name="bar1" table="exampleTable2" data="R3:C2..R5:C4" xaxis="R1:C2..R1:C4" legend="R3:C1..R5:C1" ymin="0" width="225" height="200" }%
ChartPlugin error: Required Perl module 'GD' not found
line Simple line

%CHART{ type="line" name="line1" table="exampleTable1" data="R2:C2..R6:C2" xaxis="R2:C1..R6:C1" legend="R1:C2..R1:C2" width="225" height="200" }%
ChartPlugin error: Required Perl module 'GD' not found
line Multiple lines

%CHART{ type="line" name="line2" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%
ChartPlugin error: Required Perl module 'GD' not found
scatter Multiple scatter

%CHART{ type="scatter" subtype="pline" name="scatter1" table="exampleTable3" data="R2:C2..R6:C4" xaxis="R2:C1..R6:C1" legend="R1:C2..R1:C4" numxgrids="4" linewidth="1" width="225" height="200" }%
ChartPlugin error: Required Perl module 'GD' not found
combo Combo with area, pline, point, & line

%CHART{ type="combo" subtype="area, pline, point, line" name="combo1" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%
ChartPlugin error: Required Perl module 'GD' not found
combo Combo with bar, pline, point, & line

%CHART{ type="combo" subtype="bar, pline, point, line" name="combo2" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%
ChartPlugin error: Required Perl module 'GD' not found

The "if installed" column shows images instead of variables in case the plugin is installed correctly.

Output

  • A graphics file in PNG or GIF format is created containing the chart results. The file is placed in %PUBURLPATH%/%WEB%/%TOPIC%/_ChartPlugin_<type>_<name>.png or .gif (GIF for GD version 1.19 or older)
  • %CHART{...}% gets expanded to an <img ... /> image tag.

Error Handling

If the required parameters are not defined, then an error message is returned or an <img ... /> image tag is returned pointing to a graphic containing the error message.

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

  • Download the ZIP file from the Plugin web (see below)
  • Unzip ChartPlugin.zip in your TWiki installation directory. Content:
    File: Description:
    data/TWiki/ChartPlugin.txt Plugin topic
    data/TWiki/ChartPluginTests.txt Test page containing many examples of the ChartPlugin in action. Also shows various error conditions
    data/TWiki/ChartPluginTestsRemote.txt Topic containing remote tables referenced by ChartPluginTests
    pub/TWiki/ChartPlugin/line1.png Sample line image
    pub/TWiki/ChartPlugin/line2.png Sample line image
    pub/TWiki/ChartPlugin/area3.png Sample area image
    pub/TWiki/ChartPlugin/scatter1.png Sample scatter image
    pub/TWiki/ChartPlugin/combo1.png Sample combo image
    pub/TWiki/ChartPlugin/combo2.png Sample combo image
    pub/TWiki/ChartPlugin/lineexample.png Sample line image
    pub/TWiki/ChartPlugin/areaexample.png Sample area image
    pub/TWiki/ChartPlugin/scatterexample.png Sample scatter image
    pub/TWiki/ChartPlugin/comboexample.png Sample combo image
    lib/TWiki/Plugins/ChartPlugin.pm Plugin Perl module
    lib/TWiki/Plugins/ChartPlugin/Chart.pm Chart library Plugin Perl module
    lib/TWiki/Plugins/ChartPlugin/Table.pm Table library Plugin Perl module
    lib/TWiki/Plugins/ChartPlugin/Parameter.pm Parameter library Plugin Perl module
  • If you see Permission denied errors, verify that ownership and permissions are correct for the following making sure that ownership and permissions match existing directories ownerships and permissions:
    • pub/TWiki/ChartPlugin
  • Test if the plugin is correctly installed:
    • Check above examples if the "if installed" column shows images instead of variables.
    • Check ChartPluginTests for some more tests

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny, TWiki:Main.TaitCyrus
Plugin Version: 16 Nov 2004 (V1.401)
Change History:  
16 Nov 2004: V1.401 - Added benchmarks (no code changes)
30 Aug 2004: V1.400 - Added support for subtype="bar" (includes various global bar settings), updated gridcolor to not only define the grid color but allowing the user to define the line style (for drawing user defined dotted lines), add a global for how wide lines are drawn instead of a hard coded value, change the order of how things are drawn so now the order is: areas, grid lines and X/Y axis labels, bars, lines/points/plines, rectangle around chart, data point labels, chart title/X/Y labels, and finally the legends.
13 May 2004: V1.300 - Added support for type="scatter"; renamed type="arealine" to "combo" (arealine is undocumented); renamed datatype to subtype (datatype is undocumented); added subtype options "point" and "pline", added new settings GRIDCOLOR, DEFAULTDATA, POINTSIZE; fixed bug with how the number of grids were drawn
17 Oct 2003: V1.201 - Fix boundary cases with semilog scale
16 Oct 2003: V1.200 - Add new options of scale and ytics.
16 Jun 2003: V1.100 - Add support for reversed tables (R999..R1), add new options of xaxisangle, numxgrids, and defaultdata, and allow sparse data.
7 Oct 2002: V1.003 - Improved performance, fixed bugs with color allocation, auto-legend placement and parsing of numbers in tables. Also bumped the upper value when numbers switch from decimal format to engineering format
13 Sept 2002: V1.002 - Add support for better placement of legends so they don't overlap, add auto ymin/ymax determination if not specified, add bgcolor and numygrids options
27 Jun 2002: V1.001 - Data range specified is clipped to actual table size; more forgiving data parsing by extracting first numeral from a table cell, e.g. extract 25 from <u>25%</u>
20 Jun 2002: Initial version (V1.000)
CPAN Dependencies: GD from http://stein.cshl.org/WWW/software/GD
| Other Dependencies: | gd library from http://www.boutell.com/gd (Tested with 1.8.4)
PNG graphics library from http://www.libpng.org/pub/png|
Perl Version: 5.005
TWiki:Plugins/Benchmark: GoodStyle 96%, FormattedSearch 97%, ChartPlugin 69%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/ChartPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/ChartPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/ChartPluginAppraisal

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.TaitCyrus - 3 June 2004
-- TWiki:Main.PeterThoeny - 16 Nov 2004
to top


You are here: TWiki > ChartPlugin

to top

All content is Copyright © 1999-2023 by, and the property of, the contributing authors.
Questions, comments, or concerns? Contact GNHLUG
Legal Notice (includes Terms of Service)