3.4. PHPlot Plot Types

This section describes the PHPlot plot types and their individual data type requirements.

Plot types determine the overall look of the graphical representation of the data values. To select the plot type, use SetPlotType. The following plot types are available:

Plot TypeDescription
area plot thumbnail areaFilled areas between lines. Also known as cumulative line plot or component line plot.
bars plot thumbnail barsFilled bars with optional 3-D look. Multiple datasets are offset.
box plot thumbnail boxesBox plot, showing a 5-number statistical summary of a data set.
bubbles plot thumbnail bubblesA scatter-point plot using bubbles (filled circles), with the bubble size proportional to a Z value.
candlesticks plot thumbnail candlesticksAn Open/High/Low/Close (OHLC) financial plot using filled and unfilled candlesticks.
candlesticks2 plot thumbnail candlesticks2An Open/High/Low/Close (OHLC) financial plot using filled candlesticks.
linepoints plot thumbnail linepointsLines between points, with a marker at each point, and optional error bars.
lines plot thumbnail linesStraight lines between data points, with optional error bars.
ohlc plot thumbnail ohlcA basic Open/High/Low/Close (OHLC) financial plot using lines and ticks.
pie plot thumbnail piePie chart with or without 3-D affects.
points plot thumbnail pointsDraws a marker at each data point, with optional error bars.
squared plot thumbnail squaredStepped lines, also called squared lines.
squaredarea plot thumbnail squaredareaFilled area between stepped lines.
stackedarea plot thumbnail stackedareaFilled areas between lines, with multiple data sets accumulated.
stackedbars plot thumbnail stackedbarsFilled bars with optional 3-D look. Multiple data sets are accumulated and the sum is graphed.
stackedsquaredarea plot thumbnail stackedsquaredareaFilled areas between stepped lines, with multiple data sets accumulated.
thinbarline plot thumbnail thinbarlineVertical lines from the X axis to the value, or horizontal lines from the Y axis to the value. Also known as impulse.

3.4.1. Plot Type: area (Area Plot)

This plot type draws filled areas between lines. This is often called a cumulative line plot or component line plot. Each data set (set of corresponding Y values from each record in the data array) is plotted in order, with the area between each line and the next line filled solid. The area between the last line and the X axis[2] is also filled. The data must be arranged so the values are (generally) decreasing within each row, because later drawn filled areas will cover previously drawn areas.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

A minimum of 2 rows (X values and corresponding Y value(s)) is required for this plot type. If there are fewer than 2 rows, an empty plot will be produced.

This plot type uses the absolute value of each supplied Y, because negative values do not make sense here. Missing values are taken as zero. All records in the data array must have the same number of Y values.

The areas are filled with colors as set with SetDataColors. If data borders are enabled with SetDrawDataBorders, then a border is drawn around each area fill, using the colors set with SetDataBorderColors. (Data borders for area plots were added in PHPlot-6.2.0.) By default, no data borders are drawn.

An example of this plot type can be seen in Section 5.3, “Example - Area Plot”.

The area plot type is similar to the stackedarea plot type. When plotting a single data set (1 Y value per X), the two plot types are identical.

3.4.2. Plot Type: bars (Bar Plot)

This plot type draws a bar chart, with filled rectangles. Both vertical and horizontal bar charts are available. The bars are centered on the X values (for vertical charts), or on the Y values (for horizontal charts). The rectangles can have a 3-D look (without borders, by default), or be flat (with borders, by default). Multiple data-set plots work, with each one producing a set of bars offset from the previous set.

For vertical bars, use data type text-data. The data X values are assumed to be at 0.5+N for N=0,1,2... For horizontal bars, use data type text-data-yx. The data Y values are assumed to be at 0.5+N for N=0,1,2... No other data type works with bar graphs.

If shading is on with SetShading (default is on with value 5 pixels), then the bars have a 3-D look. If shading is off (SetShading(0)), the bars are flat rectangles. The filled bar colors are set with SetDataColors. Data borders are drawn by default when shading is off. Use SetDrawDataBorders to enable or disable the borders. If the borders are on, the border colors can be set with SetDataBorderColors.

An empty string (or any non-numeric value) for the dependent variable (Y for vertical plots, X for horizontal plots) indicates a missing point. No bar will be drawn at missing point positions.

