Subversion Repositories cheapmusic

Rev

Blame | Last modification | View Log | RSS feed 

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>3.3. PHPlot Data Types</title><link rel="stylesheet" type="text/css" href="phplotdoc.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="PHPlot Reference Manual" /><link rel="up" href="concepts.html" title="Chapter 3. PHPlot Concepts" /><link rel="prev" href="conc-overview.html" title="3.2. Programming Overview" /><link rel="next" href="conc-plottypes.html" title="3.4. PHPlot Plot Types" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.3. PHPlot Data Types</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="conc-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 3. PHPlot Concepts</th><td width="20%" align="right"> <a accesskey="n" href="conc-plottypes.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="conc-datatypes"></a>3.3. PHPlot Data Types</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
This section describes how data need to be organized for use with PHPlot.
  </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-datatypes-types"></a>3.3.1. Available Data Types</h3></div></div></div><p>
The data values to be plotted are presented to PHPlot with
<a class="xref" href="SetDataValues.html" title="SetDataValues"><span class="refentrytitle">SetDataValues</span></a>.
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 <a class="xref" href="SetDataType.html" title="SetDataType"><span class="refentrytitle">SetDataType</span></a>.
</p><p>
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 <a class="xref" href="conc-plottypes.html" title="3.4. PHPlot Plot Types">Section 3.4, &#8220;PHPlot Plot Types&#8221;</a> for a list of available
plot types and which data types are available for each.
<a class="xref" href="conc-plottypes.html#conc-plottype-datatype" title="3.4.18. Plot Types and Data Types">Section 3.4.18, &#8220;Plot Types and Data Types&#8221;</a> contains a summary table of
supported plot type / data type combinations.
</p><p>
The following data types are available in PHPlot:

</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a id="text-data"></a>text-data</span></dt><dd><p>
This is the simplest data type, used for vertical plots where the X values are
implied, rather than specified, and there are one or more Y values for each X.
When using this data type, each record (row) in the data array contains a
label (which can be empty), followed by one or more Y values:
<code class="literal">array('label', y1, y2, ...)</code>.
PHPlot assigns X=0.5 to the first data record, X=1.5 to the second data record,
and so on.
      </p></dd><dt><span class="term"><a id="data-data"></a>data-data</span></dt><dd><p>
This data type is similar to <code class="literal">text-data</code> except that the
values of the independent variable X are supplied in the data array rather
than being implied. This is used for vertical plots.
When using this data type, each record (row) in the data array contains a
label (which can be empty), an X value, then one or more Y values:
<code class="literal">array('label', x, y1, y2, ...)</code>.
      </p></dd><dt><span class="term"><a id="data-data-error"></a>data-data-error</span></dt><dd><p>
This data type is used to make error plots - a plot showing values and
error ranges at each point. This is for vertical plots.
When using this data type, each record (row) in the data array contains a
label (which can be empty), 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:
<code class="literal">array('label', x, y1, e1+, e1-, y2, e2+, e2-, ...)</code>.
      </p><p>
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. These must be greater than or equal to zero.
      </p></dd><dt><span class="term"><a id="text-data-single"></a>text-data-single</span></dt><dd><p>
This data type is only used for pie charts, where the size of each pie
segment is represented by a single row and value. (There are other data types
that work with pie charts too.)
When using this data type, each record (row) in the data array contains a
label (which can be empty), and a single value:
<code class="literal">array('label', value)</code>.
      </p></dd><dt><span class="term"><a id="text-data-yx"></a>text-data-yx</span></dt><dd><p>
This data type is used for horizontal plots where the Y values are implied,
rather than specified, and there are one or more X values for each Y.
(For horizontal plots, Y is the independent variable.)
When using this data type, each record (row) in the data array contains a
label (which can be empty), followed by one or more X values:
<code class="literal">array('label', x1, x2, ...)</code>.
PHPlot assigns Y=0.5 to the first data record, Y=1.5 to the second data record,
and so on.
This is the horizontal plot variation of <code class="literal">text-data</code>.
      </p></dd><dt><span class="term"><a id="data-data-yx"></a>data-data-yx</span></dt><dd><p>
