SVGGraph guide or target lines
Skip to:
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
SVGGraph constructor.
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
line:
$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 array(10)
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 guideline_*
options
in the list above with the leading "guideline_" removed to make them
shorter.
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 LineGraph
in
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 guideline
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
page.
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 guideline_font
option.
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
"guideline_" removed.
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
line's array.
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
);
The global 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.
Average lines
Average lines were added in version 3.7 of SVGGraph - automatically calculated mean averages displayed on the graph as guide lines. Unlike best-fit lines, average lines use all the data values provided (except NULL values, which are not used in the calculation).
The lines are enabled with the show_average
option, and can be
styled using various options that correspond with the relevant guideline
options. Here's the full list:
All of the options support using an array of values to configure datasets separately.