See also Section 4.7.1, “Tuning Bar Charts”.

Examples of this plot type can be seen in Section 5.4, “Example - Bar Chart”, Section 5.5, “Example - Unshaded Bar Chart”, Section 5.6, “Example - Bar Chart, Label Options”, Section 5.19, “Example - Bar Chart with Data Value Labels”, and Section 5.27, “Example - Horizontal Bar Chart”.

The bars plot type is similar to the stackedbars plot type. When plotting a single data set, the two plot types are identical.

Horizontal bar plots were added in PHPlot-5.1.2.

3.4.3. Plot Type: boxes (Box Plot)

A box plot uses groups of 5 or more numbers to plot a statistical summary of a data set. (This is sometimes called a box and whisker plot.) The first 5 Y values in each row are referred to as Ymin, YQ1, Ymid, YQ3, and Ymax. By convention, these represent:

ValueDescription
YminMinimum value. Sometimes used as 5th or 9th percentile instead.
YQ1Lower quartile - 25th percentile, meaning 25% of the data points are below this value, and 75% are above.
YmidMedian - 50th percentile, meaning half the data points are below this value, and half are above.
YQ3Upper quartile - 75th percentile, meaning 75% of the data points are below this value, and 25% are above.
YmaxMaximum value. Sometimes used as 95th or 91st percentile instead.

Any additional numbers (beyond 5) in each row represent outliers. These are generally points outside the range of Ymin and Ymax, and are used when Ymin and Ymax are for some low and high (respectively) percentile values, such as 5th and 95th.

At each X value, a box plot has the following features:

  • box: A rectangular box is drawn from YQ1 to YQ3.

  • belt: A horizontal line is drawn through the box at the median position Ymid.

  • lower whisker: A vertical line is drawn from the bottom center of the box at the YQ1 position down to the Ymin position, and an upside-down 'T' is drawn at Ymin.

  • upper whisker: A vertical line is drawn from the top center of the box at the YQ3 position up to the Ymax position, and a 'T' is drawn at Ymax.

  • outliers: If there are any additional values in the row, a marker point (similar to that drawn in a points plot) is drawn at each given Y value.

Note that PHPlot does not force any particular interpretation on the numbers in each row. It draws a box, belt, two whiskers, and zero or more outliers at each X as described above. PHPlot does however require that the numbers be in order: Ymin <= YQ1 <= Ymid <= YQ3 <= Ymax Any outlier values should be greater than Ymax, or less than Ymin, but PHPlot does not enforce that.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

This plot type requires 5 or more Y values for each X. Multiple data sets are not supported. A missing point is indicated by using an empty string (or any non-numeric value) for either YQ1 or YQ3 (or both). Nothing at all will be drawn at that position. If the median value Ymin is an empty string or non-numeric, the belt (median line) is not drawn, but the rest of the box plot features are. If either Ymin or Ymax are empty strings or non-numeric, the corresponding whisker and 'T' end will not be drawn. Finally, any empty strings or non-numeric values in the outlier positions of the data array row are ignored. Regardless of missing values, every row in the data array must still have at least 5 entries for Y values.

This plot type uses 4 colors from the data colors array, indexes 0 through 3. You can use SetDataColors to change the colors used in the plot. Color 0 is used for the box, color 1 is used for the belt (median line), color 2 is used for the outliers, and color 3 is used for the whiskers (including the 'T' at the top and bottom).

SetLineWidths can be used to set line widths. Index 0 will be used to draw the box, index 1 is used to draw the belt (median line), and index 2 is used to draw the whiskers and 'T' ends.

The whiskers in a box plot are drawn using the first line style, which defaults to a solid line. Box plots sometimes use dashed lines for the whiskers. Use SetLineStyles('dashed') to have the whiskers drawn as dashed lines. All other features of a box plot (box, belt, and 'T' ends) use solid lines.

See also Section 4.7.2, “Tuning Box Plots”.

Examples of this plot type can be seen in Section 5.50, “Example - Box Plot with Data Reduction” and Section 5.51, “Example - Box Plot with Outliers and Styles”.

Box plots were added in PHPlot-6.1.0.

3.4.4. Plot Type: bubbles (Bubble Plot)