This data type is used for horizontal plots where the Y values are supplied
in the data array rather than being implied.
(For horizontal plots, Y is the independent variable.)
When using this data type, each record (row) in the data array contains a
label (which can be empty), a Y value, then one or more X values:
<code class="literal">array('label', y, x1, x2, ...)</code>.
This is the horizontal plot variation of <code class="literal">data-data</code>.
      </p></dd><dt><span class="term"><a id="data-data-yx-error"></a>data-data-yx-error</span></dt><dd><p>
This data type is used to make horizontal error plots - a plot showing values
and error ranges at each point.
When using this data type, each record (row) in the data array contains a
label (which can be empty), a Y value, then sets of 3 values for each X
point: the X value, error in the positive direction, and error in the
negative direction:
<code class="literal">array('label', y, x1, e1+, e1-, x2, e2+, e2-, ...)</code>.
      </p><p>
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. These must be greater than or equal to zero.
      </p><p>
Note that you can also use the alias <code class="literal">data-data-error-yx</code>
for horizontal error plots.
      </p></dd><dt><span class="term"><a id="data-data-xyz"></a>data-data-xyz</span></dt><dd><p>
This data type is used for plots which have a 3D component.
When using this data type, each record (row) in the data array contains a
label (which can be empty), an X value, then one or more pairs of Y and Z
values:
<code class="literal">array('label', x, y1, z1, y2, z2, ...)</code>.
A single data set in an array using this data type contains (x, y, z)
triplets. Multiple data sets can also be represented, with each row in the
array containing an X value and the corresponding Y and Z values.
      </p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-datatypes-array"></a>3.3.2. Building Data Arrays</h3></div></div></div><p>
In most of the examples in this manual, the data array is built from
constant values in PHP code. For example:
</p><pre class="programlisting">$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),
);
</pre><p>
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.
</p><p>
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 <code class="literal">$array[] = ...</code>.
</p><p>
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.
</p><pre class="programlisting">$data = array();
for ($x = 0; $x &lt;= 5; $x++) $data[] = array('', $x+1, $x*$x/2, $x*$x*$x/3);
</pre><p>
</p><p>
This code fragment creates a data array of type 'data-data' with about
100 points from the equation X * Y = 10.
</p><pre class="programlisting">$data = array();
for ($x = 1.0; $x &lt;= 10.0; $x += 0.1) $data[] = array('', $x, 10.0/$x);
</pre><p>
</p><p>
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 <a class="xref" href="conc-plottypes.html#plottype-pie" title="3.4.10. Plot Type: pie (Pie Plot)">Section 3.4.10, &#8220;Plot Type: pie (Pie Plot)&#8221;</a>.)
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 <code class="literal">ORDER BY</code> in your SQL query to order the results,
or you will not get predictable plots.
</p><p>
Database access methods differ. This code is for PostgreSQL; for MySQL there are
similar functions like <code class="function">mysql_fetch_row()</code>.
</p><pre class="programlisting">$r = pg_query($db, 'SELECT ...');
if (!$r) exit();
$data = array();
$n_rows = pg_num_rows($r);
for ($i = 0; $i &lt; $n_rows; $i++) $data[] = pg_fetch_row($r, $i);
...
$plot-&gt;SetDataValues($data);
</pre><p>
This works because <code class="function">pg_fetch_row</code> assigns the result
columns from the query to sequentially numbered elements in the array.
</p><p>
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 <code class="function">pg_fetch_assoc()</code>.
You can also use <code class="function">pg_fetch_array()</code>,
but only if you specify the type as <code class="literal">PGSQL_ASSOC</code>
or <code class="literal">PGSQL_NUM</code>.
The default type <code class="literal">PGSQL_BOTH</code> 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.
</p><p>
Going even further, with a properly designed query you can use
<code class="function">pg_fetch_all()</code> to fetch the entire query result and
assign it to a data array with one statement.
</p><pre class="programlisting">$r = pg_query($db, 'SELECT ...');
if (!$r) exit();
$data = pg_fetch_all($r);
...
$plot-&gt;SetDataValues($data);
</pre><p>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-datatypes-order"></a>3.3.3. Duplicate and Out-of-order Points</h3></div></div></div><p>
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:
</p><pre class="programlisting">// 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),
        );
