Introduction

X/Y Plot is a simple PHP chart class for making X/Y graphs. It includes fetches 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 compiled with GD graphic library (which is pretty hard to not have included anyway).

The hope is that this graphing library will be easy enough to understand that someone having no prior experience can it working within minutes.

Note from the author

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

Download

Current version

Version 1.4, released May 29, 2014.

  • Added line thickness.
  • Addressed warnings and notices.
  • Changed function name to lower camel case and class name to upper camel case.
  • Spelling corrections.

BZip 2 (Linux)

Download release 1.4

MD5: c573d098186cacbb7cfe691d3c3aa2bf

SHA1: d32834744cd130aa2fc4d27c1153b52ea1e92252

Zip (Others)

Download release 1.4

MD5: 0f8327313048aa1cf1cc794f6bd7f194

SHA1: 6939082047c93225a2089ecdd2d7688297a3287c

Previous versions

Version 1.0, released January 2, 2008.

BZip 2 (Linux)

Download release 1.0

MD5: 432aa7c74cf769b83ec3bb45cbe42539

SHA1: 6bff6e0464a4541c2d5d1c70f1ae155a03d9e012

PGP signature

Zip (Others)

Download release 1.0

MD5: 95578420c3ad503c7a98ced06c4f87b0

SHA1: 1e17aa3870ff8584c6909286516db3ac025490d6

PGP signature

Manual

Documentation is available on-line, generated by phpDocumentor.

Special note

This module produces warnings and notifications which will interfere with image output. While these issues need to be fix, the quick workaround is to disable PHP error messages.

<?php

// Report only errors.
error_reportingE_ERROR );

?>

License

This software is free, open-source software released under the GNU license.

Author

X/Y Plot is written and maintained by Andrew Que. To get in touch with Andrew Que, visit his contact page

User comments

Examples

Basics

<?php

   
// Include the X/Y Plot library
   
require_once( 'RootDirectory.inc.php' );
   require_once( 
$RootDirectory "Includes/XY_Plot/XY_Plot.php" );

   
//-----------------------------------------------------------
   
$imageWidth     500;
   
$imageHeight    350;
   
//-----------------------------------------------------------

   // Create image
   
$image = @imageCreate$imageWidth$imageHeight )
       or die( 
"Cannot Initialize new GD image stream" );

   
//---------------------------------
   // Create basic color map
   //---------------------------------
   
$colorMap = array();

   
$colorMap"Background" ] = imageColorAllocate$image255255255 );
   
imageColorTransparent$image$colorMap"Background" ] );
   
   
// Create a standard color palette
   
$colorMap"Black"       ] = imageColorAllocate$image,   0,   0,   );
   
$colorMap"Red"         ] = imageColorAllocate$image192,   0,   );
   
$colorMap"Green"       ] = imageColorAllocate$image,   0192,   );
   
$colorMap"Blue"        ] = imageColorAllocate$image,   0,   0192 );
   
$colorMap"Brown"       ] = imageColorAllocate$image,  48,  48,   );
   
$colorMap"Cyan"        ] = imageColorAllocate$image,   0192192 );
   
$colorMap"Purple"      ] = imageColorAllocate$image192,   0192 );
   
$colorMap"LightGray"   ] = imageColorAllocate$image192192192 );

   
$colorMap"DarkGray"    ] = imageColorAllocate$image,  48,  48,  48 );
   
$colorMap"LightRed"    ] = imageColorAllocate$image255,   0,   );
   
$colorMap"LightGreen"  ] = imageColorAllocate$image,   0255,   );
   
$colorMap"LightBlue"   ] = imageColorAllocate$image,   0,   0255 );
   
$colorMap"Yellow"      ] = imageColorAllocate$image255255,   );
   
$colorMap"LightCyan"   ] = imageColorAllocate$image,   0255255 );
   
$colorMap"LightPurple" ] = imageColorAllocate$image255,   0255 );
   
$colorMap"White"       ] = imageColorAllocate$image255255255 );

   
// New plot
   
$xyPlot = new XY_Plot$image );
   
?>

The typical location for X/Y Plot is in Includes/XY_Plot. The file RootDirectory.inc.php should be in the path that requests the script. This file is simply a path to the root directory of the web site relative to the current path.

<?php
   $RootDirectory 
"./";
?>

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.

Example 1 - Points

Point

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.

<?php
   
// Draw borders (define externally)
   
drawBorders000);

   
// New plot
   
$xyPlot = new XY_Plot$image );

   
// Set plot colors
   
