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.

Not all plot types work with all data types. In some cases, the data type doesn't make sense for that plot type, or perhaps it just isn't implemented. See Section 3.4, “PHPlot Plot Types” for a list of available plot types and which data types are available for each. Section 3.4.18, “Plot Types and Data Types” contains a summary table of supported plot type / data type combinations.

The following data types are available in PHPlot:

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

This data array 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.10, “Plot Type: pie (Pie Plot)”.) 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.

With data types 'data-data' and 'data-data-error', the independent variable X is explicitly given for each data point. With data types 'data-data-yx' and 'data-data-yx-error', the independent variable Y is explicitly given for each data point. With data type 'data-data-xyz', the independent variables X and Y are explicitly given for each data point. With each of these data types, it is possible to create a data array with duplicate values for the independent variable(s), or points which are out of order. For example, with data type 'data-data', this array has 2 points at X=4, and the 4th row (X=2) is out of order:

// Data type data-data with out-of-order points
$data = array(     // X  Y
            array('', 1, 10),
            array('', 3, 30),
            array('', 4, 40),
            array('', 2, 20),
            array('', 4, 50),
        );

PHPlot will plot the data points as specified in the array, in row order. Depending on the plot type, this may or may not make sense.

With a points plot (which puts a marker at each data point), the data array can legitimately contain duplicate or out-of-order independent variable values (usually X) as shown above. A bubbles plot using the 'data-data-xyz' data type can also contain duplicate or out-of-order points by specifying X and Y values in any order. (However, two bubbles with the same X and Y will overlap, and one might be covered and invisible.)

With plot types ohlc, candlesticks, candlesticks2, and thinbarline, out-of-order points are OK but duplicate independent variable values usually will not produce useful results.

On the other hand, with a lines plot (which draws lines between the points in the order defined by the data array rows), it probably makes no sense to have out-of-order or duplicate independent variable values in the data array. The same is true for plot types area, linepoints, stackedarea, squared, squaredarea, and stackedsquaredarea.

Most 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. (Actually, any non-numeric value works.) For example:

$data = array( array('1996', 45.5),
               array('1997', 53.8),
               array('1998', ''),   # No data available for 1998
               array('1999', 34.1));

(For horizontal plots, the missing value is X not Y.)

With the lines, linepoints, and squared plot types, there are two ways to handle missing points. 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.

The candlesticks, candlesticks2, and ohlc plot types support missing points. Specify all four Y values at the missing point as empty strings. (This does not work with PHPlot-5.4.0 and earlier.)

The area, stackedarea, stackedbars, squaredarea, and stackedsquaredarea plot types do not support missing points. Non-numeric values are taken as zero for these plot types.

All other plot types support missing points and simply ignore the point. That is, no bar, point shape, thinbar line, etc. will be plotted at that position.

With error plots, missing points are represented by an empty string for the dependent variable value. This is the Y value for vertical error plots (data type data-data-error), and the X value for horizontal error plots (data type data-data-yx-error). There still must be two error value entries in the array for each missing point, although the actual values of these will be ignored.

With data type data-data-xyz, missing points are represented by an empty string for the Y value. There still must be a Z value entry in the array for each missing Y, although the Z value is ignored.

There are some rules you need to follow when building data arrays, in order for PHPlot to correctly process your data. The following rules apply to the array indexes, or keys, in your data array.

PHPlot checks the validity of the data array in 3 stages. SetDataValues only checks that it really was given an array, that the array contains zero-based sequential integer keys, and that the values are also arrays.

More extensive checking takes place when the graph is drawn with DrawGraph. At that time, PHPlot checks that the data array is not empty, and that the rows contain a correct number of entries depending on the data type. A third stage of checking takes place for specific plot types. For example, OHLC plots require 4 values, and area plots require the same number of values for each row. (These requirements are documented in Section 3.4, “PHPlot Plot Types”.) If any of these checks fails, PHPlot produces an error image instead of a plot.

An empty plot will be produced if the data array is valid but contains no numeric Y values (X values for horizontal plots). The result has titles, X and Y axis with labels and tick marks (except for pie plots), and other applicable plot features, but no actual plotted data. There is no error or warning from PHPlot when an empty plot is produced.