This plot type produces a scatter-plot using filled circles, with the diameter of each circle representing a Z value for the point. The range of Z values in the plot is linearly mapped into a range of bubble sizes, with the lowest plotted Z value producing a bubble with the minimum size, and the largest Z value producing the largest bubble. The smallest and largest bubble sizes are automatically calculated based on the plot area size, but see also Section 4.7.3, “Tuning Bubble Plots”. Note: There is no way to display the actual numeric Z values on the plot.

Multiple data sets work, with more than one (Y,Z) pair for each X. The bubbles will be drawn using the corresponding colors in the data colors array, as set with SetDataColors. With multiple data sets (or even a single data set), you may find the plot easier to read when using semi-transparent data colors as described in Section 4.3.3, “Using Variable Transparency (Alpha) in PHPlot”.

This plot type only works with data type data-data-xyz. Each (X,Y,Z) triplet from the data array produces a bubble on the plot.

An empty string (or any non-numeric value) for Y indicates a missing point and will not be plotted. A corresponding Z entry must be provided in the data array, but the value is ignored.

See also Section 4.7.3, “Tuning Bubble Plots”.

An example of this plot type can be seen in Section 5.40, “Example - Bubbles Plot”.

Bubble plots were added in PHPlot-5.5.0.

3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)

This plot type represents the changing price of a financial instrument (such as a stock or other security) over time. At each time point, 4 values are plotted: the opening price, the highest price, the lowest price, and the closing price. The candlesticks plot type is one of three Open/High/Low/Close (OHLC) plot types available. It shows the opening and closing prices as the top and bottom of a narrow rectangle (the candlestick), with an upper wick showing the highest price, and a lower wick showing the lowest price. The candlestick body is drawn solid filled if the closing price is lower than the opening price, and as an outline (unfilled) if the closing price is higher than the opening price. (For a variation on this, see candlesticks2.)

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

This plot type requires exactly 4 Y values for each X. These represent the Open, High, Low, and Close prices in that order. Multiple data sets are not supported. A missing point is indicated by using four empty strings (or any non-numeric value) for the 4 Y values. (Missing points were not allowed for this plot type in PHPlot-5.4.0 and earlier.)

This plot type uses 4 colors from the data colors array, index 0 through 3. If the security closed lower than it opened for that time period, then color 0 is used for the candlestick body, and color 2 is used for the upper and lower wicks. If the security closed higher or the same as it opened for that time period, then color 1 is used for the candlestick body, and color 3 is used for the upper and lower wicks.

SetLineWidths can be used to set line widths. Index 0 will be used to draw the candlestick bodies, however this only applies to outlined candlestick bodies (drawn when the security closes up). The line width is not used for filled candlestick bodies (drawn when the security closes down). Line width index 1 will be used to draw the wicks.

See also Section 4.7.4, “Tuning OHLC Charts”.

An example of this plot type can be seen in Section 5.31, “Example - Candlesticks OHLC (Open, High, Low, Close) Financial Plot”.

This plot type was added in PHPlot-5.3.0.

3.4.6. Plot Type: candlesticks2 (OHLC Filled Candlesticks Plot)

This plot type represents the changing price of a financial instrument (such as a stock or other security) over time. The candlesticks2 plot type is the same as the candlesticks plot type, except the candlestick bodies are always drawn filled, regardless of whether the security closes up or down.

Color usage is the same as with candlesticks plots, with the first 4 data colors used (index 0 through 3). If the security closed down, color 0 is used for the body, and color 2 is used for the wicks. If the security closed up or the same, color 1 is used for the body, and color 3 is used for the wicks. Be sure to set data colors 0 and 2 with SetDataColors for this plot type. Unlike candlesticks, candlesticks2 plots use only color to show the difference between a security closing up or closing down. The default colors in these slots (sky blue and orange) are probably not appropriate.

Line width usage is similar to candlesticks plots, except that the candlestick bodies are always filled so line width index 0 (body outline line width) is never used. Line width index 1 is used for the wicks.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

This plot type requires exactly 4 Y values for each X. These represent the Open, High, Low, and Close prices in that order. Multiple data sets are not supported. A missing point is indicated by using four empty strings (or any non-numeric value) for the 4 Y values. (Missing points were not allowed for this plot type in PHPlot-5.4.0 and earlier.)

