Ico is a JavaScript graph library that uses Raphaël to render graphics. This means Ico can render charts in the vast majority of modern web browsers, using VML in IE (< 9), or SVG in SVG standard-compliant web browsers such as IE 9, Firefox, Apple Safari, Google Chrome, Opera, and Konqueror for Linux. Also because Raphaël does not rely on Flash, it works well (and is tested) on iPhone.

Ico’s goal is to provide effective visual reprensentation of data according to the work of Stephen Few and Edward Tufte. In particular, Ico provides an implementation of Edward tufte’s Sparklines and Stephen Few’s Bullet Graphs.

Effective visual reprensentation of data can be achieved by following Stephen Few’s graph design considerations:

• Clarity: Use of white-space to help lend clarity to graphs, nominal scale vs. ordinal scale
• Simplicity: Minimal use of decorations and lines, reliance on the Gestalt principle of closure
• Conciseness: Avoidance of graph types that don’t efficiently present data (pie charts, radar maps)

Ico’s core provides the set of graphs and features to achieve this goal:

• Sparklines, Sparbars, and Bullet Graphs
• Line graphs
• Horizontal and Vertical Bar Graphs

This version of Ico is designed to be extensible beyond its core by providing either new graph types or new graph components. A graph component automatically becomes available to all graph types.

The original version of Ico was written by Alex Young. The current version features a new API, mainly due to componentization of many graph features, comprehensive documentation, many bug fixes, new features, most importantly implements bullet graphs, angled labels, gradient backgrounds, proper negative bar graphs rendering. For a complete list of modifications read the release notes.

To see a demonstration of the capabilities of the current version, check the current test suite in index.html.

Unfortunatly tests cannot be automated because it is primaraly about rendering in supported web browsers, most of which do not provide an API suitable for test suites. The test suite is a set of graphs showing most of Ico features. This test suite is meant to be viewed in all supported web browsers where the following tests are performed:

• scroll up and down, mouse over graphs
• zoom page, mouse over graphs
• check for font display defects such as characters mis-alignments
• measure the time to render the entire test suite page

Ico requires:

• Raphaël
• Prototype only if the mouse_pointer component is used

Simple sparkline, no decoration:

new Ico.SparkLine(
  "market_trend_id",                                // DOM element where the sparkline is rendered
  [5, 2, -1, 17, 23, 15, 7, 6, -5, -2, 4, 7, 3, 9]  // List of values for market trend
)

Bullet graph with 3 graph background colors and gradient transtitions:

new Ico.BulletGraph(
  "gross_profit_id",      // DOM element where the bullet graph will be rendered
  85,                     // Actual gross profit for current period as a percentage of gross revenues
  {                       // Bullet graph options
    min: 0,               // Minimum gross profit value
    max: 100,             // Maximum gross profit value
    target: 65,           // Forecasted gross profit value
    graph_background: {   // Defines graph background for gross profit
      key_values: [50, 75],               // Less than 50% is bad, more than 75% is good, in between is ok
      key_colors: ['#555','#999','#ddd'], // The 3 colors representing the 3 quality zones
      colors_transition: 10               // 10% Gradient transition between the different zones
    }
  }
)

Line graph with 2 lines, angled labels, $ units, meanline, mouse pointer, mouse-over value in status bar, and grid:

