SVGGraph structured data

« Return to SVGGraph page

Skip to:

Version 2.11 of SVGGraph adds a new method for supplying graph data, which makes it easier to specify values for multiple data sets and also allows for settings tooltips, colours and other options for each item on the graph.

Structured data format is more like you would get straight from a database in tabular form:

IdNameAgeHeight
1Bob51160
2Alice45165
3Frank32182
4Susan35185

Performing a SELECT * FROM my_table could give you this array:

// structured data version of table
$values = array(
  array('Id' => 1, 'Name' => 'Bob', 'Age' => 51, 'Height' => 170),
  array('Id' => 2, 'Name' => 'Alice', 'Age' => 45, 'Height' => 175),
  array('Id' => 3, 'Name' => 'Frank', 'Age' => 32, 'Height' => 182),
  array('Id' => 4, 'Name' => 'Susan', 'Age' => 35, 'Height' => 185)
);

Now to draw a bar graph of heights, you can set the structure:

$settings['structured_data'] = true;
$settings['structure'] = array(
  'key' => 'Name',
  'value' => 'Height'
);

Or to draw a multi-scatter graph with heights and ages:

$settings['structured_data'] = true;
$settings['structure'] = array(
  'key' => 'Name',
  'value' => array('Height', 'Age')
);

The graphs generated with these structures are shown below.

BarGraph - height
MultiScatterGraph - height and age

You could have a scatter graph with ages along the X axis, heights on the Y axis and with the name field as the tooltip using this structure:

$settings['structured_data'] = true;
$settings['structure'] = array(
  'key' => 'Age',
  'value' => 'Height',
  'tooltip' => 'Name'
);
ScatterGraph - height against age
FloatingBarGraph - from age to height

The last example above is a floating bar graph showing the difference between age and height - I don't think this particular graph is very useful, but it does demonstrate using a graph that requires extra data:

$settings['structured_data'] = true;
$settings['structure'] = array(
  'key' => 'Name',
  'value' => 'Age',
  'end' => 'Height' // required for FloatingBarGraph
);

Using structured data

There are two options that are important for structured data. The first is structured_data - settings this to true enables the use of structured data. The second option is structure - this maps the fields in the data to the pieces of information that SVGGraph uses. Setting the structure option implicitly enables structured data. Both of these options should be set in the array of settings passed to the SVGGraph constructor.

Structure fields

These are the structure fields that are common to the many of the graph types. Not all fields are relevant to all graph types, but unused (or unrecognised) fields are ignored.

Structure fields - Hide table

FieldTypeDescription
key scalar (required) The key field. This is the X-coordinate for cartesian graphs.
value scalar or array (required) The value field(s). A single field name or number, or an array of them for multiple datasets. This is the Y-coordinate for cartesian graphs.
link scalar or array URL to link the item (bar/marker/pie slice) to.
tooltip scalar or array Text to be displayed in the tooltip for the data item.
colour scalar or array Colour of the bar, pie slice or marker.
axis_text scalar Text to display on the X-axis instead of the key field.
legend_text scalar or array Text to display in the legend.
label scalar or array Pie graph and bar graph labels.
stroke_colour scalar or array Colour of line around bar or pie slice.
stroke_width scalar or array Thickness of line around bar or pie slice.
stroke_dash scalar or array Dash pattern of line around bar or pie slice.
marker_type scalar or array Marker type for scatter, line and radar graphs.
marker_size scalar or array Marker size for scatter, line and radar graphs.
marker_stroke_width scalar or array Marker stroke width for scatter, line and radar graphs.
marker_stroke_colour scalar or array Marker stroke colour for scatter, line and radar graphs.
Structure fields

In this table “scalar” means either a string or integer - whichever type the keys in your data array use. Fields that accept arrays should have a scalar value for each dataset, as specified in the value field, or a single scalar value to be used for all datasets. A NULL entry may be used in an array field to specify that a dataset should not have a tooltip, label, etc.