See also Section 4.7.4, “Tuning OHLC Charts”.

An example of this plot type can be seen in Section 5.32, “Example - Filled Candlesticks OHLC (Open, High, Low, Close) Financial Plot”.

This plot type was added in PHPlot-5.3.0.

3.4.7. Plot Type: linepoints (Lines and Points Plot)

This plot type draws a line graph with a marker at each point, thus combining the 'lines' and 'points' plot types.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2... It also works with data-data-error for error plots. These produce the usual vertical plots.

This plot type also works with data types text-data-yx and data-data-yx to produce horizontal plots, and with data type data-data-yx-error to produce horizontal error plots. For 'text-data-yx', the data Y values are assumed to be at 0.5+N for N=0,1,2... (Horizontal 'linepoints' plots were added in PHPlot-6.0.0. Horizontal 'linepoints' error plots were added in PHPlot-6.1.0.)

An empty string (or any non-numeric value) for the dependent variable (Y for vertical plots, X for horizontal plots) indicates a missing point. PHPlot can either skip the line segments around missing points, or connect the adjacent points. See SetDrawBrokenLines for details.

Line and marker colors for each line are set with SetDataColors. Marker styles for each line are set with SetPointShapes. Marker sizes for each line are set with SetPointSizes. Line widths for each line are set with SetLineWidths. Line styles (solid or dashed) for each line are set with SetLineStyles.

You can also suppress the line, or the markers, for individual data sets in a graph. This allows you combine points-only, lines-only, and line/points plots. Refer to SetLineStyles and SetPointShapes for details.

For error plots only: Error bar colors for each line are set with SetErrorBarColors. Error bar shape (tee or line) is set with SetErrorBarShape. If tee-shaped error bars are used, the width of the upper and lower 'tee' is set with SetErrorBarSize. Error bar line width is set with SetErrorBarLineWidth.

Example of this plot type can be seen in Section 5.7, “Example - Line/Point Plot, Point Shapes” and Section 5.48, “Example - Horizontal Linepoints Plot with Data Value Labels and Lines”.

3.4.8. Plot Type: lines (Lines Plot)

This plot type simply draws a line from each point to the next.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2... It also works with data-data-error for error plots. These produce the usual vertical plots.

This plot type also works with data types text-data-yx and data-data-yx to produce horizontal plots, and with data type data-data-yx-error to produce horizontal error plots. For 'text-data-yx', the data Y values are assumed to be at 0.5+N for N=0,1,2... (Horizontal 'lines' plots were added in PHPlot-6.0.0. Horizontal 'lines' error plots were added in PHPlot-6.1.0.)

An empty string (or any non-numeric value) for the dependent variable (Y for vertical plots, X for horizontal plots) indicates a missing point. PHPlot can either skip the line segments around missing points, or connect the adjacent points. See SetDrawBrokenLines for details.

Line colors for each line are set with SetDataColors. Line widths for each line are set with SetLineWidths. Line styles (solid or dashed) for each line are set with SetLineStyles.

For error plots only: Error bar colors for each line are set with SetErrorBarColors. Error bar shape (tee or line) is set with SetErrorBarShape. If tee-shaped error bars are used, the width of the upper and lower 'tee' is set with SetErrorBarSize. Error bar line width is set with SetErrorBarLineWidth.

Examples of this plot type can be seen in Section 5.1, “Example - Line Plot” and Section 5.2, “Example - Line Plot: Functions”.

3.4.9. Plot Type: ohlc (Basic OHLC Plot)

This plot type represents the changing price of a financial instrument (such as a stock or other security) over time. At each time point, 4 values are plotted: the opening price, the highest price, the lowest price, and the closing price. The ohlc plot type is one of three Open/High/Low/Close (OHLC) plot types available. It shows a vertical line connecting the low and high prices, with small horizontal tick marks showing the opening and closing prices. The opening price tick mark is on the left of the vertical line, and the closing price tick mark is on the right.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

This plot type requires exactly 4 Y values for each X. These represent the Open, High, Low, and Close prices in that order. Multiple data sets are not supported. A missing point is indicated by using four empty strings (or any non-numeric value) for the 4 Y values. (Missing points were not allowed for this plot type in PHPlot-5.4.0 and earlier.)