var months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
new Ico.LineGraph(
  "gross_profit_id",                               // DOM element where the graph will be rendered
  [                                                // The 2 series
    [31, 5, 1, -5, 15, 33, 20, 25, 1, 12, 25, -3], // Drawn first
    [18, -1, -7, 17, 15, 21, 1, 25, 3, 21, 16, 4]  // Drawn last, on top of previous series
  ],
  {                                                // Graph components' options
    colors: ['#228899', '#339933' ],               // Series' colors
    curve_amount: 10,                              // Slightly curve series' lines path using Cubic Bézier
    mouseover_attributes: { stroke: 'green' },     // When hovering over values
    font_size: 16,                                 // for both labels and value labels and other elements
    labels: { values: months, angle: 30 },         // Set labels at a 30 degres angle
    x_padding_right: 40,                           // Make more room on the right to properly display labels
    units: '$',                                    // $ units to display values
    units_position: 0                              // Render $ before values
    value_labels: {                                // Controls value labels
      marker_size: 4                               // Value labels markers set to 4 pixels instead of 5
    },
    background: { color: '#ccf', corners: 5 },     // Set entire div background color and corner size 
    meanline: true,                                // Display mean value of all series
    grid: true,                                    // Display a grid from labels and value labels
    mouse_pointer: true,                           // Display a cross mouse pointer in graph area
    status_bar : true,                             // Display status bar to show values on mouse over
  }
)

See index.html for more examples.

Graph classes provide defaults components appropriate for each type of graph:

To create and render a graph, call new Ico.desired_graph_type, providing three parameters:

• The DOM element where the graph will be rendered
• Data series
• Options (optional)

Example creating and rendering a line graph:

new Ico.LineGraph( dom_element, data_series, graph_options )

The DOM element can be provided as a DOM Element object:

new Ico.LineGraph( $( "sales" ), data_series, graph_options )

The DOM element can also be specified using a string containing a DOM id:

new Ico.LineGraph( "sales", data_series, graph_options )

Data series can provided as:

• A single value (for a bullet graph only)
• An array of values for a single data serie
• An array of array of values for multiple series data

Examples:

// A single value for a bullet graph
data_series = -20


// An array of values for a single serie graph
data_series = [5, 2, -1, 17, 23, 15, 7, 6, -5, -2, 4, 7, 3, 9]


// An array of arrays of values for multiple series graphs
data_series = [
  [31, 5, 1, -5, 15, 33, 20, 25, 1, 12, 25, -3],
  [18, -1, -7, 17, 15, 21, 1, 25, 3, 21, 16, 4]
]

Options are provided as a hash of options where each key is the option name and each value is the option value. Options hashes can be nested typically to group options by components.

Many options are Raphaël attributes which rely on the SVG Specification so please refer to these documents when further information is needed.

Example of options:

graph_options = {                     // Graph components' options
  colors: ['#228899', '#339933' ],               // Series' colors
  curve_amount: 10,                              // Slightly curve series' lines path using Cubic Bézier
  mouseover_attributes: { stroke: 'green' },     // When hovering over values
  font_size: 16,                                 // for both labels and value labels and other elements
  labels: { values: months, angle: 30 },         // Set labels at a 30 degres angle
  x_padding_right: 40,                           // Make more room on the right to properly display labels
  units: '$',                                    // $ units to display values
  units_position: 0                              // Render $ before values
  value_labels: {                                // Controls value labels
    marker_size: 4                               // Value labels markers set to 4 pixels instead of 5
  },
  background: { color: '#ccf', corners: 5 },     // Set entire div background color and corner size 
  meanline: true,                                // Display mean value of all series
  grid: true,                                    // Display a grid from labels and value labels
  mouse_pointer: true,                           // Display a cross mouse pointer in graph area
  status_bar : true,                             // Display status bar to show values on mouse over
}

The following are options shared by all graphs:

Ico.BaseGraph is used as a base for more complex graphs possibly with multiple series whereas sparklines and sparkbars are limited to one serie.

Ico.BaseGraph extends Ico.Base with more default features such as value_labels, focus_hint and axis enabled by default.

The following options apply as defaults for bar and Line graphs unless overrided:

Graph features are driven by components. Each graph type defines different default components and graph orientation (horizontal or vertical) and other graph-specific options. Default components can be disabled by explicitly setting their option attribute to false.
Each component is shown with the name of its options attribute hash:

Component options can be set with the following types of values:

• false => disable feature, useful when a graph type sets the option by default
• true => get default options for the component
• hash => attributes for the component

