6.3 Bar graphs

Jpgraph also supports 2D vertical bar plots. Before you can use any bar plots you must make sure that you included the file "jpgraph_bar.php" in your script.

Using bar plots is quite straightforward and works in much the same way as line plots which you are already familiar with from the previous examples. Assuming you have a data array consisting of the values [12,8,19,3,10,5] and you want to display them as a bar plot. This is the simplest way to do this:

 $datay=array(12,8,19,3,10,5);

$bplot = new BarPlot($datay);

$graph->Add($bplot);

If you comapre this to the previous line examples you can see that the only change necessary was that instead of createing a new line plot (via the new LinePlot(...) call) we used the statement new BarPplot().

The other change we should do is to make sure the X-axis have an text-scale (it is perfectly fine to use a linear X-scale but in most cases this is not the effect you want when you use a bar graph, see more below). With this two simple change we will now get a bar graph as displayed in the following image You can of course modify the apperance of the bar graph. So for example to change the fill color you would use the BarPlot::SetFillColor() method. MAking this small change to the previous example would give the expected effect as can be seen in the next example. Sidebar: You should note from the previous two graphs that slight change in apperance for the X-scale. The bar graphs gets automatically centered between the tick marks when using as text x-scale. If you were to use a linear scale they would instead start at the left edge of the X-axis and the X-axis would be labeled with a linear scale. As is illustrated in the (small) example below

Figure 1: A small example with a bar graph using a linear X-scale [src]

6.3.1 Adjusting the width of the bars

JpGraph allows you to easy customize the apperance of the bar graph, for example to change the width of each bar. The width of each bar can be specified either as a fraction of the width between each major tick or as an absolute width (in pixels).

To set the width in fraction you use the method SetWidth() and to set the width in pixels you use the SetAbsWidth()

As an example let's take the previous example and set the width to 100% of the distance between the ticks. The example will now become

Figure 2: Setting the width of the bars to 100% of the tick width [src]

6.3.2 Displaying the value of each bar

