What is the DataPreprocessor for?

In some cases data values are in such a format that the when written to the Image_Graph elements (f.x. Image_Graph_Axis or Image_Graph_Marker) they do not make much sense.

An example on usage

For example is it often necessary to plot som (x,y) values where x are dates and maybe the y values represent the percentage of system load as an average on the specified date. Then we would need to plot values of the kind (7 Aug 2004, 24.4%), (8 Aug 2004, 86.2%), (9 Aug 2004, 5.7%). But the way we add points does not support the "formatting" of the values, i.e. it is not possible to do:

1     // THIS WON'T WORK!
2     
3     ...
4     $DataSet->addPoint("7 Aug 2004", "24.4%");
5     $DataSet->addPoint("8 Aug 2004", "86.2%")
6     $DataSet->addPoint("9 Aug 2004", "5.7%")
7     ...

The reason is that the Image_Graph_DataSet requires (x, y) values to be numerical. The solution to this is to use the DataPreprocessor and its sub-classes. There are a couple of ways to do this, but well describe in details the use of Image_Graph_DataPreprocessor_Array for the X-values and Image_Graph_DataPreprocessor_Formatted for the Y-values.

Using Image_Graph_DataPreprocessor_Array

To use the Image_Graph_DataPreprocessor_Array method you would map the values on to the "displayed" value. This can be done in the following way:

1     ...
2     $XArray[0] = "7 Aug 2004"; // there is of course no need to actually hardcode this
3     $XArray[1] = "8 Aug 2004";
4     $XArray[2] = "9 Aug 2004";
5     
6     $DataSet->addPoint(0, 24.4);
7     $DataSet->addPoint(1, 86.2);
8     $DataSet->addPoint(2, 5.7);
9     ...
10    $AxisX =& $Ploarea->getAxis(IMAGE_GRAPH_AXIS_X);
11    $AxisX->setDataPreprocessor(new Image_Graph_DataPreprocessor_Array($XArray));
12    ...

This will cause the X-axis to display x-labels mapped on to the $XArray, i.e. if a label is to be printed for the "internal" x-value 0, the Image_Graph_DataPreprocessor_Array will then "catch" the value before it is printed on the axis and translate it from 0 to "7 Aug 2004" and print this value instead. Likewise for other x-values.

Note however that using this way to display X-axis values will require the (@link Image_Graph_Axis} labels to cooincide with an index within the array, i.e. if you do the following:

1     ...
2     // THIS WON'T WORK!
3     
4     $XArray[] = "7 Aug 2004"; // there is of course no need to actually hardcode this
5     $XArray[] = "8 Aug 2004";
6     $XArray[] = "9 Aug 2004";
7     
8     $DataSet->addPoint(10, 24.4);
9     $DataSet->addPoint(20, 86.2);
10    $DataSet->addPoint(30, 5.7);
11    ...
12    $AxisX =& $Ploarea->getAxis(IMAGE_GRAPH_AXIS_X);
13    $AxisX->setDataPreprocessor(new Image_Graph_DataPreprocessor_Array($XArray));
14    ...

The X-values (10, 20, 30) are not found as indices in the $XArray and will therefor be printed as values, i.e. 10, 20 and 30.

Using Image_Graph_DataPreprocessor_Formatted

To enable the Y-values to be displayed as percentages (i.e. 86.2% instead of "just" 86.2) we can use the Image_Graph_DataPreprocessor_Formatted preprocessor.

This method basically uses the sprintf function to format the output. The usage is in priciple very simple:

1     ...
2     $AxisY =& $Ploarea->getAxis(IMAGE_GRAPH_AXIS_Y);
3     $AxisY->setDataPreprocessor(new Image_Graph_DataPreprocessor_Formatted("%0.1f%%"));
4     ...

This will cause all Y-axis values to be formatted using the format. Another usage could be in the Image_Graph_Marker functionality. For example:

1     ...
2     $Marker =& new Image_Graph_Marker_Value(IMAGE_GRAPH_VALUE_Y);
3     $Marker->setDataPreprocessor(new Image_Graph_DataPreprocessor_Formatted("%0.1f%%"));
4     $Plot->setMarker($Marker);
5     ...

This would cause the graph to display Y-values (Image_Graph_Marker_Value) as markers on the graph in the specified format (i.e. 86.2%).

To summarize: a good way of achieving the above would be to do the following:

1     $Graph =& new Image_Graph(400, 300);
2     $Plotare =& $Graph->add(new Image_Graph_Plotarea());
3     
4     $DataSet =& new Image_Graph_Dataset_Trivial();
5     
6     $XArray[0] = "7 Aug 2004";
7     $XArray[1] = "8 Aug 2004";
8     $XArray[2] = "9 Aug 2004";
9     
10    $DataSet->addPoint(0, 24.4);
11    $DataSet->addPoint(1, 86.2);
12    $DataSet->addPoint(2, 5.7);
13    
14    $Plot =& $PlotArea->addPlot(new Image_Graph_Plot_Line($DataSet));
15    
16    $Marker =& new Image_Graph_Marker_Value(IMAGE_GRAPH_VALUE_Y);
17    $Marker->setDataPreprocessor(new Image_Graph_DataPreprocessor_Formatted("%0.1f%%"));
18    $Plot->setMarker($Marker);
19    
20    $AxisX =& $Ploarea->getAxis(IMAGE_GRAPH_AXIS_X);
21    $AxisX->setDataPreprocessor(new Image_Graph_DataPreprocessor_Array($XArray));
22    
23    $Graph->Done();

Actually these results could be achieved using other Image_Graph_DataPreprocessor's, fx. Image_Graph_DataPreprocessor_Date or Image_Graph_DataPreprocessor_Funtion.