</pre><p>
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.
</p><p>
With a <a class="link" href="conc-plottypes.html#plottype-points" title="3.4.11. Plot Type: points (Styled Dot Plot)">points</a> 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 <a class="link" href="conc-plottypes.html#plottype-bubbles" title="3.4.4. Plot Type: bubbles (Bubble Plot)">bubbles</a> 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.)
</p><p>
With plot types
<a class="link" href="conc-plottypes.html#plottype-ohlc" title="3.4.9. Plot Type: ohlc (Basic OHLC Plot)">ohlc</a>,
<a class="link" href="conc-plottypes.html#plottype-candlesticks" title="3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)">candlesticks</a>,
<a class="link" href="conc-plottypes.html#plottype-candlesticks2" title="3.4.6. Plot Type: candlesticks2 (OHLC Filled Candlesticks Plot)">candlesticks2</a>, and
<a class="link" href="conc-plottypes.html#plottype-thinbarline" title="3.4.17. Plot Type: thinbarline (Thin Bar Line Plot)">thinbarline</a>,
out-of-order points are OK but duplicate independent variable values
usually will not produce useful results.
</p><p>
On the other hand, with a <a class="link" href="conc-plottypes.html#plottype-lines" title="3.4.8. Plot Type: lines (Lines Plot)">lines</a> 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
<a class="link" href="conc-plottypes.html#plottype-area" title="3.4.1. Plot Type: area (Area Plot)">area</a>,
<a class="link" href="conc-plottypes.html#plottype-linepoints" title="3.4.7. Plot Type: linepoints (Lines and Points Plot)">linepoints</a>,
<a class="link" href="conc-plottypes.html#plottype-stackedarea" title="3.4.14. Plot Type: stackedarea (Stacked Area Plot)">stackedarea</a>,
<a class="link" href="conc-plottypes.html#plottype-squared" title="3.4.12. Plot Type: squared (Squared Plot)">squared</a>,
<a class="link" href="conc-plottypes.html#plottype-squaredarea" title="3.4.13. Plot Type: squaredarea (Squared Area Plot)">squaredarea</a>, and
<a class="link" href="conc-plottypes.html#plottype-stackedsquaredarea" title="3.4.16. Plot Type: stackedsquaredarea (Stacked Squared Area Plot)">stackedsquaredarea</a>.

</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-datatypes-missing"></a>3.3.4. Missing Data in Data Arrays</h3></div></div></div><p>
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:
</p><pre class="programlisting">$data = array( array('1996', 45.5),
               array('1997', 53.8),
               array('1998', ''),   # No data available for 1998
               array('1999', 34.1));