This plot type uses 4 colors from the data colors array. If the security closed lower than it opened for that time period, then color 0 is used for the vertical line, and color 2 is used for the open and close tick marks. If the security closed higher or the same as it opened for that time period, then color 1 is used for the vertical line, and color 3 is used for the open and close tick marks.

SetLineWidths can be used to set line widths. Index 0 will be used to draw the vertical lines, and index 1 will be used to draw the tick marks.

See also Section 4.7.4, “Tuning OHLC Charts”.

An example of this plot type can be seen in Section 5.30, “Example - Basic OHLC (Open, High, Low, Close) Financial Plot”.

This plot type was added in PHPlot-5.3.0.

3.4.10. Plot Type: pie (Pie Plot)

This plot type draws pie charts. The pie chart can have a 3-D look or be drawn flat. By default, the first pie segment starts at 0 degrees (East, or 3:00 on an analog clock face) and segments go around the pie in a counter-clockwise direction. (The start point and direction can be changed with SetPieStartAngle and SetPieDirection.) Each segment can be labeled. By default, the labels show the percentage of each segment.

This plot type works with data types text-data, data-data, and text-data-single. Data arrays for pie charts are handled differently from with other plot types, so the data types are described in more detail below.

If shading is on with SetShading (default is on with value 5 pixels), then the pie chart has a 3-D look. If shading is off (SetShading(0)), the pie chart is drawn flat (circular rather than oval). The position of the segment labels is set with SetLabelScalePosition. The content and formatting of the segment labels is controlled with SetPieLabelType.

Missing values (an empty string or any non-numeric value) are taken as zero. Any segment with arc angle less than 1 degree will not be drawn. (This is due to the PHP GD implementation of imagefilledarc, which uses integer degrees.)

See also Section 4.7.5, “Tuning Pie Charts”.

Examples of this plot type can be seen in Section 5.8, “Example - Pie Chart, text-data-single” (text-data-single), Section 5.9, “Example - Pie Chart, text-data” (text-data), and Section 5.10, “Example - Pie Chart, flat with options” (unshaded).

3.4.10.1. Pie Chart with data type: 'text-data-single'

The data array for pie charts with 'text-data-single' data type is structured as follows. Each record in the data array represents a pie segment. The record is an array of 2 elements: label and value. By default, the labels from the data array are ignored, but these can be used to label the pie segments with SetPieLabelType. The values in the data array set the size of each pie segment. PHPlot totals up the values and computes the relative size of each segment.

For example:

$data = array(array('', 1), array('',4), array('',5));

This makes a pie chart with 3 segments, with sizes 10%, 40%, and 50%.

The data array labels can also be used to build a plot legend. For example, this will produce a pie chart with 3 segments, and a legend with 3 entries using the labels from the data array:

$data = array(array('Gold', 100), array('Silver',35), array('Copper',12));
$plot = new PHPlot();
$plot->SetPlotType('pie');
$plot->SetDataType('text-data-single');
$plot->SetDataValues($data);
foreach ($data as $row) $plot->SetLegend($row[0]); // Copy labels to legend
$plot->DrawGraph();

A slightly more complex example of this can be seen in Section 5.8, “Example - Pie Chart, text-data-single”. This only works for the 'text-data-single' data type, where each row or record in the data array is used to build one pie segment.

3.4.10.2. Pie Chart with data type: 'text-data'

The data array for pie charts with 'text-data' data type is structured as follows. Each record in the data array is an array of a label followed by N data values. The label is ignored. The pie chart will be produced with N segments. The relative weight of the first segment is the sum of the first data values in each record. The relative weight of each subsequent segment is the sum of the corresponding data values in each record.

For example:

$data = array(array('', 10, 10, 20, 10),
              array('', 15, 10, 15, 10));

This results in 4 segments with sizes 25%, 20%, 35%, and 20%.

3.4.10.3. Pie Chart with data type: 'data-data'

The data array for pie charts with 'data-data' data type is structured the same as 'text-data', except that the first two values in each record are ignored (the positions usually used for label and X value). Each element in the data array represents a record. Each record is an array of a label, X value, then N data values. The label and X value are ignored. The pie chart will be produced with N segments. The relative weight of the first segment is the sum of the first data values in each record. The relative weight of each subsequent segment is the sum of the corresponding data values in each record.

