3.4. PHPlot Plot Types
Prev | Chapter 3. PHPlot Concepts | Next

## 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 Type | Description
--- | ---
area | Filled areas between lines. Also known as cumulative line plot or component line plot.
bars | Filled bars with optional 3-D look. Multiple datasets are offset.
candlesticks | An Open/High/Low/Close (OHLC) financial plot using filled and unfilled candlesticks.
candlesticks2 | An Open/High/Low/Close (OHLC) financial plot using filled candlesticks.
linepoints | Lines between points, with a marker at each point, and optional error bars.
lines | Straight lines between data points, with optional error bars.
ohlc | A basic Open/High/Low/Close (OHLC) financial plot using lines and ticks.
pie | Pie chart with or without 3-D affects.
points | Draws a marker at each data point, with optional error bars.
squared | Stepped lines
stackedarea | Filled areas between lines, with multiple data sets accumulated.
stackedbars | Filled bars with optional 3-D look. Multiple data sets are accumulated and the sum is graphed.
thinbarline | Vertical 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 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...

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.

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

### 3.4.2. Plot Type: bars (Bar Graph)

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, or be flat with a border. 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 with borders. The filled rectangle color is set with SetDataColors. The border color (if shading is off) can be set with SetDataBorderColors.

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

Horizontal bar plots were added in PHPlot-5.1.2.

### 3.4.3. 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. Missing Y values are not allowed.

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 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, and index 1 will be used to draw the wicks.

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.4. 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 and line width usage are the same.

Be sure to set the data colors 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.

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... As with candlesticks, this plot type requires exactly 4 Y values for each X: Open, High, Low, and Close prices.

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.5. Plot Type: linepoints (Lines and Points)

This plot type draws a line graph with a marker at each point, thus combining the 'line' and 'point' 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 bars.

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-bar plots with data type 'data-data-error' 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 example of this plot type can be seen in Section 5.7, “Example - Line/Point Plot, Point Shapes”.

### 3.4.6. Plot Type: lines (Lines Graph)

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

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-bar plots with data type 'data-data-error' 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.7. 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. Missing Y values are not allowed.

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.

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.8. Plot Type: pie (Pie Chart)

This plot type draws pie charts. The pie chart can have a 3-D look or be drawn flat. The first pie segment starts at 0 degrees (East, or 3:00PM) and they go around the pie in a counter-clockwise direction. Each segment is labeled with its percentage.

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 percentage labels is set with SetLabelScalePosition.

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.8.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, but the label is ignored. The value sets the relative size of a 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%.

#### 3.4.8.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.8.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.9. 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 bars.

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-bar plots with data type 'data-data-error' 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.12, “Example - Points Plot / Scatterplot”, and Section 5.11, “Example - Points Plot with Error Bars”.

### 3.4.10. Plot Type: squared (Step 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...

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

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 data sets are processed with stacked area plots in reverse order relative to area plots. With stacked area plots, the first data set (using the first data color) will be at the bottom, but with area plots it will be at the top. Compare Section 5.3, “Example - Area Plot” and Section 5.21, “Example - Stacked Area Plot”.

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.

### 3.4.12. Plot Type: stackedbars

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

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 with borders. The filled rectangle colors for each stacked segment are set with SetDataColors. The border color (if shading is off) can be set with SetDataBorderColors.

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

Horizontal stacked bar plots were added in PHPlot-5.1.3. Support for negative values in stacked bar plots was added in PHPlot-5.2.0.

### 3.4.13. Plot Type: thinbarline

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.

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.14. 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-data | data-data | data-data-error | text-data-single | text-data-yx | data-data-yx
area | Yes | Yes |  |  |  |
bars | Yes |  |  |  | Yes |
candlesticks | Yes | Yes |  |  |  |
candlesticks2 | Yes | Yes |  |  |  |
linepoints | Yes | Yes | Yes |  |  |
lines | Yes | Yes | Yes |  |  |
pie | Yes | Yes |  | Yes |  |
ohlc | Yes | Yes |  |  |  |
points | Yes | Yes | Yes |  |  |
squared | Yes | Yes |  |  |  |
stackedarea | Yes | Yes |  |  |  |
stackedbars | Yes |  |  |  | Yes |
thinbarline | Yes | Yes |  |  | Yes | Yes

Prev | Up | Next
3.3. PHPlot Data Types | Home | 3.5. Colors