SVGGraph guide or target lines
Sometimes you want to mark a line on a graph to show where the values should be, or where the historical mean average, minimum or maximum values are - these are generally called "target lines", though I started calling them "guide lines" during development when I didn't know what they were called, and I've decided to stick with it.
Guide lines are available from version 2.7 of SVGGraph, and are supported by all bar, line and scatter graph types.
How to use them
As with most other things that modify the appearance of graphs, guide lines
are configured in the PHP
$settings array that is passed to the
The main option that configures the lines is
guideline - this
accepts several different formats to configure the guide lines. The first
format accepts a single value that specifies the Y-axis position of the
$settings = array("guideline" => 10);
The value for where to draw the line uses the same scale as the values
you provide to SVGGraph using the
Values function - you don't
need to calculate the position in pixels or anything complicated.
The second format that SVGGraph accepts is an array of options, the first being the value, the second being a title to be displayed with the guide line and the third is the axis that the line is on:
$settings = array( "guideline" => array(10, "Target", "y") );
Both the title and the axis are optional, so passing
will give you the same result as just passing
10 by itself. The
title may contain line breaks to split the title over mupltiple lines.
The axis option may be set to "x" to draw vertical lines - these are not limited to the integer divisions, even for bar graphs. When using one of the horizontal graph types, the axes are flipped so that the default "y" axis becomes vertical and the "x" axis is then horizontal.
The third format is an array of guidelines, in either of the other two formats:
$settings = array( "guideline" => array( 10, array(20, "Target", "y"), array(30, "Target two") ) );
Styling the guide lines
There are several options available for changing how the lines and their titles appear, listed below (the names link to the relevant page in the options index):
Setting one of these options will change the appearance of all the guide lines on the graph, though you can alter the appearance of individual lines by passing named options in the array with the value and title/axis:
$settings = array( "guideline" => array(10, "Target", "text_colour" => "red") );
The named options correspond to the
in the list above with the leading "guideline_" removed to make them
The rest of this page demonstrates using the guide lines with some example settings.
Example: Market data
For this example I'll be starting off with the
figure 1 below, showing some completely made-up market data, with stock prices
rising and falling over the course of a day.
The array of values passed to SVGGraph to draw this graph consists of times and values, one for every five minutes from 08:00 to 17:00. The data line ends before 17:00, so I have padded the array with NULL values to provide the keys required for the axis labels.
In Figure 2 above, I have added in a guide line to mark where the previous
day's closing value of 1853 is in relation to today's figures. To add a single
dashed line using the default styling, I have set the
option to the single value 1853.
It might not be clear from this what the line represents, so in Figure 3
I've added a title to the
guideline by turning it into an array
and adding the title string as the second value. I've also changed the
line dash pattern with the
guideline_dash option. Dash patterns
are described on the line and scatter graphs
The default title position is at the top right of the line - this might
imply that the close value is at the end of the day, so in Figure 4 the
title has been moved to the top right with the
guideline_text_position option. I've also changed the font used
by the title with the
In Figure 5 below I've added in two more guide lines, for the maximum and minimum values that the non-existent market has seen in the last year. To specify multiple guide lines you must provide an array of options for each line.
In Figure 6 I've coloured the minimum and maximum guide lines by adding
in the named
colour option to the arrays for the individual
lines. All of the global
guideline_* options can be specified
for individual lines by adding them into the array with the leading
In Figure 7 below I have added a vertical guide line to highlight where there is a strange straight section in the graph line, by adding a new array with the third member set to "x" (because the value is on the X axis).
I've also turned on the
fill_under option to colour
in the area under the graph. By default the guide lines appear behind the
graph, so now we can't see most of them. (I haven't shown all the options
used in the description under the graph, as there are too many of them -
the full options list is shown further down the page.)
In Figure 8 above, I've set the
guideline_above option to true,
which makes all the guide lines appear on top of the graph data. You could make
individual lines above or below by setting the
above option in the
The code snippet below shows all the relevant options to draw the guide lines in Figure 8 - I haven't included the options to set up the grid spacing or any other styling options.
$options = array( "guideline" => array( array( 1853, "Close:\n1853" ), array( 1723, "Year minimum", "colour" => "red" ), array( 1958, "Year maximum", "colour" => "blue" ), array( "13:00", "Lunch\nbreak", "x", "stroke_width" => 2, "dash" => "3", "text_position" => "bottom right -3 -15", "text_angle" => -90, "font" => "Arial", ), ), "guideline_text_position" => "top left", "guideline_font" => "Georgia", "guideline_dash" => "1,2", "guideline_above" => true );
guideline_* options are shown after the
guideline option in this example, but their order is not important.
All lines with
above false are drawn first, in the order they
appear in the list. The lines with
above true are drawn in order
after the graph content has been rendered.