Abstract
This section describes how data need to be organized for use with PHPlot.
The data values to be plotted are presented to PHPlot with SetDataValues. In all cases, the data values are stored in a PHP array. This data array contains elements, themselves also arrays, which are called records. Each record contains labels and/or data values. The 'data type' of the data array determines how PHPlot will interpret the records in the data array. To set the data type, use SetDataType.
The following data types are available in PHPlot:
Each record contains a label, followed by one or more Y values:
array('label', y1, y2, ...).
The corresponding X value for all Y values in a record is implicit: the
first data record is at X=0, the second at X=1, etc.
This data type works with all plot types.
Each record contains a label, an X value, then one or more Y values:
array('label', x, y1, y2, ...).
This is the same as 'text-data' except the X values are explicitly given.
This data type works with all plot types except bars and stackedbars.
Note that with data type 'data-data', it is possible to create a data array with duplicate X values, or X values out of order. Depending on the plot type, this may or may not make sense. For example, with a point plot (which puts a marker at each data point), the data array can legitimately contain duplicate and out-of-order X values. With a line plot (which connects adjacent points in the data array with a line), it probably makes no sense to have out-of-order or duplicate X values in the data array.
Each record contains a label, an X value, then sets of 3 values for each Y
point: the Y value, error in the positive direction, and error in the
negative direction:
array('label', x, y1, e1+, e1-, y2, e2+, e2-, ...).
This data type works with plot types lines, points, and linepoints only.
Note that both errors (e+ and e-) are given as positive numbers. They represent the absolute value of the error in the positive and negative directions respectively.
Each record contains a label and a single value:
array('label', factor).
This data type is only for the pie chart plot type.
In most of the examples in this manual, the data array is built from constant values in PHP code. For example:
$data = array(
array('', 0, 0, 0, 0),
array('', 1, 1, 1, -10),
array('', 2, 8, 4, -20),
array('', 3, 27, 9, -30),
array('', 4, 64, 16, -40)
array('', 5, 125, 25, -50)
);
Which contains 6 records, each with an empty label, an X value (assuming the data type is 'data-data'), and then 3 Y values representing 3 data sets to plot.
In a real application, of course, the data values will most likely come
from a calculation, perhaps using values from a database.
This section provides a few sample code fragments which construct
data arrays. We use the PHP ability to append a new value to the end of an
array using $array[] = ....
This code fragment creates a data array of type 'text-data' with three data sets for Y=X+1, Y=X*X/2, and Y=X*X*X/3.
$data = array();
for ($x = 0; $x <= 5; $x++) $data[] = array('', $x+1, $x*$x/2, $x*$x*$x/3);
This code fragment creates a data array of type 'data-data' with about 100 points from the equation X * Y = 10.
$data = array();
for ($x = 1.0; $x <= 10.0; $x += 0.1) $data[] = array('', $x, 10.0/$x);
The next code fragments use database queries to build data arrays for PHPlot.
In many cases, you can create a query such that the returned columns
correspond to the format of a PHPlot data array record.
The first query result column should be the data label, the second (for
data type 'data-data' only) should be the X value, and subsequent column
results should be one or more Y values (depending on the number of datasets you are plotting).
(Pie charts work differently - see Section 3.4.5, “Plot Type: pie (Pie Chart)”.)
You aren't limited to simple table lookups - you can use the full power of the SQL language
to combine tables and perform calculations on the data.
Be sure to use ORDER BY in your SQL query to order the results,
or you will not get predictable plots.
Database access methods differ. This code is for PostgreSQL; for MySQL there are
similar functions like mysql_fetch_row().
$r = pg_query($db, 'SELECT ...'); if (!$r) exit(); $data = array(); $n_rows = pg_num_rows($r); for ($i = 0; $i < $n_rows; $i++) $data[] = pg_fetch_row($r, $i); ... $plot->SetDataValues($data);
This works because pg_fetch_row assigns the result
columns from the query to sequentially numbered elements in the array.
Using data arrays from database query results also works if the result
columns are in an array which is indexed by the field name, because PHPlot
converts the data array to use numeric indexes.
So with PostgreSQL you can use pg_fetch_assoc().
You can also use pg_fetch_array(),
but only if you specify the type as PGSQL_ASSOC
or PGSQL_NUM.
The default type PGSQL_BOTH will not work,
because the result array will contain the data values duplicated
under both number and field-name indexes,
and PHPlot will see both copies of the data.
Going even further, with a properly designed query you can use
pg_fetch_all() to fetch the entire query result and
assign it to a data array with one statement.
$r = pg_query($db, 'SELECT ...'); if (!$r) exit(); $data = pg_fetch_all($r); ... $plot->SetDataValues($data);
This uses field-name indexes in the array representing each row, but as noted above PHPlot will convert the data array to use numeric indexes.
The 'lines' (Section 3.4.4, “Plot Type: lines (Lines Graph)”) and 'squared' (Section 3.4.7, “Plot Type: squared (Step Plot)”) plot types support the concept of missing points. A missing point is represented in your data array with an empty string instead of a Y value. For example:
$data = array( array('1996', 45.5),
array('1997', 53.8),
array('1998', ''), # No data available for 1998
array('1999', 34.1));
By default, PHPlot will act as if the missing point does not exist, connecting the points before it and after it. You can use SetDrawBrokenLines to leave a gap at the missing point instead.