SVGGraph guide or target lines

« Return to SVGGraph page

Skip to:

• Using
• Styling
• Example
• Average 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 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):

• guideline_above
• guideline_colour
• guideline_dash
• guideline_font
• guideline_font_adjust
• guideline_font_size
• guideline_font_weight
• guideline_length
• guideline_length_units
• guideline_line_spacing
• guideline_opacity
• guideline_stroke_width
• guideline_text_align
• guideline_text_angle
• guideline_text_colour
• guideline_text_opacity
• guideline_text_padding
• guideline_text_position

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:

• average_above
• average_colour
• average_dash
• average_font
• average_font_adjust
• average_font_size
• average_font_weight
• average_length
• average_length_units
• average_opacity
• average_stroke_width
• average_title
• average_title_align
• average_title_angle
• average_title_callback
• average_title_colour
• average_title_opacity
• average_title_padding
• average_title_position
• show_average

All of the options support using an array of values to configure datasets separately.

« Back to top of page Shapes »

Copyright © 2020, Goat 1000