X/Y Plot is a simple PHP chart class for making X/Y graphs. It
includes feature such as mean average and linear regression.
X/Y Plot requires PHP 5.0 or above, since the code is entirely
object-oriented. PHP must be include with GD graphic library
which is standard in most PHP distributions. It has been tested
most recently with PHP 8.2 and runs without warnings.
The hope is that this graphing library will be easy enough to
understand that someone having no prior experience can have it
working within minutes.
Note from the author 2023
There is not a lot of development on this library owing to my
shift away from server-side processing. There is a similar library
based on this unit is available for client-side Javascript available
at aqGraph.DrQue.net. However,
this project has not been abandon.
A special thanks to those who have used this library and provided
feedback.
Note from the author 2008
I wrote this library after trying to find a simple PHP graphing
library with
linear regression. Having found nothing free and
already put together, I just decided to write a library myself.
This isn't the first time I've written a graphing library for a
project and I decided to make it a nice object-oriented setup.
Once it was complete, I decided to explore
phpDocumentor and release
this library to the public. So here it is. This is my first
attempt at creating an auto-documented set of code, so I hope
it turns out useful. - AAQ
The typical location for X/Y Plot is in vendor/xyPlot.
The use of __DIR__ assists in the path being relative
to the current directory.
This is a convention the author uses, but if it doesn't suit
your tastes, simply modify the PHP files XY_Plot.php
and ClipLine.php with your preferred system.
Points
Rendering a data set with points. Each data point is add with
the function addData. This
function takes two parameters: the X and Y location of a data
point.
Before data can be rendered to a chart, a few basic parameters
need to be set. The color of the points to be drawn which is done
through the function setColor.
The span of the data must also be set with the functions
setX_Span and
setY_Span.
Rendering with points and lines is as simple as calling both
rendering functions. This is true of all rendering function.
Remember order of operation—that is, the first rendered plot
will end up on the bottom with subsequent plots over the top.
<?php
// ...
// Render the points and lines to image
$xyPlot->renderWithLines();
$xyPlot->renderPoints();
Rendering a data set with points and linear regression. The
only extra step here is setting the linear regression color
using the function setLinearRegressionColor
and then rendering this plot with renderLinearRegression.
<?php
// ...
// Set linear regression color
$xyPlot->setLinearRegressionColor( $colorMap[ "LightPurple" ] );
// Add some data
$xyPlot->addData( 0, 0 );
$xyPlot->addData( 31, 1 );
// ...
// Render the points and lines to image
$xyPlot->renderWithLines();
$xyPlot->renderPoints();
$xyPlot->renderLinearRegression();
Rendering a data set with mean average. The
only extra step here is setting the mean average color
using the function setAverageColor
and then rendering this plot with
renderMeanPlot.
<?php
// ...
// Set linear regression color
$xyPlot->setAverageColor( $colorMap[ "LightPurple" ] );
// Render the points and lines to image
$xyPlot->renderWithLines();
$xyPlot->renderPoints();
$xyPlot->renderMeanPlot();
// Render the points and lines to image
$xyPlot->renderWithLines();
$xyPlot->renderPoints();
$xyPlot->renderMeanPlot();
$xyPlot->renderLinearRegression();
For this example, multiple charts have been placed on a single image.
This is a standard application of such a function—plotting the data
followed by the first and second derivative of the data on a single
image.
To draw multiple charts on a single image, two additional steps
are needed. The first image is drawn as excepted, using
sizeWindow to place the data in
the correct location. After this, resetData
is called to flush the data in the plot. Then, the window can
be repositioned, new data added to the chart and the chart
rendered to the image.
Vertical auto scaling can be accomplished using
autoScaleY_MinMax. This function will
find the min and max Y values and scale the graph accordingly.
adjustMinMax has one parameter, which
is a rounding value. This can be described as "round to the
nearest". For example, if the largest Y-value is 23 and
the lowest 10 and the rounded value set to 10, the min will
be 10 and max is 30. If the rounded value is 25, the min will
be 0 and the max 25.
In this chart, 4 plots of the same data are made but with different
vertical scales. On the top left, the chart is scaled with no rounding.
Since the minimum value is -21 and the maximum 136, these values are at
the edge. The charts are all labeled on intervals of 50.
Thus, this chart has no labeled on the top or bottom, since those do not
fall on even intervals.
The chart on the top right is auto scaled to the nearest 25. The the
maximum value of 136 is therefore rounded up to 150 and the minimum
value of -21 is rounded down to -25. The divisions are again labeled
on intervals of 50. So the lowest interval is not labeled, since the
chart begins at -25. The highest interval is 150, which does get labeled.
The chart on the bottom left is a more ideal setup. The auto
scale is set to the nearest 50. This is ideal because the
the labeled intervals are also in increments of 50. Thus, the
chart is labeled evenly from top the bottom.
The chart on the bottom right has an auto scale set to the
nearest 100. This leaves empty divisions above and below the
chart, which may be desired in some situations (such as if
linear regression) extends into these areas.
//---------------------------------------------------------------------------
// Draw graph at given scale
//---------------------------------------------------------------------------
function draw(
$scale,
$leftMargin, $topMargin,
$rightMargin, $bottomMargin )
{
global $imageWidth;
global $imageHeight;
global $xyPlot;
// Render the points and lines to image
$xyPlot->renderWithLines();
$xyPlot->renderPoints();
}
?>
Distance gap
Sometimes the data for a chart will be missing chunks of data.
Having a lines connect the points over the missing spans may not
be desired. So the function setMaxX_Distance
defines a maximum separations in X values before leaving a gap between
two points. This helps to visually represent the fact there is missing
data.
There are four grids: vertical major, vertical minor,
horizontal major and horizontal minor. The only difference
between major and minor grids are that minor grids do not
have an extension past the margin or labeled.
Each of the major and minor grids have some common attributes:
scale and color. The methods are as follows:
setX_MinorDivisionScale() - Minor peritoneal scale.
setX_MajorDivisionScale() - Major peritoneal scale.
setY_MinorDivisionScale() - Minor vertical scale.
setY_MajorDivisionScale() - Major vertical scale.
setX_MinorDivisionColor() - Minor peritoneal color.
setX_MajorDivisionColor() - Major peritoneal color.
setY_MinorDivisionColor() - Minor vertical color.
setY_MajorDivisionColor() - Major vertical color.
Major divisions have some additional functionality for labeled.
Division extensions, label color, and label text callbacks.
Division extension is the term for the number of pixels
past the right margin the line extends. This helps denote that
the label belongs to the line. The label text callback
is a function to format the label. These will be explained
latter.
In this example, grids are drawn with custom callback functions
for both the vertical and horizontal scales. In addition,
a custom increment function is used on the horizontal scale
to increment the scale by months. The data for the horizontal
scale is in seconds, and naturally, the seconds/month depends on
the days in the month.
Several graphs can be drawn in the same chat area. This is done
by simply calling resetData and adding new data
to be plotted. The one drawback is the chart must have it's
scale pre-calculated.