If a hash is provided and one of the options name is ‘attributes’, it is a hash of Raphaël attributes. Attribute option tables bellow define only the subset of Ico default attributes although all valid Raphaël attributes can be used.

Labels are series’ samples labels, while value labels are numerical labels associated with series’ data.

Labels are defined by the option attribute ‘labels’. If an array is provided, it reprensents the values of the labels. If more label options are provided, labels must be provided as a hash of options.

Label components always make room for themselves in the padding areas.

Values labels are always calculated. The calculation is optimized according to the following criteria:

• If zero is in the range (between min and max values), zero is always one of the value labels
• The maximum number of value labels is limited by the size of the graph area, the font, angle and orientation of the graph
• The number of labels is chosen to minimize unused areas to maximize the size of displayed data series
• The step beetween two value labels has a maximum of 2 significant digits and is a multiple of 5 if the 2 significant digits are required
• Values labels are limited to 3 significant digits using string manipulations to avoid floating-point rounding errors
• Once value labels are calculated, precision is fixed, possibly adding zeros to nicely align labels
• Finally, appropriate padding is added to make room for calculated labels using just as much space as neccesary and according to labels angle

The graph area is the area where data series are rendered. This does not include padding areas where labels and other graph features are rendered.

The graph_background option attribute, if present allows to display a grandient of colors in the graph area. The gradient is drawn along the value labels axis to add meaning to ranges of values. The default gradient meaning represents ranges where the values are ‘bad’, ‘acceptable’, and ‘good’. The actual meaning of these background colors is application-specific and the same colors could mean ‘small’, ‘average’, and ‘tall’ or any other meaning.

The graph_background attribute can be set to true to get the default background or a hash to provide specific attributes:

The background is the entire Raphaël canvas area.

If the ‘grid’ option attribute is provided it can be set to true or a hash of additional options.

All Raphaël Element Attributes are valid, only listed here are those whith default values:

If the ‘axis’ option attribute is provided it can be set to true or a hash of additional options:

If the ‘meanline’ attribute option is set to true or a hash of additional attributes, Ico calculates the mean of all values of all series and displays this mean value as line parallel to labels’ axis.

A focus hint is displayed as two short lines crossing the value labels axis if the value range does not include zero in order to attract the attention of the users that the graph does not start at zero nor contains zero.

If the ‘mouse_pointer’ attribute option is set to true or a hash, a mouse pointer is displayed when the mouse is over the graph area as a cross spanning the entire width and height of the graph area.

If the ‘status_bar’ attribute option is set to true or a hash, value are displayed on mouse over in the top padding area.

• Firefox: best compromize of quality and speed, some rendering problems of angled fonts
• IE: best angled fonts rendering, slowest by far
• Safari: fastest, bugs: while zooming
• Google Chrome: good quality, bugs: while zooming
• iPhone (Safari): pretty amazing, try it
• Opera: good fonts rendering, bugs: zoom, mouse-over while scrolling

This section outlines the projected improvements for upcoming releases.

Features:

• Display Value Labels Title either above the y axis, in the status bar or under value labels if horizontal graph
• Allow greater control of labels positioning: left-justification, top, right
• By default Draw labels on top (or right if orientation) if all values are negative
• Enable values formatting with a function to allow custom numbers formatting, provide default formatters
• Allow single axis (x or y) to be displayed
• Display values in tooltips instead of status bar, tooltips implemented w/ an external DOM library to enable out-of-the-canvas tooltips
• Zoom-in spark lines, spark bars, and bullet graphs on-mouse-over.
• Display full graph of spark lines and spark bars on mouse-click, possibly in a tooltip
• Facilitate user events definition on graph elements
• Add zero line component to draw a line at zero when zero in the range. This can be done today by adding a dummy serie but this would make it easier.

Architechture:

• Componentize series in a Ico.Serie class to allow bars and lines in the same graph but also to allow new types of data series rendering

Documentation:

• Ico box model
• methods beyond intitialization
• (for contributors) Graph and Components extensions