You can easily choose to display the value (and it's format) on top of each bar by accessing the bar's 'value' property. So for example by just adding the line

 $barplot->value->Show();

Will enable the values in it's simplest form and will give the result

Figure 3: Showing the values for each bar [src]

You cane see a small nuiance in this graph. The autoscaling algorithm chooses quite tight limits for the scale so that the bars just fit. Adding the value on top of the bar makes it collide with the top of the graph. To remedy this we tell the autoscaling algorithm to allow for more "grace" space at the top of the scale by using the method SetGrace() which is used to tell the scale to add a percentage (of the total scale span) more space to either one end or both ends of the scale. In this case we add 20% more space at the top to make more room for the values with the line

 $graph->yaxis->scale->SetGrace(20);

This will then give the graph as shown below

Figure 4: Adding some grace space to the top of the Y-scale [src]

You can also adjust the general position of the value in respect to the bar by using the BarPlot::SetValuePos() method. You can set the position to either 'top' (the default) , 'center' or 'bottom'. The graph below shows the value being positioned in the center. In this example we have also adjusted the format to just display the value as an integer without any decimals.

Figure 5: Putting the values in the middle of the bar. [src]

It is also possible to specify a more fine grained control on how you want the values presented. You can for example, rotate them, change font, change color. It is also possible to adjust the actual value displayed by either using a printf()-type format string or with the more advanced technique of a format callback routine.

To show what you can do we just give another example for you to examine without much further explanations. Just remember that to have text at an angle other than 0 or 90 degrees we have to use TTF fonts. Even though we haven't explained the SetFont() method it should be fairly obvious.

Figure 6: Making the displayed values more interesting [src]

6.3.3 Adding a drop shadow to the bar

One simple way of making the bar graph more attracting is to add a drop shadow to each bar. This is done by calling the SetShadow() method. An example will clarify this.

Figure 7: Adding a drop shadow to each bar [src]

6.3.4 Adjusting the alignment of bars ona text scale

As you have seen from the previous examples bar graphs are normally centered between the trick marks on a text scale. However, you can modify this behavious by calling the method BarPlot::SetAlign()

6.3.5 Using grouped bar plots

These types of bar graph is used to easy group two or more bars together around each tick (X-value). The bars will be placed immediately beside each other and as a group centred on each tick mark. A grouped bar is created by aggregating two or more ordinary bar graphs and creating a GroupBarPlot() From two ordinary bar graphs along the lines of

 // Create the bar plots

$b1plot = new BarPlot($data1y);

$b1plot->SetFillColor("orange");

$b2plot = new BarPlot($data2y);

$b2plot->SetFillColor("blue");

// Create the grouped bar plot

$gbplot = new GroupBarPlot(array($b1plot,$b2plot));

// ...and add it to the graPH

$graph->Add($gbplot);

The following example illustrates this type of graph

Figure 8: A grouped bar plot [src]

There is no limit on the number of plots you may group together.

If you use the SetWidth() method on the GroupBarPlot() this will affect the total width used by all the added plots. Each individual bar width will be the same for all added bars. The default width for grouped bar is 70%.

Setting the grouped with to 0.9 would result in the image below.

Figure 9: Adjusting the width for a gropued bar plot. [src]

6.3.6 Using accumulated bar plots

The final varietys of group bars you can have are accumulated bars. They work in much the same way as accumulated line plots described above. Each plot is stacked on top of each other.

You create accumulated bar plots in the same way as grouped bar plots by first creating a number of ordinary bar plots that are then aggregated with a call to AccBarPlot();

An example makes this clear. Let's use the same data as in the two examples above but instead of grouping the bars we accumulate (or stack) them. The code would be very similar (actually only one line has to change)

Figure 10: Accumulated bar plots [src]

6.3.7 Using grouped accumulated bar graphs

It is perfectly possible to combine the previous bar types to have grouped accumulated bar plots. This is done by just adding the different accumulated plots to a group bar plot, for example the following code would do that.

 // Create all the 4 bar plots

$b1plot = new BarPlot($data1y);

$b1plot->SetFillColor("orange");

$b2plot = new BarPlot($data2y);

$b2plot->SetFillColor("blue");

$b3plot = new BarPlot($data3y);

$b3plot->SetFillColor("green");

$b4plot = new BarPlot($data4y);

$b4plot->SetFillColor("brown");

// Create the accumulated bar plots

$ab1plot = new AccBarPlot(array($b1plot,$b2plot));

$ab2plot = new AccBarPlot(array($b3plot,$b4plot));

// Create the grouped bar plot

$gbplot = new GroupBarPlot(array($ab1plot,$ab2plot));

// ...and add it to the graph

$graph->Add($gbplot);

Putting this together in an example would then produce the graph as whown below

Figure 11: Combining grouped and accumulated bar plots [src]

6.3.8 Horizontal bar graphs

It can often come in handy to have horizontal bar graphs especially if you have a large number of values to display. Even though JpGraph doesn't directly support horizontal bar graphs this is easy achived by constructing a normal vertical bar graph which is then rotated 90 degrees.

The example below shows a simple example of this

Figure 12: A typical horizontal bar graph with the Y-axis at the bottom [src]

In order to achieve this effect you should study the above example carefully and you might notice two things

We dont simply rotate the graph we also specify that we want the rotation center to be the middle of the entire image. The reason for this is that by default (See the section on rotating plots) the pivot point for rotation is the center of the plotarea. Since the center of the plotarea is not necessary the center of the entire image the rotation might be a little bit difficult to predict since it will depend on the margins specified. <
The size of the plotarea is determined from the original width and height of the image taking the specified margin into account. When the the plotartea is rotated 90 degrees clockwise what was the left margin now in effect becomw the upper margin and so on. This is a small nuance since we conceptually want to specify the margins directly in the rotated plot.
I have choosen not to add any special margin method specifically for a 90 degree rotated plot. Since to compensate for this since is fairly easy once you understood this problem.For this reason the example code let's you specify the percived margins and they are then backwards converted to their horizontal equivalent. If the width and height differs we must also take that into account.
The code below extracts the lines that makes this simple conversion

// Since we swap width for height (since we rotate it 90 degrees) // we have to adjust the margin to take into account for that $top = 50; $bottom = 30; $left = 50; $right = 20; $adj = ($height-$width)/2; $graph->SetMargin($top-$adj,$bottom-$adj,$right+$adj,$left+$adj);

We finally show three more examples of horizontal bar plots. In the first plot we have hidden the Y-axus and in the second we have positioned the Y - axis at top as opposed to the bottom as the first example shows.

Figure 13: Horizontal bar graph with hidden Y axis [src]

Figure 14: Horizontal bar graph with Y axis at the top [src]

In the final example which is almost similair to the two first we illustrate the use of labels with more than one line.

Figure 15: Horizontal bar graph with manual integer scale as well as multiple line labels [src]

6.3.9 Using gradient fill for bar graphs

It is possible to use color gradient fill for the individual bars in the bar graph.

Color gradient fill fills a rectangle with a smooth transition between two colors. In what direction the transition goes (from left to right, down and up, fomr the middle and out etc) is determined by the style of the gradient fill. JpGraph currently supports 7 different styles. All supported styles are displayed in the figure below.

Figure 16: [src]

Figure 17: [src]

Figure 18: [src]

Figure 19: [src]

Figure 20: [src]

Figure 21: [src]

Figure 22: [src]

To specify a gradient fill for the bar plots you make use of the method BarPlot::SetFillGradient() . See the class reference for details of this function.

When using gadient fills there are a couple of caveats you should be aware of:

gradient filling is computational expensive. Large plots with gradient fill will take in the order of 6 times longer to fill then for a normal one-color fill. This might to some extent be helped by making use of the cache feature of JpGraph so that the graph is only generated a few times.
gradient filling will make use of much more colors (by definition) this will make the color palette for the image bigger and hence make the overall image larger. It might also have some severe effect on using anti-aliased line in the same image as color gradient filling since anti-aliased lines also have the possibility to make use of many colors. Hence the color palette might not be big enough for all the colors you need. So if you use gadient fills you should also be using a true-color image since you otherwise run out of colors.
This problem is often seen as that for no apperant reason some color you have specified in the image does appear as another color. (This is not a bug in JpGraph!) This is something to especially watch out for when enabling anti-alising since that also uses a lot of colors. Since the numbers of colors used with anti-alising depends on the angle on the lines it is impossible to foresee the number of colors used for this.

6.3.10 Creating semi-filled bar graphs

Semi filled bar graphs are in principle the same as normal filled bar graphs but with the additional feature that you can choose to only fill a specified range (or ranges) of X-coordinates. The figure below illustrates this

Figure 23: Semi-filled line graph [src]

I this example we defined two areas along the X-axis to be filled. You can add filled areas by using the method AddArea() and specifying range and color for the filled area.

Contents Previous Next