SVGGraph guide or target lines

« Return to SVGGraph page

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.

A graph with a guide line

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, and what each of them do should be fairly obvious:

guideline_above guideline_colour guideline_stroke_width
guideline_dash guideline_text_position guideline_text_padding
guideline_font guideline_font_size guideline_font_weight
guideline_text_colour guideline_text_angle  

Setting one of these options will change the appearance of all the guide lines on the graph, but you can alter the appearance of individual lines by passing named options along with their value and title/axis:

$settings = array(
  "guideline" => array(10, "Target", "text_colour" => "red")
);

The named options are all the same as the guideline_* options in the table above, but do not start with "guideline_".

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.

Figure 1
Figure 2
guideline = 1853

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.

Figure 3
guideline = array(1853, "Close:\n1853")
guideline_dash_pattern = "1,2"
Figure 4
guideline = array(1853, "Close:\n1853")
guideline_dash_pattern = "1,2"
guideline_text_position = "top left"
guideline_font = "Georgia"

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.

Figure 5
guideline = array(
array(1853, "Close:\n1853"),
array(1723, "Year minimum"),
array(1958, "Year maximum") )
guideline_dash_pattern = "1,2"
guideline_text_position = "top left"
guideline_font = "Georgia"
Figure 6
guideline = array(
array(1853, "Close:\n1853"),
array(1723, "Year minimum",
"colour" => "red"),
array(1958, "Year maximum",
"colour" => "blue") )
guideline_dash_pattern = "1,2"
guideline_text_position = "top left"
guideline_font = "Georgia"

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

Figure 7
guideline = array( ...
array(60, "Lunch break", "x", ... )
fill_under = true
Figure 8
guideline = array( ...
array(60, "Lunch break", "x", ... )
guideline_above = true

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(60, "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
);

« Back to top of page Shapes »