$settings['structure'] = array(
  'key' => 'Id',
  'value' => array('Sales', 'Expenses'),
  'tooltip' => array(null, 'Expense types'), // no tooltip for 'Sales' field
  'link' => 'Url',                           // both datasets use link to 'Url' field
  'my_data' => 'Comments'                    // no 'my_data' structure field, ignored
);

The graph types on the other graphs page have extra field requirements to display more information.

Default structure

When structured_data is enabled and the structure option is not set, SVGGraph uses a default structure that it determines from the data.

The first entry in the first data array is assumed to be the key field, and all other fields are used as value fields.

// structured data array
$values = array(
  array('Name' => 'Bob', 'Age' => 40, 'Height' => 180),
  array('Name' => 'Sam', 'Age' => 32, 'Weight' => 65),
);

Using this data array with structured_data set to true and structure not set, SVGGraph will use this structure:

// implied structure
$settings['structure'] = array(
  'key' => 'Name',
  'value' => array('Age', 'Height', 'Weight')
);

Example 1: Simple graph data

In the most simple example, structured data does not appear to provide any advantages over the plain data format:

// old-style plain data format
$values = array(30, 60, 50, 40, 90, 50, 60, 20);
 
// structured data
$values = array(
  array(0, 30), array(1, 60), array(2, 50), array(3, 40),
  array(4, 90), array(5, 50), array(6, 60), array(7, 20)
);

There should be no difference between the graphs drawn with each type of data:

BarGraph - plain data
BarGraph - structured data

The data is using the default structure, where the first entry in the array is taken to be the key field, and the following entries are assumed to be value fields. Because the keys are inside the inner arrays, the same key may be repeated multiple times for graphs that support data with repeated keys (mainly scatter graphs).

ScatterGraph - repeated keys
ScatterGraph - float keys

PHP does not support floating-point values as array keys, so using structured data also allows for decimals in the key fields - how they are used depends on the graph type.

// repeated keys
$values = array(
  array(1, 30), array(1, 60), array(2, 50), array(3, 40),
  array(3, 90), array(6, 50), array(6, 60), array(7, 20)
);
 
// float keys
$values = array(
  array(0.25, 30), array(1.6, 60), array(2, 50), array(M_PI, 40),
  array(4, 90), array(5.1, 50), array(6.5, 60), array(7, 20)
);

These simple examples are identical to the format used in the scatter_2d format supported by the scatter graphs. Using the old scatter_2d option now enables structured data using a very simple structure.

Example 2: multiple datasets

The stacked and grouped bar graphs, multi-line and multi-scatter graphs all use multiple datasets:

// old-style plain data format
$values = array(
  array(30, 60, 50, 40, 90, 50, 60, 20),
  array(20, 20, 40, 30, 20, 10, 30, 15)
);
 
// structured data
$values = array(
  array(0, 30, 20), array(1, 60, 20), array(2, 50, 40), array(3, 40, 30),
  array(4, 90, 20), array(5, 50, 10), array(6, 60, 30), array(7, 20, 15)
);

Again, this might not seem like much of an advantage. Internally, the multi-dataset graphs convert the old format into structured data because it is easier to work with.

GroupedBarGraph - plain data
GroupedBarGraph - structured data

These two graphs should be identical. The default structure is used for the data, so the key field is 0 and the value field is array(1, 2).

Example 3: links, tooltips, labels, colours and axis_text

These last couple of example graphs show the other fields in use, so the data array and structure are a bit more complicated:

