Contents Previous Next

## 7.2 Pie plots

So far we have just show plots based on an X-Y coordinate system. This is not the only types of graphs you can create with JpGraph. Another common type is Pie plots. JpGraph supports both 2D and 3D pie plots. For 2D pie plots there are also 2 versions, but more on that later.

The main difference as compared to the X-Y plots is that to all pie plots are added to the PieGraph() instead of the Graph() object we used for the X-Y graphs we have drawn so far. For this you must first include the "jpgraph_pie.php" in your script (or "jpgraph_pie3d.php" if you want to use 3-dimensional pies).

Below you cane see the code needed to create the simplest possible pie graph just using the default settings.

`include ("../jpgraph.php");
include ("../jpgraph_pie.php");
$data = array(40,60,21,33);
$graph = new PieGraph(300,200);
$graph->SetShadow();
$graph->title->Set("A simple Pie plot");
$p1 = new PiePlot($data);
$graph->Add($p1);
$graph->Stroke();
`

The above code would give the following pie graph

Figure 1: The simplest possible pie graph [src]

There is a few things worth noting here

- By default all pie slices have the percentage shown just outside the slice.
- The colors are automatically assigned to the slices.
- The pie have the edges marked by default
- The first slice start at 0 degrees (3 o'clock)

You can change almost all aspects of appearance of the pie graphs. For example you could change :

- Change the angle for the first slice, ( PiePlot::SetStartAngle())
- Remove the border lines around the pie ( PiePlot::ShowBorder())
- Change the color of the border ( PiePlot::SetColor(),
- Change the colors of the slices ( PiePlot::SetSliceCOlors())
- Change the size and position of the pie ( PiePlot::SetSize(), PiePlot::SetCenter())
- Adjust the labels for the slice (color, font, format, position ) by accessing the value property of pie plots, for example ( PiePlot::value::SetFont(), You can read more about label formatting and how to change what is displayed as a value further down in this chapter.

The next simplest addition we can do is to add a legend to the pie graph. We do this by using the SetLegends(); method. By adding the legends to the previous example we get the following image

Figure 2: Adding a legend to the pie graph [src]

(In the figure above we also moved the center of the pie slightly to the left to make more room for the legend box.)

The text for the legends can also contain printf() style format strings to format a number. This number passed on into this string is either the absolute value of the slice or the percentage value. How to switch between the is describe further down in this chapter.

The next change you might want to change is the size and position of the Pie plot. You can change the size with a call to SetSize(); and the position of the center of the pie plot with a call to SetCenter(); The size can be specified as either an absolute size in pixels or as a fraction of width/height (whatever is the smallest). The position of the pie plot is specified as a fraction of the width and height.

To put the size and positioning API to use we will show how to put several pie plots on the same pie graph. In the following example we have also adjusted the legends of the slice values to use a smaller font.

What we do in this example is quite simple, create 4 pie plots, make them smaller and put them in the four corner of the graph. This will give the result as shown in the following example.

Figure 3: Multiple pie plots in the same pie graph [src]

### 7.2.1 Creating 3D pie plots

So far we have only made use of 2D pie plots, creating 3D pie plots is no more difficult. Instead of creating the plots with a call to PiePlot() you create the plots with a call to PiePlot3D() If we just take the first simple pie plot and replace the call to PiePlot() with a call to PiePlot3D() we get the following result.

Figure 4: A first example of a 3D pie plot [src]

3D Pie plots have the same possibilities as the normal pie plots with the added twist of a 3:rd dimension. You can adjust the perspective angle with the method SetAngle() So for example to make the pie more "flat" you just set it to a smaller angle. Setting the perspective angle to 20 degrees in the previous example will give the following result.

Figure 5: Adjusting the perspective angle [src]

### 7.2.2 Exploding pie slices

One way to attract attention to some specific piece of information in a pie chart is to "explode" one or more slices. Both 2D and 3D pies support exploding one or several slices.

Exploding slices is accomplished by the methods Explode() and ExplodeSlice() The first method is used if you want to explode more than one slices and the second is a shorthand to make it easy to just explode one slice.

For example to explode one slice the default "explode" radius you would just have to say

`$pieplot->ExplodeSlice(1)`

The above line would explode the second slice (slices are numbered from 0 and upwards) the default amount. Doing this to the two previous example would result in

Figure 6: Exploding one slice [src] | Figure 7: Exploding one 3D slice [src]

To explode all slices at once you can use the PiePlot::ExplodeAll() method. If you want to explode several slices you can use the PiePlot::Explode() method and supply a suitable array argument.

### 7.2.3 Specifying and adjusting labels on pie plots

By default the values shown just outside the pie for each slice are the percentage value for each slice. If you instead wanted the absolute value you would just have to use the SetLabelType() method. So to use the absolute value you would call

`$pieplot->SetLabelType("PIE_VALUE_ABS");`

Furthermore you could enhance the formatting of the value by either using a printf() style format string (using SetFormat() ) or by providing a formatting function callback (using SetFormatCallback() ) for doing more advanced formatting.

You can also adjust the position of the labels by means of the PiePlot::SetLabelPos() method. The argument to this method is either the fraction of the radius or the string 'auto'. In the latter case JpGraph automatically determines the best position and the the first case The following example illustrates this

Figure 8: Example of adjusting the position of the labels for the slices [src]

If this formatting is not enough you can also "manually" specify the labels for each slice individually. You do this by using the PiePLot::SetLabels() method. This will let you specify individual text strings for each label. In each specification you can also add a printf() formatting specification for a number. The number passed on will be either the absolute value for the slice or the percentage value depending on what was specified in the call to SetLabelType()

The SetLabels() method can also take a second parameter, the label position parameter. This is just a shortcut to the SetLabelPos() as described above. By default the position will be set to 'auto' if not explicitely specified.

Note: The alignment of the labels will be different depending on whether they are inside or outside the pie. When inside the center of the strings will be aligned with the center of the slice at the specified fraction of the radius. When positioned outside the alignment will depend on the angle to avoid that the labels inadvertedly writes over the pie.

### 7.2.4 Specifying slice colors and using themes

Another typical change would be to change the colors of the slices. There are two fundamental ways of doing this. You either manually specify the colors for the slices as an array using the method SetSliceColors() If you specify fewer colors than the number of slices they will just wrap around.

Another way is to use one of the pre-defined color "themes". This is just a predefined set of colors that will be used for the slices. You choose what "theme" you like to use with the method ( SetTheme() ) At the time of this writing the available themes are

- "earth"
- "pastel"
- "sand"
- "water"

The following example shows the same pie using the different "themes" in order.

Figure 9: [src] | Figure 10: [src] | Figure 11: [src] | Figure 12: [src]

A complete color chart of all available colors in the different themes can be found here

Another simple change is to remove the border ( or change it's colors ) that separates each slice. This can be done by a call to ShowBorder()

### 7.2.5 Adding drop shadows to the slices

An additional visual enhancements can be made by adding a drop shadow to the individual slices. This is accomplished by means of the PiePlot::SetShadow() method. Adding a drop shadow is often more affective if the pie has one or more slices exploded as the following example shows

Figure 13: Adding a drop hadow to the slices [src]

### 7.2.6 Another variant of 2D Pie plots

As mentioned in the beginning there are two versions of the 2D pie plots. The normal pie plot created as an instance of class PiePlot and a variant created as an instance of class PiePlotC

This variant is an extension of the standard PiePlot in the sense that it also have a filled circle in the center. The following example illustrates this

Figure 14: Example of the variant of pie plot with a filled center circle [src]

Since the PiePlotC is an extension to the basic pie plot all the normal formatting you can do for pie plots you can also do for the PiePlotC .

The additional formatting only concerns the filled middle circle. You have the option of adjusting size, fill color and all font properties. You perform these operations with the methods

PiePlotC::SetMidColor() | Set fill color of mid circle
PiePlotC::SetMidSize() | Set size (fraction of radius)
PiePlotC::SetMidTitle() | Set title string (may be multi-lined)
PiePlotC::SetMid() | Set all parameters in a single method call

In addition to the normal CSIM for PiePlot:s the center area is also a CSIM hotspot. You specify the target CSIM with a call to PiePlotC::SetMidCSIM()

The next example shows an example with some more innovative formatting. In this example we have :

- hidden the frame around the pie graph
- exploded all the slices
- added drop shadow to the individual slices (and the center filled circle)
- specified individual multi line labels.
- changed the font for the title to a TTF font.

Figure 15: PiePlotC with some more innovative formatting to make it more interesting. [src]

Contents Previous Next