SVGGraph structured data

« Return to SVGGraph page

Skip to:

• Structure fields
• Examples

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:

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.

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'
);

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 many of the graph types. Not all fields are relevant to all graph types, but unused (or unrecognised) fields are ignored.

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.

The table below lists the global options that are also available for use as structured data keys. Values specified in structured data override global options.

The example structure below shows the required key and value fields, along with structured-only and overriding fields.

$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
  'stroke_colour' => array('c1', 'c2'),      // draw the outline using colours from 'c1' and 'c2' fields
  '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:

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).

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.

* PHP will happily accept an array that has floating point values as keys, but it will quietly truncate all the keys to integer values.

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.

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 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.

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 »

Copyright © 2020, Goat 1000