$values = array(
  array(
    "January", 10, 30, "svggraph-using.php", "svggraph-embed.php",
    "Ten\nItems", "Bob", "**", "#f00", "#f0f"
  ),
  array(
    "February", 6, 20, "svggraph.php", "svggraph-settings.php",
    "Six\nItems", "Anne", "*", "#f63", "#63f"
  ),
  array(
    "March", 13, 18, "svggraph-bar.php", "svggraph-bar3d.php",
    "Thirteen\nItems", "Sue", "***", "#f93", "#93f"
  ),
  array(
    "April", 16, 22, "svggraph-horizontal.php", "svggraph-line.php",
    "Sixteen\nItems", "Frank", "***", "#fc0", "#c0f"
  ),
  array(
    "May", 18, 25, "svggraph-radar.php", "svggraph-scatter.php",
    "Eighteen\nItems", "Alan", "****", "#9c0", "#63c"
  ),
  array(
    "June", 16, 28, "svggraph-pie.php", "svggraph-misc.php",
    "Sixteen\nItems", "Vera", "***", "#3f0", "#00f"
  )
);
 
$settings['structure'] = array(
  'key' => 0,
  'value' => array(1, 2),
  'link' => array(3, 4),
  'tooltip' => array(5, 6),
  'label' => array(7, 6),
  'colour' => array(8, 9)
);

These are the data values and structure used for StackedBarGraph 1 below. The data contains a month string in position 0 for the key field, two data sets in positions 1 and 2, two link fields in positions 3 and 4, tooltip text in positions 5 and 6, label text in position 7, with the text in position 6 reused for the second dataset label, and colours in positions 8 and 9.

StackedBarGraph 1
StackedBarGraph 2

StackedBarGraph 2 is almost the same as the first one, but I've added in the axis_text field as the 10th entry in the array. The main advantage of using axis_text over changing the key field is that axis_text can repeat the same value as many times as you like on any of the grid-based graph types. You can also leave out a value for the axis text to not show anything on the X-axis for that entry.

$values = array(
  array(
    "January", 10, 30, "svggraph-using.php", "svggraph-embed.php",
    "Ten\nItems", "Bob", "**", "#f00", array("#f0f", "#303"), "J"
  ),
  array(
    "February", 6, 20, "svggraph.php", "svggraph-settings.php",
    "Six\nItems", "Anne", "*", "#f63", array("#63f", "#00c"), "F"
  ),
  array(
    "March", 13, 18, "svggraph-bar.php", "svggraph-bar3d.php",
    "Thirteen\nItems", "Sue", "***", "#f93", array("#93f", "#306"), "M"
  ),
  array(
    "April", 16, 22, "svggraph-horizontal.php", "svggraph-line.php",
    "Sixteen\nItems", "Frank", "***", "#fc0", "#c0f", "A"
  ),
  array(
    "May", 18, 25, "svggraph-radar.php", "svggraph-scatter.php",
    "Eighteen\nItems", "Alan", "****", "#9c0", "#63c", "M"
  ),
  array(
    "June", 16, 28, "svggraph-pie.php", "svggraph-misc.php",
    "Sixteen\nItems", "Vera", "***", "#3f0", array("#00f", "#003"), "J"
  )
);
 
$settings['structure'] = array(
  'key' => 0,
  'value' => array(1, 2),
  'link' => array(3, 4),
  'tooltip' => array(5, 6),
  'label' => array(7, 6),
  'colour' => array(8, 9),
  'axis_text' => 10
);

The other difference in this graph is that I have changed a few of the plain colours to gradients by using arrays of colours. Setting colours from the values array is very useful, but it can cause a mismatch with the colours shown in the legend if you have enabled it.

Example 4: legend_text

This option was added in version 2.22 to solve the problems of using the legend_entries option to display a legend when structured data is used to set the styles of items. The example stacked bar graph below uses legend_text to set the legend entries for the first dataset.

StackedBarGraph with legend

This graph is using the same $values array as in the previous graph, but with one extra line added to the structure:

$settings['structure'] = array(
  'key' => 0,
  'value' => array(1, 2),
  'link' => array(3, 4),
  'tooltip' => array(5, 6),
  'label' => array(7, 6),
  'colour' => array(8, 9),
  'axis_text' => 10,
  'legend_text' => array(0, null)
);

The legend_text field is set to array(0, null), so the legend entry for the first dataset comes from field 0, which is also the key field, and the NULL means no entries are added for the second dataset.

« Back to top of page General settings »