For example:

$data = array(array('', 1, 10, 10, 20, 10),
              array('', 2, 15, 10, 15, 10));

This results in 4 segments with sizes 25%, 20%, 35%, and 20%. The empty strings and '1' and '2' are ignored.

3.4.11. Plot Type: points (Styled Dot Plot)

This plot type draws a point marker at each X,Y value.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2... It also works with data-data-error for error plots. These produce the usual vertical plots.

This plot type also works with data types text-data-yx and data-data-yx to produce horizontal plots, and with data type data-data-yx-error to produce horizontal error plots. For 'text-data-yx', the data Y values are assumed to be at 0.5+N for N=0,1,2... (Horizontal 'points' plots were added in PHPlot-6.0.0. Horizontal 'points' error plots were added in PHPlot-6.1.0.)

Marker colors for each line are set with SetDataColors. Marker styles for each line are set with SetPointShapes. Marker sizes for each line are set with SetPointSizes.

For error plots only: Error bar colors for each line are set with SetErrorBarColors. Error bar shape (tee or line) is set with SetErrorBarShape. If tee-shaped error bars are used, the width of the upper and lower 'tee' is set with SetErrorBarSize. Error bar line width is set with SetErrorBarLineWidth.

An empty string (or any non-numeric value) for the dependent variable (Y for vertical plots, X for horizontal plots) indicates a missing point. No point marker will be drawn at missing point positions.

Examples of this plot type can be seen in Section 5.12, “Example - Points Plot / Scatterplot”, Section 5.11, “Example - Points Plot with Error Bars”, and Section 5.49, “Example - Horizontal Error Plot”.

3.4.12. Plot Type: squared (Squared Plot)

This plot type makes stepped lines. For each point, you get a horizontal line from the previous point to the current X, then a vertical line to the current Y.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

An empty string (or any non-numeric value) for a Y value indicates a missing point. PHPlot can either skip the line segments around missing points, or connect the adjacent points. See SetDrawBrokenLines for details.

Line colors per line are set with SetDataColors. Line widths per line are set with SetLineWidths. Line style (solid or dashed) per line are set with SetLineStyles.

An example of this plot type can be seen in Section 5.13, “Example - Squared Plot”.

3.4.13. Plot Type: squaredarea (Squared Area Plot)

This plot type draws filled areas between squared (or stepped) lines. Each data set (set of corresponding Y values from each record in the data array) is plotted in order, with the area between the data set and the next data set filled solid. The edges of the filled area are stepped lines, as with the squared plot type, rather than straight line segments, as in the area plot type. The area between the last line and the X axis[2] is also filled. The data must be arranged so the values are (generally) decreasing within each row, because later drawn filled areas will cover previously drawn areas.

Because squared lines are drawn by stepping X first, then Y, the last Y value is usually not visible because there is no width for a filled area. One work-around is to append a copy of the last row of the data array. This is shown in the example linked below.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

A minimum of 2 rows (X values and corresponding Y value(s)) is required for this plot type. If there are fewer than 2 rows, an empty plot will be produced.

This plot type uses the absolute value of each supplied Y, because negative values do not make sense here. Missing values are taken as zero. All records in the data array must have the same number of Y values.

The areas are filled with colors as set with SetDataColors. If data borders are enabled with SetDrawDataBorders, then a border is drawn around each area fill, using the colors set with SetDataBorderColors. By default, no data borders are drawn.

An example of this plot type can be seen in Section 5.52, “Example - Squared Area Plot”.

The squaredarea plot type is similar to the stackedsquaredarea plot type. When plotting a single data set (1 Y value per X), the two plot types are identical.

This plot type was added in PHPlot-6.2.0.

3.4.14. Plot Type: stackedarea (Stacked Area Plot)

This plot type draws filled areas between lines, similar to area except the values are accumulated as in stackedbars plots. The area between the X axis and the first data set (the line resulting from the first Y value from each record) is filled first. Then the area above that line, up to the sum of the first and second Y values in each record, is filled next. This repeats until filling the area up to the top-most line, which is the sum of all the Y values from each record.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

A minimum of 2 rows (X values and corresponding Y value(s)) is required for this plot type. If there are fewer than 2 rows, an empty plot will be produced.

