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

Structure-only 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.
context_menu "scalar or array" Contents of context menu to display for data item.
explode "scalar or array" Explosion amount for exploded pie graph slices, 1.0 being fully exploded.
Structure-only 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.

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.

Structure fields overriding global options - Hide table

FieldTypeDescription
data_label_angle "scalar or array" Text angle for data labels.
data_label_back_colour "scalar or array" Colour of label text border.
data_label_back_colour_outside "scalar or array" Alternative label text border colour.
data_label_colour "scalar or array" Text colour for data labels.
data_label_colour_outside "scalar or array" Alternative text colour for data labels.
data_label_fill "scalar or array" Data label background colour.
data_label_font "scalar or array" Font used for data labels.
data_label_font_adjust "scalar or array" Font adjust value for label text.
data_label_font_size "scalar or array" Font size for data labels.
data_label_font_weight "scalar or array" Font weight for data labels.
data_label_outline_colour "scalar or array" Edge colour for data labels.
data_label_outline_thickness "scalar or array" Line thickness for data labels.
data_label_padding "scalar or array" Space inside data label boxes.
data_label_padding_x "scalar or array" Horizontal space in data label box.
data_label_padding_y "scalar or array" Vertical space in data label box.
data_label_position "scalar or array" Position of data label.
data_label_round "scalar or array" Radius of data label corners.
data_label_shadow_opacity "scalar or array" Opacity of data label shadows.
data_label_space "scalar or array" The space between the label and the data item.
data_label_tail_end "scalar or array" Style of data label tail ending.
data_label_tail_end_angle "scalar or array" Angle of data label tail ending.
data_label_tail_end_width "scalar or array" Width of data label tail ending.
data_label_tail_length "scalar or array" Length of data label tails.
data_label_tail_width "scalar or array" Thickness of data label tails.
data_label_type "scalar or array" The style of label to use.
marker_angle "scalar or array" Sets a rotation angle for the markers.
marker_opacity "scalar or array" Sets the opacity of the markers.
marker_size "scalar or array" Size of markers.
marker_stroke_colour "scalar or array" Colour of marker outlines.
marker_stroke_width "scalar or array" Thickness of marker outlines.
marker_type "scalar or array" Shape of markers.
stroke_colour "scalar or array" Colour of graph lines.
stroke_dash "scalar or array" Dash pattern for graph lines, or NULL to draw solid lines.
stroke_width "scalar or array" Thickness of graph lines, 0 to disable drawing the lines.
Structure fields overriding 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:

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 »