$xyPlot->setColor$colorMap"LightRed" ] );

   
// Set point size
   
$xyPlot->setCircleSize);

   
// Setup timeframe
   
$xyPlot->setX_Span0150 );
   
$xyPlot->setY_Span010 );

   
// Add some data
   
$xyPlot->addData0);   $xyPlot->addData86);
   
$xyPlot->addData31);  $xyPlot->addData11);
   
$xyPlot->addData44);  $xyPlot->addData50);
   
$xyPlot->addData11);  $xyPlot->addData83);
   
$xyPlot->addData82);  $xyPlot->addData136);

   
// Render the points to image
   
$xyPlot->renderPoints();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );
   
?>

Example 2 - Lines

Lines

Rendering a data set with lines between the points

<?php
   
// ...

   // Set plot colors
   
$xyPlot->setColor$colorMap"LightRed" ] );

   
// Add some data
   
$xyPlot->addData0);
   
// ...

   // Render the lines to image
   
$xyPlot->renderWithLines();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );
?>

Example 3 - Lines and points

Point and lines

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();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );
?>

Example 4 - Linear regression

Point, lines and linear regression

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->addData0);
   
$xyPlot->addData31);
   
// ...

   // Render the points and lines to image
   
$xyPlot->renderWithLines();
   
$xyPlot->renderPoints();
   
$xyPlot->renderLinearRegression();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );

?>

Example 5 - Mean average

Mean average

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();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );

?>

Example 6 - Margins

Mean average

A chat doesn't have to take up the entire window. In fact, leaving margin space is needed if you are to put in labeled or a legend.

The function sizeWindow is designed to setup the area in which the chart occupies in an image.

<?php
   
// Margins
   
$topMargin         10;
   
$bottomMargin      10;
   
$leftMargin        10;
   
$rightMargin       100;

   
// Draw borders (define externally)
   
drawBorders(
     
$leftMargin$topMargin
     
$rightMargin$bottomMargin );

   
// New plot
   
$xyPlot = new XY_Plot$image );

   
// Setup boundries
   
$xyPlot->sizeWindow
     
$leftMargin$topMargin
     
$imageWidth $rightMargin$imageHeight $bottomMargin );

   
// ...

   // Render the points and lines to image
   
$xyPlot->renderWithLines();
   
$xyPlot->renderPoints();
   
$xyPlot->renderMeanPlot();
   
$xyPlot->renderLinearRegression();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );
    
?>

Example 7 - Multiple charts on an image

Multiple carts

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.

<?php
   $leftMargin        
10;
   
$rightMargin       10;

   
$topMargin         10;
   
$bottomMargin      70;

   
$topMargin2        115;
   
$bottomMargin2     40;

   
$topMargin3        145;
   
$bottomMargin3     10;

   
// New plot
   
$xyPlot = new XY_Plot$image );

   
// Setup boundries
   
$xyPlot->sizeWindow
     
$leftMargin$topMargin
     
$imageWidth $rightMargin$imageHeight $bottomMargin );

   
// ... Add data ...

   // Render the points and lines to image
   
$xyPlot->renderLinearRegression();
   
$xyPlot->renderWithLines();
   
$xyPlot->renderPoints();

   
// Draw borders (define externally)
   
drawBorders(
     
$leftMargin$topMargin2
     
$rightMargin$bottomMargin2 );

   
// Setup boundries
   
$xyPlot->sizeWindow
     
$leftMargin$topMargin2
     
$imageWidth $rightMargin$imageHeight $bottomMargin2 );

   
$xyPlot->resetData();

   
// ... Add data ...

   
$xyPlot->AutoScaleY_MinMax1.0 );
   
$xyPlot->renderMeanPlot();
   
$xyPlot->renderWithLines();


   
$xyPlot->resetData();
   
   
// ... Add data ...
   
   // Draw borders (define externally)
   
drawBorders(
     
$leftMargin$topMargin3
     
$rightMargin$bottomMargin3 );
   
   
// Setup boundries
   
$xyPlot->sizeWindow
     
$leftMargin$topMargin3
     
$imageWidth $rightMargin$imageHeight $bottomMargin3 );
   
   
$xyPlot->AdjustMinMax1.0 );
   
   
$xyPlot->renderMeanPlot();
   
$xyPlot->renderWithLines();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );
?>

Example 8 - Vertical auto scaling

Auto scale

Veticle 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.

<?php
   
// ...

   // Setup timeframe
   
$xyPlot->setX_Span010 );

   
// Setup divisions
   
$xyPlot->setY_MajorDivisionScale50 );
   
