It is a well known fact that sun spots have a certain pattern and regularity. The cause of these regular patterns are not currently fully understood (even though investigation into this phenomenon has been made since beginning of the 17:th century). The fact that solar storms affects the earth in terms of interference with radio traffic and other sensitive electronic devices makes it very interesting to keep careful records of the suns activities.

For this reason the data of solar storm is readily available and makes an interesting first example. The data used here is taken from SIDC (The Solar Influences Data Analysis Center) in Belgium (http://sidc.oma.be/sunspot-data/SIDCpub.php). In this example we will use the summary historical data that shows the total number of sun spots per year since 1700..

The first step is to get the data into our PHP script which makes for a first good discussion since all graphs needs to get data from some source. The library itself is agnostic in regards to from where the data is collected and only needs (and requires) data stored in a PHP array of numbers (integers or floats).

In principle the data to be plotted in the graph can come from :

What is common among all these methods is that the creator of the script has to read the data into one (or several) data arrays that can be used by the library. For our example the data of sunspots are stored in a plain text file in two columns, one column for the year (with a ".5" added which indicates the average of the year) and one column for the number of sunspots for the corresponding year. As illustration the first 10 lines of data is shown in Figure 4.1.

1
2
3
4
5
6
7
8
9
10

1700.5   5.0  
1701.5  11.0  
1702.5  16.0  
1703.5  23.0  
1704.5  36.0  
1705.5  58.0  
1706.5  29.0  
1707.5  20.0  
1708.5  10.0  
1709.5   8.0

From this data we need to create two arrays, one with the number of sunspots and one with the corresponding years. If we assume that the data is stored in a text file named "yearssn.txt" in the same directory as the script file the function in Figure 4.2will read the data into two arrays

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<?php
function readsunspotdata($aFile, &$aYears, &$aSunspots) {
    $lines = @file($aFile,FILE_IGNORE_NEW_LINES|FILE_SKIP_EMPTY_LINES);
    if( $lines === false ) {
        throw new JpGraphException('Can not read sunspot data file.');
    }
    foreach( $lines as $line => $datarow ) {
        $split = preg_split('/[\s]+/',$datarow);
        $aYears[] = substr(trim($split[0]),0,4);
        $aSunspots[] = trim($split[1]);
    }
}
 
$year = array();
$ydata = array();
readsunspotdata('yearssn.txt',$year,$ydata);
 
?>

In the function above we have deviated from the common practice of not including even the most basic error handling in examples by adding an exception in case the data file could not be read. This is to emphasize that graph scripts which reads data from potentially disconnected sources must have real quality error and exception handling. As this is the first example we will not discuss the details of the error handling other than saying that the library provides one exception class JpGraphException that is meant to be used by clients to signal unrecoverable errors in the code. The full details on error handling in the library is discussed in Chapter 6

Armed with the data in the two arrays $year and $ydata we will now plot the data in a basic line graph with some variations and then show the data in a bar graph.

As the very first start we will create a line graph which shows sun spots as a line graph. To keep the code focused on the graph we do not include the previous function to read the data again in the code snippet shown below. Before we get into the code we start by briefly discuss how your script can include the necessary library files.

All graph scripts must include at least two files, jpgraph.php and some plot module. If we want to create a line plot we must include jpgraph_line.php. Slightly depending on the server setup and what paths are defined for PHP include files (as discussed in Section 3.3.3) the include paths for the library might look a bit different. However, we recommend that you install the library files so they can be accessed, for example using, require_once('jpgraph/jpgraph.php') (since this is what is assumed by the library examples). Furthermore, we would recommend that the require_once() construct is used to avoid including the same file multiple times.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<?php
 // Width and height of the graph
$width = 600; $height = 200;
 
// Create a graph instance
$graph = new Graph($width,$height);
 
// Specify what scale we want to use,
// int = integer scale for the X-axis
// int = integer scale for the Y-axis
$graph->SetScale('intint');
 
// Setup a title for the graph
$graph->title->Set('Sunspot example');
 
// Setup titles and X-axis labels
$graph->xaxis->title->Set('(year from 1701)');
 
// Setup Y-axis title
$graph->yaxis->title->Set('(# sunspots)');
 
// Create the linear plot
$lineplot=new LinePlot($ydata);
 
// Add the plot to the graph
$graph->Add($lineplot);
 
// Display the graph
$graph->Stroke();
?>

Before we explain this code in some more detail it is a good idea to visualize what we get when we execute this as script. The result of running this script is shown in Figure 4.3

Figure 4.3. Line plot showing the number of sun spots since 1700 (sunspotsex1.php)

Let us now walk through this code in some details.

Let's now make a small variation of the above line graph. Let's make it a filled line graph. instead. In order to do this we only have to add one single line

1
2
3

<?php
$lineplot->SetFillColor('orange@0.5');
?>

The line above actually does two things. First it sets the basic color to 'orange' and then it modifies this color to be 50% opaque (0.5) which makes the grid line shine through the fill color to some extent. The whole color handling in the library is further describe both in Appendix D as well as in Chapter 7. The result of adding the line above is shown in Figure 4.4

Figure 4.4. Displaying sun spots with a semi filled line graph (sunspotsex2.php)

Adding tick labels to the X-axis

Note

This section can be skipped at first reading since it contains some slightly more advanced material. The reason why we have included this section already now is that some of the issues discussed here is an often repeated question among newcomers to the library.

There is one bit of the available data that we haven't used yet and that is the actual years. In the example above we can only see the count from 1700. (If we just want to look at the cyclic behaviour of the number of sunspots this is fine since what year a specific number of sunspots appeared is not relevant.) To make it easier to see what year corresponds to the different sunspot numbers we must change the label on the X-axis scale to show the years instead.

There is actually a couple of ways to do this. The easiest way is to just add the labels we have ($years) on the X-axis and instruct the library to use them instead. This is done with a call to the method SetTickLabels() on the X-axis. This method call takes an array as argument and uses the values in that array to populate all labels on major tick marks. In order to make adequate room for the scale the library automatically selects a suitable distance between each major tick mark.

1 2 3

<?php $graph->xaxis->SetTickLabels($year); ?>

Adding this line to our previous graph will generate the graph shown in Figure 4.5

Figure 4.5. Adding tick labels to the graph (sunspotsex3.php)

However, there is a problem in the graph above. There are valid years on the X-axis up to "2000" but then there is a single label "320".

What is going on here? Have we already discovered a bug in the library?

No, not really. In the way we have setup the graph we have not provided the library with enough labels. What has happened is that the integer scale has chosen a suitable interval between each tick label to have enough space to be able to show the labels. As can be seen from the figure the distance chosen with this particular graph seems to be 20 years between each tick. The way the default labeling works is that the end tick should be labelled and hence be an even multiple of 20 years (in this case).

Since the library needs to have tick labels for all ticks it uses the labels we supplied as far as they go (up to 2008) but since we didn't supply data more than up to "2008" (in the $year array) the library does what it can do and continues with the ordinal numbers where we failed to provide enough labels.

Now, there are a some standard ways of correcting this abomination.

1. We can set a manual scale to make sure the scale ends exactly at 2008, i.e. the scale is exactly as long as our data. This is done by submitting the wanted scale min/max as additional argument in the SetScale() method. First the min/max for the Y-axis and then the min/max for the X-scale. Since we still want the Y-scale to be fully automatically determined we just put a "0" for both min and max on the Y-scale and specify 0 for the min x-value and then the exact number of sunspots we have measured as the maximum x-value.

   1 2 3

   <?php $graph->SetScale('intint',0,0,0,max($year)-min($year)+1); ?>

   The result of this is shown in Figure 4.6

   Figure 4.6. Manually specifying the X scale to use just the supplied X values (sunspotsex4.php)

   

   
   

2. An alternative way to get labels is to use a callback function to specify the labels. This works so that the library calls the user specified function and as argument passes the label (or the value of the label) that the library intends to put on a tick. The library will then use as the actual label whatever string value we return from our function. Since we know that the integer label 0 (the first tick) corresponds to the first value, i.e. "1700" we can simply take whatever label we get as argument, add "1700" and return that value. This way all labels will be properly named and even if the scale extends far beyond where we have data a sensible tick label will be shown.

   A suitable callback function together with the method to instruct the library to use this callback would be

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   <?php // ... // Label callback function year_callback($aLabel) { return 1700+(int)$aLabel; } // ... $graph->xaxis->SetLabelFormatCallback('year_callback'); // ... ?>

   and the result can be seen in Figure 4.7

   Figure 4.7. Using a callback to get correct values on the x axis (sunspotsex5.php)

   

   
   

3. There is one more way to handle this issue which we will not cover in detail yet. This is to use a "text" scale. The "text"scale can be used when there is no need to show numeric values on the axis. A typical use for text scale would be to add labels to mark bar graphs. Of course a text can contain numeric strings that would make it visually indistinguishable from a "real" numeric value.

   For text scales every label counts. So by default the library will assign a tick mark for each ordinal so that every label is used. In some cases this will just be two dense and then the tick and the labelling can be adjusted by calling the two methods Axis::SetTextTickInterval() and Axis::SetTextLabelInterval() to get to a wanted result. But for now we do not discuss this technique further here since it would bring too far.

As a final illustration we will show how easy it is to change the plot type. We will make a small modification of the previous script and display the sun spots as a bar graph instead. In order to do this we take the code from Figure 4.4 and just change the creation of an instance of the LinePlot() class to instead be an instance of the BarPlot() class (to make the code more readable we also change the name of the variable where we store the instance so it makes more sense). In order to use this class we must also change the include statement so that the bar module is included by adding the statement require_once('jpgraph/jpgraph_barplot.php'). The changed code would now look like this

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php
// ...
 
// Create the bar plot
$barplot=new BarPlot($ydata);
 
// Add the plot to the graph
$graph->Add($barplot);
 
// Display the graph
$graph->Stroke();
 
?>

and would result in the graph displayed in Figure 4.8

Figure 4.8. Changing the plot type to a bar plot instead (sunspotsex6.php)

Since there are so many bars in small space we cannot see the individual bars in the example in Figure 4.8. So lets modify the script so that it only shows the last 20 years of measurements so that we can see the individual bars. To set this up there are two things we must do

The following code snippet shows the necessary modifications to the previous script

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?php
// Just keep the last 20 values in the arrays
$year = array_slice($year, -20);
$ydata = array_slice($ydata, -20);
 
// ...
 
// Specify what scale we want to use,
// text = txt scale for the X-axis
// int = integer scale for the Y-axis
$graph->SetScale('textint');
 
// ...
?>

The final graph with the "zoomed" last 20 years can now be seen in

Figure 4.9. Sunspots zoomed to only show the last 20 years (sunspotsex7.php)

Since the scale is larger we can now actually see the individual bars. By default the library choses a light blue color to fill the interior. (Try to see what happens if you add the method call "$barplot->SetFillColor('orange@0.5');" just after the "$barplot" variable has been assigned the new BarPlot object.)