SVGGraph subgraphs
Skip to:
Added in version 3.1, subgraphs allow you to draw graphs on top of other graphs. These subgraphs can have their own values, options, links, colours, and can also have their own subgraphs.
Adding a subgraph
This is a simple example to show how to use subgraphs. The main graph
is a LineGraph showing the start of the Fibonacci sequence, and
the subgraph is another LineGraph showing the reciprocals of each
of the values in the main graph.
Here is the code that creates the outer graph, adds the subgraph, then draws both of them:
$graph = new Goat1000\SVGGraph\SVGGraph(600, 200, $settings);
$graph->values($values);
$subgraph = $graph->subgraph('LineGraph', 45, 2, 280, 130, null, $inner_settings);
$subgraph->values($inner_values);
$graph->render('LineGraph');The first two lines are the normal setup and value assigment for a graph,
then the next two lines create a subgraph and assigns values to that. The last
line renders the outer LineGraph and automatically renders the
subgraph on top.
The subgraph function
The most important new part in that code is the subgraph
function, whis is supported by the main SVGGraph class and also
the Subgraph class for adding subgraphs to subgraphs. The function
has a declaration that looks like this:
function subgraph($type, $x, $y, $w, $h, $settings = null, $extra = null)
The $type argument is the graph type to add, which can be any
of the types supported by SVGGraph. The example draws a LineGraph
in another LineGraph, but they could just as easily be a
PieGraph in a GroupedBarGraph or a RadarGraph
in a CylinderGraph.
The $x and $y arguments are where the top-left
corner of the subgraph goes, relative to the parent graph. The example is using
absolute pixel positions, but you could also use negative values to specify
distances from the left and bottom edges of the outer graph, or
grid coordinates to position the
subgraph relative to the parent graph's grid.
$w and $h are the width and height of the subgraph,
and also support negative values to position the right and bottom edges relative
to the parent graph. Grid coordinates are supported for the width and height
too.
Subgraph settings
The optional $settings and $extra are for passing
arrays of options to the subgraph. When neither of the arguments are set, the
settings from the parent graph are passed to the subgraph without alteration.
When the $settings argument is set, its value is passed to the
subgraph instead of the parent's settings. The subgraph can be made to use the
default settings by passing an empty array as the $settings option:
// main graph uses $outer_settings
$graph = new Goat1000\SVGGraph\SVGGraph(600, 200, $outer_settings);
// subgraph using new settings
$subgraph = $graph->subgraph('LineGraph', 10, 10, 200, 100, $subgraph_settings);
// subgraph using default settings
$subgraph = $graph->subgraph('LineGraph', 210, 10, 200, 100, []);
The $extra argument can be used to pass extra settings to the
subgraph - these are merged in with the main options set with $settings
or inherited from the parent graph:
// main graph uses $outer_settings
$graph = new Goat1000\SVGGraph\SVGGraph(600, 200, $outer_settings);
// subgraph using $subgraph_settings and $more_settings
$subgraph = $graph->subgraph('LineGraph', 10, 10, 200, 100, $subgraph_settings, $more_settings);
// subgraph using $outer_settings and $more_settings
$subgraph = $graph->subgraph('LineGraph', 210, 10, 200, 100, null, $more_settings);
There is no need to use the $settings or $extra
arguments if the main graph and subgraph(s) are to share all the same options.
Return value - the Subgraph class
When you call the subgraph function it creates an instance of
the Subgraph class and attaches it to the parent graph before
returning it. The Subgraph class behaves a lot like the
SVGGraph class, supporting the functions to add values and links,
set the colours and creating new subgraphs.
The Subgraph class does not support the fetch or
render functions though - subgraphs are only drawn as part of the
parent graph's output.
Values and links
SVGGraph doesn't automatically assign any values or links to subgraphs - to
do that you must call the values and links functions
of the Subgraph object returned from the subgraph
function call.
If you want the subgraph to use the same values as the outer graph, just pass the same array of values to both.
Colours
The colours used by subgraphs are inherited from their parent graph - unless
you use any of the colour functions on the Subgraph object.
Sub-subgraphs
Subgraphs are just graphs that sit inside other graphs, so naturally they
also support subgraphs. To add a subgraph to a subgraph, just use the same
subgraph function on the Subgraph object:
The updated code for drawing the pie graph inside the inner line graph is below:
$graph = new Goat1000\SVGGraph\SVGGraph(600, 200, $settings);
$graph->values($values);
$subgraph = $graph->subgraph('LineGraph', 45, 2, 280, 130, null, $inner_settings);
$subgraph->values($inner_values);
$subsubgraph = $subgraph->subgraph('PieGraph', 'g7', 'gt', 'u3', 'u3x', $settings, $pie_settings);
$subsubgraph->values($values);
$subsubgraph->colourRangeHexHSL(0, '#f00', '#00f', true);
$graph->render('LineGraph');
The PieGraph is drawn at 'g7' and
'gt' which means 7 units along the X axis and at the grid top. The
width and height are 'u3' and 'u3x' to give 3 X-axis
units in both directions.
The sub-subgraph is using the same $settings array as the outermost
graph, but with a few extra options added from the $pie_settings
array. I haven't shown them here, but they adjust the padding and turn off the
background fill.