Reference modified by Dirk Krause

Dirk Krause — Thu, 29 Jun 2023 18:57:13 -0000

--- v3
+++ v4
@@ -18,7 +18,7 @@

 ###    Syntax

-~~~
+~~~octave
 pgfplot(filename, unit, imagesize, ...);
 ~~~

@@ -147,7 +147,7 @@

 ###    Syntax

-~~~
+~~~octave
 cal = pgfplot_varargs(key, value, ...);
 ~~~

@@ -165,7 +165,7 @@

 ###    Syntax

-~~~
+~~~octave
 pp = pgfplot_cs(matrix [ , type, derived ] );
 pp = pgfplot_cs(x, y [ , type, derived ] );
 ~~~
@@ -202,7 +202,7 @@

 ###    Syntax

-~~~
+~~~octave
 [newx, info] = pgfplot_merge(x1, x2);
 ~~~

Reference modified by Dirk Krause

Dirk Krause — Wed, 28 Jun 2023 19:27:35 -0000

--- v1
+++ v2
@@ -0,0 +1,345 @@
+
+
+
+
+
+
+
+
+
+
+   Home       Installation       Tutorial       Reference       Change log   
+
+[TOC]
+
+#   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...10³. 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|
Number of tics values to omit to free space for printing the unit. Optional, ignored if no unit defined.
+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 _f__x(_t_) and _f__y(_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|left,dy/dt|left,dx/dt|right,dy/dt|right).
Piecewise polynomial structure for "pp".
Required for types "pp", "points", "points-parametric", and "x-spline".
+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|left,dy/dt|left,dx/dt|right,dy/dt|right).
Piecewise polynomial structure for "pp".
Required for types "pp", "points", "points-parametric", and "x-spline".
+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.

octpgfpl-theory-de.pdf	German version
octpgfpl-theory-en.pdf	English version

Recent changes to Reference

Reference modified by Dirk Krause

Reference modified by Dirk Krause

Reference modified by Dirk Krause

Reference modified by Dirk Krause