This plot type uses the absolute value of each supplied Y, because negative values do not make sense here. Missing values are taken as zero. All records in the data array must have the same number of Y values.

The areas are filled with colors as set with SetDataColors. Note that color selection with stackedarea plots tends to go in the reverse order compared to area plots. For stacked plots, the first area fill using the first color fills the area extending up from the X axis to the first data set. So the first color is always at the bottom of the plot. For unstacked plots, the last area fill using the last color fills the area extending up from the X axis to the last data set. Unless this data set contains the lowest Y values (and is drawn at the bottom of the plot), it will cover all the other data set area fills. So typically the unstacked plot has to have the last color at the bottom of the plot. Compare Section 5.3, “Example - Area Plot” and Section 5.21, “Example - Stacked Area Plot”.

If data borders are enabled with SetDrawDataBorders, then a border is drawn around each area fill, using the colors set with SetDataBorderColors. (Data borders for stackedarea plots were added in PHPlot-6.2.0.) By default, no data borders are drawn.

An example of this plot type can be seen in Section 5.21, “Example - Stacked Area Plot”.

This plot type was added in PHPlot-5.1.1.

A stackedarea plot is identical to an area plot when plotting a single data set (1 Y value per X),

3.4.15. Plot Type: stackedbars (Stacked Bar Plot)

This plot type draws a bar chart with stacked bars. Both vertical and horizontal stacked bar charts are available. The bars are centered on the X values (for vertical charts), or on the Y values (for horizontal charts). Each data set value contributes one segment of a stack. That is, the first data set is drawn from the axis in the first color, then the second data set is drawn stacked on the first using the second color, etc.

Data values greater than zero result in an upward (or rightward) bar. Data values less than zero result in a downward (or leftward) bar. Mixing negative and positive values within a row does work, but the results are not generally useful. The first non-zero value in any given row determines the direction of that bar stack. PHPlot keeps a running total for each row, but does not draw any segment unless it increases the bar stack height (or length, for horizontal plots). It also does not draw any segment on the wrong side of the axis (which is normally at 0).

Segments of length zero in a bar stack are usually ignored, but they might be visible if the axis is moved in the direction opposite to the bar stack direction. (For example, axis is at Y=2, stack contains segment values 0 and -4; the 0 segment is drawn down from the axis at Y=2 to Y=0, followed by the second segment down to -4).

For vertical bars, use data type text-data. The data X values are assumed to be at 0.5+N for N=0,1,2... For horizontal bars, use data type text-data-yx. The data Y values are assumed to be at 0.5+N for N=0,1,2... No other data type works with stacked bar plots.

If shading is on with SetShading (default is on with value 5 pixels), then the bars have a 3-D look. If shading is off (SetShading(0)), the bars are flat rectangles. The filled colors for each stacked segment are set with SetDataColors. Data borders are drawn by default when shading is off. Use SetDrawDataBorders to enable or disable the borders. If the borders are on, the border colors can be set with SetDataBorderColors.

Missing values (an empty string or any non-numeric value) are taken as zero, except that they do not result in a visible segment in the case of a moved axis described above.

See also Section 4.7.1, “Tuning Bar Charts”.

Examples of this plot type can be seen in Section 5.14, “Example - Stacked Bars, Shaded”, Section 5.15, “Example - Stacked Bars, Unshaded”, Section 5.20, “Example - Stacked Bars with Y Data Value Labels”, and Section 5.28, “Example - Horizontal Stacked Bar Chart”.

The stackedbars plot type is similar to the bars plot type. When plotting a single data set, the two plot types are identical.

Horizontal stackedbars plots were added in PHPlot-5.1.3. Support for negative values in stackedbars plots was added in PHPlot-5.2.0. Before PHPlot-5.4.0, zero values were completely ignored in stackedbars plots. From PHPlot-5.4.0 through PHPlot-5.6.0, a zero value at the end of a data row (or an all zero row) would result in a color 'cap' on the top of the bar stack, but this was changed in PHPlot-5.7.0.

3.4.16. Plot Type: stackedsquaredarea (Stacked Squared Area Plot)