</pre><p>
(For horizontal plots, the missing value is X not Y.)
</p><p>
With the <a class="link" href="conc-plottypes.html#plottype-lines" title="3.4.8. Plot Type: lines (Lines Plot)">lines</a>,
<a class="link" href="conc-plottypes.html#plottype-linepoints" title="3.4.7. Plot Type: linepoints (Lines and Points Plot)">linepoints</a>, and
<a class="link" href="conc-plottypes.html#plottype-squared" title="3.4.12. Plot Type: squared (Squared Plot)">squared</a> 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
<a class="xref" href="SetDrawBrokenLines.html" title="SetDrawBrokenLines"><span class="refentrytitle">SetDrawBrokenLines</span></a> to leave a gap at the missing point
instead.
</p><p>
The <a class="link" href="conc-plottypes.html#plottype-candlesticks" title="3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)">candlesticks</a>,
<a class="link" href="conc-plottypes.html#plottype-candlesticks2" title="3.4.6. Plot Type: candlesticks2 (OHLC Filled Candlesticks Plot)">candlesticks2</a>,
and <a class="link" href="conc-plottypes.html#plottype-ohlc" title="3.4.9. Plot Type: ohlc (Basic OHLC Plot)">ohlc</a> 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.)
</p><p>
The <a class="link" href="conc-plottypes.html#plottype-area" title="3.4.1. Plot Type: area (Area Plot)">area</a>,
<a class="link" href="conc-plottypes.html#plottype-stackedarea" title="3.4.14. Plot Type: stackedarea (Stacked Area Plot)">stackedarea</a>,
<a class="link" href="conc-plottypes.html#plottype-stackedbars" title="3.4.15. Plot Type: stackedbars (Stacked Bar Plot)">stackedbars</a>,
<a class="link" href="conc-plottypes.html#plottype-squaredarea" title="3.4.13. Plot Type: squaredarea (Squared Area Plot)">squaredarea</a>, and
<a class="link" href="conc-plottypes.html#plottype-stackedsquaredarea" title="3.4.16. Plot Type: stackedsquaredarea (Stacked Squared Area Plot)">stackedsquaredarea</a>
plot types do not support missing points.
Non-numeric values are taken as zero for these plot types.
</p><p>
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.
</p><p>
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 <a class="link" href="conc-datatypes.html#data-data-error">data-data-error</a>),
and the X value for horizontal error plots
(data type <a class="link" href="conc-datatypes.html#data-data-yx-error">data-data-yx-error</a>).
There still must be two error value entries in the array for each missing
point, although the actual values of these will be ignored.
</p><p>
With data type <a class="link" href="conc-datatypes.html#data-data-xyz">data-data-xyz</a>, 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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-datatypes-indexes"></a>3.3.5. Data Array Indexes</h3></div></div></div><p>
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.
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Your data array must be indexed using sequential integers starting with zero.
This is automatically true if you build an array with the empty-brackets
syntax (<code class="literal">$mydata[] = ...</code>), or if you use the
<code class="literal">array(...)</code> construct without specifying keys.
Note that this refers only to the data array itself, not the elements of
the data array - the records.
      </p></li><li class="listitem"><p>
The data records, which are elements of the data array, are also arrays.
These record arrays are processed by PHPlot using the
<code class="literal">array_values()</code> function. This means the array keys
are ignored, and the elements of the record are processed in the same order
as they were assigned. As with the data array itself, you can use the
empty-brackets syntax, or the array() language construct, to build records
in the data array. You can also use words (such as database query result
fields) as indexes, as long as the assignments are made in the correct
order.
      </p></li></ul></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-datatypes-validation"></a>3.3.6. Data Array Validation</h3></div></div></div><p>
PHPlot checks the validity of the data array in 3 stages.
<a class="xref" href="SetDataValues.html" title="SetDataValues"><span class="refentrytitle">SetDataValues</span></a> 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.
</p><p>
More extensive checking takes place when the graph is drawn with
<a class="xref" href="DrawGraph.html" title="DrawGraph"><span class="refentrytitle">DrawGraph</span></a>. 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
<a class="xref" href="conc-plottypes.html" title="3.4. PHPlot Plot Types">Section 3.4, &#8220;PHPlot Plot Types&#8221;</a>.) If any of these checks fails,
PHPlot produces an error image instead of a plot.
</p><p>
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.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="conc-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="concepts.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="conc-plottypes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.2. Programming Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.4. PHPlot Plot Types</td></tr></table></div></body></html>