$xyPlot->setY_MajorDivisionColor$colorMap"LightGray" ] );
   
$xyPlot->setY_MajorDivisionTextColor$colorMap"Black" ] );

   
// Graph 1
   
draw
     
0.0,
     
$leftMargin1$topMargin1,
     
$rightMargin1$bottomMargin1 );

   
// Graph 2
   
draw
     
25.0,
     
$leftMargin2$topMargin2,
     
$rightMargin2$bottomMargin2 );

   
// Graph 3
   
draw
     
50.0,
     
$leftMargin3$topMargin3,
     
$rightMargin3$bottomMargin3 );

   
// Graph 4
   
draw
     
100.0,
     
$leftMargin4$topMargin4,
     
$rightMargin4$bottomMargin4 );

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );

//---------------------------------------------------------------------------
// Draw graph at given scale
//---------------------------------------------------------------------------
function draw
  
$scale,
  
$leftMargin$topMargin,
  
$rightMargin$bottomMargin )
{
   global 
$imageWidth;
   global 
$imageHeight;
   global 
$xyPlot;

   
// Draw borders (define externally)
   
drawBorders(
     
$leftMargin$topMargin,
     
$rightMargin$bottomMargin );

   
// Setup boundries
   
$xyPlot->sizeWindow(
     
$leftMargin$topMargin,
     
$imageWidth $rightMargin$imageHeight $bottomMargin );

   
// Rescale
   
$xyPlot->AutoScaleY_MinMax$scale );

   
// Draw divisions
   
$xyPlot->drawY_MajorDivisions();

   
// Render the points and lines to image
   
$xyPlot->renderWithLines();
   
$xyPlot->renderPoints();
}

?>

Example 9 - Distance gap

Auto scale

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.

<?php
   
// ...
   
   // Add some data
   
$xyPlot->addData26 );
   
$xyPlot->addData59  );
   
$xyPlot->addData5   );
   
$xyPlot->addData8   );
   
$xyPlot->addData0   );
   
$xyPlot->addData27  );
   
$xyPlot->addData80  );
   
$xyPlot->addData50  );
   
$xyPlot->addData50  );
   
$xyPlot->addData10134 );
   
$xyPlot->addData1184  );
   
$xyPlot->addData12123 );
   
$xyPlot->addData13110 );
   
$xyPlot->addData14158 );
   
$xyPlot->addData15159 );
   
$xyPlot->addData16122 );
   
$xyPlot->addData17170 );
   
$xyPlot->addData18139 );
   
$xyPlot->addData19218 );
   
$xyPlot->addData20208 );
   
$xyPlot->addData21249 );
   
// Gap in data
   
$xyPlot->addData33319 );
   
$xyPlot->addData34382 );
   
$xyPlot->addData35374 );
   
$xyPlot->addData36378 );
   
$xyPlot->addData37344 );
   
$xyPlot->addData38354 );
   
$xyPlot->addData39412 );
   
$xyPlot->addData40442 );
   
$xyPlot->addData41390 );
   
$xyPlot->addData42465 );
   
$xyPlot->addData43460 );
   
$xyPlot->addData44488 );
   
$xyPlot->addData45484 );
   
$xyPlot->addData46476 );
   
$xyPlot->addData47514 );
   
$xyPlot->addData48522 );

   
// Auto scale
   
$xyPlot->AdjustMinMax20 );

   
// Max distance of 10 units
   
$xyPlot->setMaxX_Distance10 );
   
   
// Render the points and lines to image
   
$xyPlot->renderLinearRegression();
   
$xyPlot->renderWithLines();
   
$xyPlot->renderPoints();

   
// Output image
   
header"Content-Type: image/png" );
   
imagePNG$image );

?>

Example 10 - Basic grids

Simple grids

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.

  • setX_MajorDivisionTextColor() - Vertical label color
  • setY_MajorDivisionTextColor() - Horitonal label color
  • setX_MajorTextCallback() - Horitonal label callback
  • setY_MajorTextCallback() - Vertical label callback

This example shows how to setup a basic grid with labeled. Major and minor grid lines are drawn.

View source code

Example 11 - Advanced Grids

Advanced grids

In this example, grids are Dwain 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.

View source code

Example 12 - Additional data

Statistics

This example shows the various statistics that can be generated from the data.

View source code

Example 13 - Multiple graphs

Advanced grids

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.

View source code

Example 14 - Clipping

Clipping

The graphing library has build into it clipping functions. Data that extends beyond the margins is simply chopped off.

View source code