This plot type draws filled areas between squared (or stepped) lines, similar to squaredarea except the values are accumulated as in stackedbars plots. The area between the X axis and the first data set (the squared line resulting from the first Y value from each record) is filled first. Then the area above that up to the sum of the first and second Y values in each record is filled next. This repeats until filling the area up to the top-most squared line, which is the sum of all the Y values from each record. The edges of the filled areas are squared lines, as with the squared plot type.

Because squared lines are drawn by stepping X first, then Y, the last Y value is usually not visible because there is no width for a filled area. One work-around is to append a copy of the last row of the data array. This is shown in the example linked below.

This plot type works with data types text-data and data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2...

A minimum of 2 rows (X values and corresponding Y value(s)) is required for this plot type. If there are fewer than 2 rows, an empty plot will be produced.

This plot type uses the absolute value of each supplied Y, because negative values do not make sense here. Missing values are taken as zero. All records in the data array must have the same number of Y values.

The areas are filled with colors as set with SetDataColors. If data borders are enabled with SetDrawDataBorders, then a border is drawn around each area fill, using the colors set with SetDataBorderColors. By default, no data borders are drawn.

Note that color selection with stackedsquaredarea plots tends to go in the reverse order compared to squaredarea plots. For stacked plots, the first area fill using the first color fills the area extending up from the X axis to the first data set. So the first color is always at the bottom of the plot. For unstacked plots, the last area fill using the last color fills the area extending up from the X axis to the last data set. Unless this data set contains the lowest Y values (and is drawn at the bottom of the plot), it will cover all the other data set area fills. So typically the unstacked plot has to have the last color at the bottom of the plot. Compare Section 5.52, “Example - Squared Area Plot” and Section 5.53, “Example - Stacked Squared Area Plot”.

An example of this plot type can be seen in Section 5.53, “Example - Stacked Squared Area Plot”.

A stackedsquaredarea plot is identical to a squaredarea plot when plotting a single data set (1 Y value per X).

This plot type was added in PHPlot-6.2.0.

3.4.17. Plot Type: thinbarline (Thin Bar Line Plot)

This plot type draws lines from the axis to the data value. Other implementations call this type of plot impulses. Both vertical and horizontal thinbarline plots are available. Plotting multiple data sets does not work, because the lines are drawn on top of each other and only one can typically be seen. This plot type can be more readable than a bar chart when there are a large number of data points.

For vertical plots, use data type text-data or data-data. For 'text-data', the data X values are assumed to be at 0.5+N for N=0,1,2... For horizontal plots, use data type text-data-yx or data-data-yx. For 'text-data-yx', the data Y values are assumed to be at 0.5+N for N=0,1,2...

The width of the plot lines can be controlled with SetLineWidths.

An empty string (or any non-numeric value) for the dependent variable (Y for vertical plots, X for horizontal plots) indicates a missing point. No line will be drawn at missing point positions.

Examples of this plot type can be seen in Section 5.16, “Example - Thin Bar Line Plot”, Section 5.17, “Example - Thin Bar Line Plot, Wider Lines”, and Section 5.29, “Example - Horizontal Thin Bar Line Plot”.

3.4.18. Plot Types and Data Types

The following table indicates which plot types support which data types. Refer to Section 3.3, “PHPlot Data Types” for more information on data types.

Plot Type:Data Type:
text-datadata-datadata-data-errortext-data-singletext-data-yxdata-data-yxdata-data-yx-errordata-data-xyz
areaYesYes
barsYes Yes
boxesYesYes
bubbles Yes
candlesticksYesYes
candlesticks2YesYes
linepointsYesYesYes YesYesYes
linesYesYesYes YesYesYes
pieYesYes Yes
ohlcYesYes
pointsYesYesYes YesYesYes
squaredYesYes
squaredareaYesYes
stackedareaYesYes
stackedbarsYes Yes
stackedsquaredareaYesYes
thinbarlineYesYes YesYes



[2] The area and squaredarea plot types are actually intended to fill the area between each data set (set of Y values) and the X axis. The way it is described above is how it is actually implemented, however. When using opaque colors, there is no visible difference between the two methods. But when colors are partially transparent, filling the area between data sets (rather than data set to axis) avoids some unwanted color artifacts as the overlapping colors are blended.

SourceForge.net Logo

This version of the manual was produced for the PHPlot Sourceforge project web service site, which requires the logo on each page.

To download a logo-free copy of the manual, see the PHPlot project downloads area.