octpgfpl - 2D diagrams for LaTeX Wiki
Create 2D diagrams for use with LaTeX from GNU Octave
Brought to you by:
kraused
Menu
▾
▴
Reference
Attachments
octpgfpl-theory-de.pdf
(125164 bytes)
octpgfpl-theory-en.pdf
(120581 bytes)
| Home | Installation | Tutorial | Reference | Change log |
Functions
pgfplot
Syntax
pgfplot(filename, unit, imagesize, ...);
Required and optional arguments
For the required arguments use the values directly.
An even-numbered list of further arguments may follow the list of required arguments. These optional arguments are grouped as key/value pairs, the keys are texts.
| Status | Argument/Key | Purpose |
|---|---|---|
| Required | filename | Path name. Output file to produce. See the table below for accepted file name suffixes. |
| unit | String. Unit used for all dimensions, one from: "bp", "cm", "mm", or "in" ("inch" and "inches" are equivalent). |
|
| imagesize | Vector of two numeric values. Image width and height in the unit specified above. |
|
| Optional | axis.x | Cell array list containing the configuration for the primary x axis on the bottom side. Recommended. See the table "Axis configuration cell array list" below for axis configuration. |
| axis.y | Cell array list containing the configuration for the primary y axis on the left side. Recommended | |
| axis.x2 | Cell array list containing the configuration for the secondary x axis on the top side. Optional. | |
| axis.y2 | Cell array list containing the configuration for the secondary y axis on the right side. Optional. | |
| lw.pt lw.bp lw.mm lw.cm lw.in |
Numerical value Base line width in either pt, bp, mm, cm or in. The keys are mutually exclusive. Recommended to use once. |
|
| box.color | Text The box color as LaTeX color definition. Optional, default is "black". |
|
| grid.color | Text The grid line color as LaTeX color definition. Optional, default is "black". |
|
| tics.color | Text The tics color as LaTeX color definition. Optional, default is "black". |
|
| tics.size | Number Size of tics markers as multiple of the line width. Optional, default is 3. |
|
| decimal.separator | String Marker for decimal separator, dot or comma. Optional, default depends on unit ("." for in, "," for cm). |
|
| plot | Cell array list. Configuration of one item to plot. See the table "Plot configuration cell array list" below. At least one required, multiple allowed. |
|
| latex | Cell array list Configuration for LaTeX. See the table "LaTeX configuration cell array list" below. Optional. |
File name suffixes in pgfplot
| File name suffix in pgfplot | Files produced |
|---|---|
| .tex | A standalone *.tex file is produced, you can run pdfLaTeX on it. Graphics is implemented using instructions from the pgfcore package. |
| .pdftexs | PDF+TeX standalone. A combination of a *.tex and a *-i.pdf file is produced, you can run pdfLaTeX on the *.tex file file. The *.tex file uses "\includegraphics{}" to include the *-i.pdf file containing all non-text graphics and typesets the text labels on top of it (same mechanism as pdftex/pdftex_t output from fig2dev). Note: The plpdftex program from DK tools is required, version 4.14.4 or above is recommended. |
| .pgf | A *.pgf file is produced, you can use "\input{...}" to include the image into a LaTeX document. Graphics is implemented using instructions from the pgfcore package. |
| .pdftex | PDF+TeX A combination of a *.tex and a *.pdf file is produced. You can use "\input{...}" to include the image into a LaTeX document. The *.tex file uses "\includegraphics{}" to include the *.pdf file containing all non-text graphics and typesets the text labels on top. The plpdftex program is required. |
| .epstex | EPS+TeX A combination of a *.tex and a *.eps file is produced. You can use "\input{...}" to include the image into a LaTeX document. The *.tex file uses "\includegraphics{}" to include the *.eps file containing all non-text graphics and typesets the text labels on top of it. The plpdftex program is required. |
Axis configuration cell array list
The cell array list to configure an axis consists of key/value pairs.
Keys are texts, the following keys are allowed:
| Key | Purpose |
|---|---|
| lin log |
Vector Left/bottom and right/top value, for linear or logarithmic axis configuration. For a logarithmic scale the vector contains the integer exponentes of powers of ten, i.e. "[-3 3]" for a logarithmic axis in the range 10-3...103. Required, "lin" and "log" are mutually exclusive. |
| grid | Number Number of grid intervals. Optional, default 0 indicates no grid. A grid is drawn for the primary x and y axis only. |
| tics | Number Number of tics intervals. Optional, default 0 indicates no tics. |
| label | Text X axis label, optional. |
| unit.text | Text Unit on axis, optional. |
| unit.omit | Number |
| tics.distance | Number Distance between drawing area and tics texts. Optional, default 1bp. |
| label.distance | Number Distance between drawing area and label center. Optional, default 2bp. |
| border.distance | Number Distance between drawing area and image border. Optional, default 3bp. |
Plot configuration cell array list
The cell array list to configure a plot consists of key/value pairs.
Keys in bold are used to set the plot type, exactly one of them must be used before any other key. Keys are texts, the following keys are allowed:
| Key | Value and purpose |
|---|---|
| function | Function handle or cell array list containing two function handles Configures an y=f(x) plot. The cell array list contains a handle of the function to plot and a handle of the derivative function. Both functions must be vectorized. |
| parametric | Cell array list containing two or four function handles. Configures a parametric plot. For two handles we have vectorized functions to calculate fx(t) and fy(t). For four handles we also have dx/dt and dy/dt functions. |
| pp | Piecewise polynomial structure Draw the piecewise polynomial. |
| points | 2 or 3 column matrix Configures a points plot. The matrix contains one point per line. Each line contains x and y, optionally a dy/dx value. X values must be monothonically. If derivative values are known/required for some points only, use NA in the third column of remainig points. |
| points‑parametric | 2 or 4 column matrix Parametric points plot, the matrix contains one point per line. For each point we have to specify x and y, optionally we can specify dx/dϑ and dy/dϑ. When specifying derivative values for some points only, use NA for the remaining points. For each point either specify both derivative values or none of them. |
| x‑spline.open.approximated x‑spline.closed.approximated x‑spline.open.interpolated x‑spline.closed.interpolated |
2 or 3 column matrix X-spline plot, each matrix line contains one points x and y coordinate, optionally an s value. When specifying s values for some points only, use NA for the remaining points. You can abbreviate x-spline.open.approximated to x-spline.open or just x-spline. You can abbreviate x-spline.closed.approximated to x-spline.closed. For closed X-splines do not repeat the first point as last point. |
| range | 2 elements vector Start and end of plot range for function plots or parametric plots. Optional for function plots, required for parametric plots. |
| intervals | Number Number of intervals for plotting, default: 10 |
| x‑spline.intervals | Number Number of Bezier segments to draw for each X-spline segment. Optional, default: 4. |
| at | Vector Positions (x values for function, t values for parametric) which should be merged into the arguments vector created for the intervals. Optional. |
| breakpoints | Vector Positions (x values for function, t values for parametric) with discontinuities in the derivative (break points, corner points). For function and parametric the positions are specified directly. For points and points-parametric the value is a boolean vector containing a value for each data point, true for break points. Optional. |
| axis | Text or cell array of texts Axes to use: "x1", "x2", "y1", "y2". Optional, default is "x1" and "y1". |
| style | Text Plot style, one from "curve", "polyline", or "markers". Optional, default "curve". Ignored for pp and x-spline, which are always drawn as curves. |
| lw | Number Line width for the plot in multiples of the base line width. Optional, default 1. |
| color | Text LaTeX color definition. Optional, default "black". |
| marker.type | Text marker type, one from "+" (cross), "x" (diagonal cross), "*" (asterisk), "c" (circle), "s" (square), or "d" (diamond, rotated square). Optional, default "*". |
| spline‑type | Text Spline type to draw curves. Optional, default "not-a-knot". One from "not-a-knot", "variational", "periodic", "fast", "fast‑periodic". See the table "Spline types" below. |
| label | Cell array list Description one label to plot. Optional, allowed multiple times. See the table "Label configuration cell array" below. |
| polyline | Cell array list description for one polyline to insert. Optional, allowed multiple times. See the table below. |
As the keywords "function", "parametric", "points", "points‑parametric", "x‑spline.open.approximated", "x‑spline.closed.approximated", "x‑spline.open.interpolated", and "x‑spline.closed.interpolated" configure the plot type, they are mutually exclusive. The plot type entry must be the first in the list.
Spline types
| Name | Description |
|---|---|
| not‑a‑knot | Third derivative contiguous in second and penultimate point, default. |
| variational | Natural spline, second derivative is 0 in first and final point. Used for smooth curves. |
| periodic | Periodic spline. Value, first and second derivative are equal at end of last interval and start of first interval. |
| fast | Fast spline avoiding to solve a linear system of equations. For each triple of points we find a quadratic polynomial, from this polynomial we get the derivative in the center point. For the first and last point we get the derivative from the start/end of the first/last polynomial. |
| fast‑periodic | Combination of fast and periodic. |
Label configuration cell array
The cell array list to configure a label consists of key/value pairs. Keys are texts, the following keys are allowed:
| Name | Value and purpose |
|---|---|
| text | Text Text for the label. Required. |
| position | Vector Coordinates (x and y) for the label. Required. |
| box | Boolean Draw box around label. Optional, default: no. |
| valign | Text Vertical align, one from "centered" (default), "base", "bottom" or "top". Optional. |
| halign | Text Horizontal align, one from "centered" (default), "left", "right". Optional. |
| color | Text LaTeX colour definition for the label. |
Polyline configuration cell array list
| Name | Value and purpose |
|---|---|
| points | 2 column matrix Polyline points, one per line. Required. |
| color | Text LaTeX colour definition. Optional, default: black. |
| lw | Number Line width in multiples of the base line width. Optional, default: the plot line width. |
LaTeX configuration cell array list
| Name | Value and purpose |
|---|---|
| font‑size | Number Document class font size. Optional. |
| font‑setup | 1 column matrix of strings "\usepackage" lines to set up fonts. Optional. |
| packages | 1 column matrix of strings "\usepackage" lines for further setup. Optional. |
| preamble | 1 column matrix of strings Further setup commands. Optional. |
pgfplot_varargs
Syntax
cal = pgfplot_varargs(key, value, ...);
Description
The pgfplot_varargs() function returns all arguments as a one-dimensional cell array list.
Some configuration keywords expect a one-dimensional cell array list, i.e. to configure an axis, a plot item, a text label or a polyline.
Without the pgfplot_varargs() function we would have to write the entire list — which is a list of key/value pairs — in one line or we would use an ellipsis at each line end.
The pgfplot_varargs() function allows to distribute the list elements over multiple lines visualizing the key/value relationship.
pgfplot_cs
Syntax
pp = pgfplot_cs(matrix [ , type, derived ] );
pp = pgfplot_cs(x, y [ , type, derived ] );
Description
The pgfplot_cs() function constructs a cubic spline for given points and returns a piecewise polynomial (pp) structure.
Arguments
The matrix argument contains point data, one point per line.
For each point we have x and y value (columns 1 and 2).
The third column — if present — contains values for the first derivative dy/dx at the points. If you don't specify values for all points, use NA for the points where dy/dx is not known.
Instead of specifying dy/dx in the third column,
you can specify dy/dx in the derived argument.
This column vector must have the same length as the number of rows in the matrix.
The column vectors x and y can be used instead of the matrix to specify coordinates. The vectors must have equal lengths.
The type argument specifies the spline type.
| Name | Details |
|---|---|
| not-a-knot not_a_knot |
The default spline type. The third derivative is contiguous in the second and penultimate point. |
| variational natural |
Natural spline. The second derivative is 0 in the first and last point. |
| periodic | The first and second derivative of the last interval in the last point are equal to the first interval in the first point. |
| fast | The spline is constructed without solving a linear system of equations. Quadratic polynomials are calculated for each triplet of contiguous points. For the middle point the first derivative of the polynomial is used as the first derivative of the spline. The first and last polynomial is used for the first and last point. The time required for the calculation increases only linearly with the number of points. |
| fast‑periodic | Combination of fast and periodic. |
pgfplot_merge
Syntax
[newx, info] = pgfplot_merge(x1, x2);
Description
The pgfplot_merge() function merges two vectors. The arguments x1 and x2 are increasing vectors. The resulting column vector newx contains each element from x1 and x2 once (a number contained in both x1 and x2 appears only once in newx).
The info result is a vector of same size as newx containing boolean values corresponding to the values in newx. The value is true for newx elements obtained from the x2 vector, false for other values.
Data structures
Plot configuration
| Component name | Contents |
|---|---|
| type | Text, plot item type. Required. One from: "function", "parametric", "pp", "points", "points-parametric", "x-spline". |
| cl | Boolean flag: X-spline is closed. Required for type "x-spline". |
| yfct | Function handle to calculate y=f(x) for "function" or y=f(t) for "parametric". Required for types "function" and "parametric". |
| yder | Function handle to calculate dy/dx for "function" or dy/dt for "parametric". Optional. For "parametric", yder and xder are used only if both function handles are available. |
| xfct | Function handle to calculate x=f(t) for "parametric". Required for type "parametric". |
| xder | Function handle to calculate dx/dt for "parametric". Optional. |
| pdata | 3 column matrix for "points", and "x-spline". 2, 4, or 6 column matrix for "points-parametric" (x,y or x,y,dx/dt,dy/dt, or x,y,dx/dt |
| range | 2 element numerical vector, start and end of plot range for function and parametric plots. Optional for function plots, entire x axis is used if omitted. Required for parametric plots. |
| intervals | Integer, number of intervals for plotting. Used by plot item types "function" and "parametric". Optional, default 20. |
| xsubs | Number of sub-splines (number of Bezier segments used for each X-spline segment). Required, default 4. |
| at | Vector containing x values for function plotting or t values for parametric plotting. Optional |
| breakpoints | For function and parametric plotting: Direct x or t values for discontinuities in the derivative. For points and points-parametric: Boolean vector, one element for each point. Optional |
| style | Plot style, "curve", "polyline" or "markers". Required, default is "curve". |
| color | Text, LaTeX color definition. Required, default is "black". |
| lw | For "curve" and "polyline": Line width as multiples of the grid line width. For "markers": Marker size in multiples of the grid line width. Required, default is 1. |
| spline_type | Spline type used for style=curve. Optional, default is "not-a-knot". |
| marker_type | Text describing marker type, one from "+", "x", "c", "s", or "d". Required, default is "*". |
| label_list | Cell array list containing label data. Optional |
| pl_list | Cell array list containing polyline data. Optional. |
| x2active | Boolean flag to use x2 axis instead of x axis. Required. |
| y2active | Boolean flag to use y2 axis instead of y axis. Required. |
Axis
| Component name | contents |
|---|---|
| s | Value at left or bottom axis border. Real value for linear axis, integer exponent (base 10) for logarithmic axis. Required. |
| e | Value at right or top axis border.Real value for linear axis, integer exponent (base 10) for logarithmic axis. Required. |
| is_log | Boolean flag to indicate a logarithmix axis. Required. |
| tics | Number of axis tics intervals, integer. Required. |
| grid | Number of grid intervals, integer. Required. 0 for no grid. |
| label | Text label for axis. Optional. |
| unit | Text label for axis unit. Optional. |
| omit | Number of tics to omit for unit, integer. Required, may be 0. |
| border | Space between image border and drawing area border in bp. Required. |
| d_label | Distance between drawing area border and label center in bp. Required. |
| d_tics | Distance between drawing area border and tics values in bp. Required. |
Plot item
| Component name | Contents |
|---|---|
| type | Text, plot item type. Required. One from: "function", "parametric", "pp", "points", "points-parametric", "x-spline". |
| cl | Boolean flag: X-spline is closed. Required for type "x-spline". |
| yfct | Function handle to calculate y=f(x) for "function" or y=f(t) for "parametric". Required for types "function" and "parametric". |
| yder | Function handle to calculate dy/dx for "function" or dy/dt for "parametric". Optional. For "parametric", yder and xder are used only if both function handles are available. |
| xfct | Function handle to calculate x=f(t) for "parametric". Required for type "parametric". |
| xder | Function handle to calculate dx/dt for "parametric". Optional. |
| pdata | 3 column matrix for "points", and "x-spline". 2, 4, or 6 column matrix for "points-parametric" (x,y or x,y,dx/dt,dy/dt, or x,y,dx/dt |
| range | 2 element numerical vector, start and end of plot range for function and parametric plots. Optional for function plots, entire x axis is used if omitted. Required for parametric plots. |
| intervals | Integer, number of intervals for plotting. Used by plot item types "function" and "parametric". Optional, default 20. |
| xsubs | Number of sub-splines (number of Bezier segments used for each X-spline segment). Required, default 4. |
| at | Vector containing x values for function plotting or t values for parametric plotting. Optional |
| breakpoints | For function and parametric plotting: Direct x or t values for discontinuities in the derivative. For points and points-parametric: Boolean vector, one element for each point. Optional |
| style | Plot style, "curve", "polyline" or "markers". Required, default is "curve". |
| color | Text, LaTeX color definition. Required, default is "black". |
| lw | For "curve" and "polyline": Line width as multiples of the grid line width. For "markers": Marker size in multiples of the grid line width. Required, default is 1. |
| spline_type | Spline type used for style=curve. Optional, default is "not-a-knot". |
| marker_type | Text describing marker type, one from "+", "x", "c", "s", or "d". Required, default is "*". |
| label_list | Cell array list containing label data. Optional |
| pl_list | Cell array list containing polyline data. Optional. |
| x2active | Boolean flag to use x2 axis instead of x axis. Required. |
| y2active | Boolean flag to use y2 axis instead of y axis. Required. |
Label
| Component name | Contents |
|---|---|
| text | Label text. Required. |
| x | X position. Required. |
| y | Y position. Required. |
| align | Text, alignment to use in \pgftext instruction. Optional. |
| color | Text, a LaTeX color definition. Optional. |
| box | Boolean flag, draw box around text. Required, default false. |
Polyline
| Component name | Contents |
|---|---|
| lw | Numerical value, line width in multiples of the grid line width. |
| points | 2 column matrix containing a line for each point. |
| color | Text, a LaTeX color definition. |
LaTeX
| Component name | Contents |
|---|---|
| ts | Integer number, font size used when setting document class. Optional. |
| fs | String matrix containing "\usepackage" lines for font setup. Optional. |
| os | String matrix containing "\usepackage" lines for further setup. Optional. |
| pr | String matrix containing additional preamble lines. Optional. |
Theory
Some theory is explained in the attached PDF files.
| octpgfpl-theory-de.pdf | German version |
| octpgfpl-theory-en.pdf | English version |
You should prefer the german version as my written English is probably not perfect.
