The TikZ and PGF Packages
Manual for version 3.1.10

This module provides a set of commands that are intended to make it reasonably easy to plot functions using pgf. It is loaded automatically by pgf, but you can load it manually if you have only included pgfcore.

This command signals that a plot stream starts. The effect of this command is to call the internal command \pgf@plotstreamstart, which is set by the current plot handler to do whatever needs to be done at the beginning of the plot. It will also reset the meaning of the internal commands like \pgf@plotstreampoint to the initial setting for the plot handler (what this means will be explained in a moment).

This command adds a ⟨point⟩ to the current plot stream. The effect of this command is to call the internal command \pgf@plotstreampoint, which is also set by the current plot handler. This command should now “handle” the point in some sensible way. For example, a line-to command might be issued for the point.

When a plot handler is installed, it will setup the internal command \pgf@plotstreampoint in some way. It is permissible to change the meaning of this internal command during a stream. For instance, a handler might setup \pgf@plotstreampoint in some sensible way for the first point and then redefine it so that subsequent points are handled in some other way.

As mentioned earlier, the \pgfplotstreamstart will always reset the definition of the internal command to the initial meaning it had when the handler was installed. This is true for the other commands mentioned in the following.

An outlier is a point that is “out of bounds” in some way. For instance, it might have very large coordinates or the coordinates might just be outside some specified range. Nevertheless, an outlier is still a well-defined point. This command is issued, for instance, by gnuplot when a value is outside the specified range.

You can configure how outliers are treated using the following key:

This command indicated that the stream contains an “undefined” point like a point where some coordinate results for a division by zero. Such a point cannot be plotted, which is why it is not given as a parameter. However, such a point can result in a jump in the plot, depending on the setting of the following key:

This command indicated that in the stream a “new data set” starts. So, the stream does not end, but there is a logical break in the data. For example, when a table is read from a file, empty lines are interpreted as indicating new data sets. What happens when a new data set is encountered is governed by the following key:

This command causes \pgf@plotstreamspecial to be called with ⟨text⟩ as its parameter. This allows handler-specific information to be passed to the handler. All normal handlers ignore this command.

This command signals that a plot stream ends. It calls \pgf@plotstreamend, which should now do any necessary “cleanup”.

This command will try to open the file ⟨filename⟩. If this succeeds, it will convert the file contents into a plot stream as follows: A \pgfplotstreamstart is issued. Then, for each empty line a \pgfplotstreamnewdataset is produced. Other lines in the file should start with two numbers separated by a space, such as 0.1 1 or 100 -.3. The numbers may be followed by some text, which will be ignore except if it is exactly “u” or “o”. For “u” the point is considered to be undefined and \pgfplotstreampointundefined is called. For “o” the point is considered to be an outlier and \pgfplotstreampointoutlier is called. Otherwise, each pair ⟨x⟩ and ⟨y⟩ of numbers is converted into one plot stream point in the \(xy\)-coordinate system. Thus, a line like

is turned into

(Note that the last line is not an outlier because oo is not the same as o).

The two characters % and # are also allowed in a file and they are both treated as comment characters. Thus, a line starting with either of them is treated as empty.

When the file has been read completely, \pgfplotstreamend is called.

This command works like \pgfplotxyfile, only three numbers are expected on each non-empty line. They are converted into points in the \(xyz\)-coordinate system. Consider, the following file:

It is turned into the following stream:

This command will produce coordinates by iterating the ⟨variable⟩ over all values in ⟨sample list⟩, which should be a list in the \foreach syntax. For each value of ⟨variable⟩, the ⟨point⟩ is evaluated and the resulting coordinate is inserted into the plot stream.

Be warned that if the expressions that need to evaluated for each point are complex, then this command can be very slow.

This command will “try” to call the gnuplot program to generate the coordinates of the ⟨function⟩. In detail, the following happens:

This command works with two files: ⟨prefix⟩.gnuplot and ⟨prefix⟩.table. If the optional argument ⟨prefix⟩ is not given, it is set to \jobname.

Let us start with the situation where none of these files exists. Then pgf will first generate the file ⟨prefix⟩.gnuplot. In this file it writes

where #1 is replaced by ⟨prefix⟩. Then, in a second line, it writes the text ⟨function⟩.

Next, pgf will try to invoke the program gnuplot with the argument ⟨prefix⟩.gnuplot. This call may or may not succeed, depending on whether the \write18 mechanism (also known as shell escape) is switched on and whether the gnuplot program is available.

Assuming that the call succeeded, the next step is to invoke \pgfplotxyfile on the file ⟨prefix⟩.table; which is exactly the file that has just been created by gnuplot.

The more difficult situation arises when the .gnuplot file exists, which will be the case on the second run of TeX on the TeX file. In this case pgf will read this file and check whether it contains exactly what pgf “would have written” into this file. If this is not the case, the file contents is overwritten with what “should be there” and, as above, gnuplot is invoked to generate a new .table file. However, if the file contents is “as expected”, the external gnuplot program is not called. Instead, the ⟨prefix⟩.table file is immediately read.

As explained in Section 22.6, the net effect of the above mechanism is that gnuplot is called as seldom as possible and that when you pass along the .gnuplot and .table files with your .tex file to someone else, that person can TeX the .tex file without having gnuplot installed and without having the \write18 mechanism switched on.

This handler will issue a \pgfpathlineto command for each point of the plot, except possibly for the first. What happens with the first point can be specified using the two commands described below.

Specifies that the line-to plot handler (and also some other plot handlers) should issue a move-to command for the first point of the plot instead of a line-to. This will start a new part of the current path, which is not always, but often, desirable. This is the default.

Specifies that plot handlers should issue a line-to command for the first point of the plot.

This handler works like the line-to plot handler, only the line is closed at the end using \pgfpathclose, resulting in a polygon.

This handler will simply throw away the stream.

When this handler is installed, each time a plot stream command is called, this command will be appended to ⟨macro⟩. Thus, at the end of the stream, ⟨macro⟩ will contain all the commands that were issued on the stream. You can then install another handler and invoke ⟨macro⟩ to “replay” the stream (possibly many times).

This command creates a new plot handler that can subsequently be called using the macro ⟨macro⟩. This macro take the arguments given in ⟨arguments⟩, which can be a list like #1#2 if ⟨macro⟩ should be invoked with two arguments. Here is a typical example:

The ⟨configuration⟩ is used to define the behavior of the handler. It is a list of key–value pairs, where the following keys are allowed:

• • start=⟨code⟩. The ⟨code⟩ will be executed whenever \pgfplotstreamstart is used while the handler ⟨macro⟩ is selected. Inside the ⟨code⟩, you can use #1, #2, and so on to refer to the parameters that were given to ⟨macro⟩:

  Hi foo.Bye foo.Hi bar.Bye bar.

  copy
\pgfdeclareplothandler{\myhandler}{#1}{
start = Hi #1.,
end = Bye #1.,
}
\myhandler{foo}
\pgfplotstreamstart
\pgfplotstreamend
\myhandler{bar}
\pgfplotstreamstart
\pgfplotstreamend


• • end=⟨code⟩ Works just like start.

• • point=⟨code⟩. The ⟨code⟩ will be executed whenever \pgfplotstreampoint is used while the handler ⟨macro⟩ is in force. Inside the ⟨code⟩, you can use #1, #2, and so on to refer to the arguments give to ⟨macro⟩, while you can use ##1 to refer to the argument given to \pgfplotstreampoint itself (this will be the coordinate).

  

  copy
\pgfdeclareplothandler{\myhandler}{#1}{
point=\pgfpathcircle{##1}{#1} % ##1 is the coordinate,
% #1 the parameter for \myhandler
}
\begin{pgfpicture}
\myhandler{1pt}
\pgfplotstreamstart
\pgfplotstreampoint{\pgfpoint{0pt}{0pt}}
\pgfplotstreampoint{\pgfpoint{3pt}{3pt}}
\pgfplotstreampoint{\pgfpoint{6pt}{3pt}}
\pgfplotstreampoint{\pgfpoint{9pt}{0pt}}
\pgfplotstreamend
\pgfusepath{stroke}
\myhandler{3pt}
\pgfplotstreamstart
\pgfplotstreampoint{\pgfpoint{0pt}{0pt}}
\pgfplotstreampoint{\pgfpoint{9pt}{0pt}}
\pgfplotstreamend
\pgfusepath{stroke}
\end{pgfpicture}


  The ⟨code⟩ will also be called for \pgfplotstreampointoutlier when this command has been configured to plot the outliers.

• • jump=⟨code⟩ The ⟨code⟩ will be called whenever a jump has been requested indirectly via an outlier point, and undefined point, or a new data set (for each of which the command needs to be configured to jump). As always, inside the ⟨code⟩ you can access #1 and so on.

• • special=⟨code⟩ Causes ⟨code⟩ to be executed whenever \pgfplotstreamspecial{⟨something⟩} is used. Inside the ⟨code⟩, you can access ⟨something⟩ via ##1 and the parameters of ⟨macro⟩ as #1, #2, and so on.

In addition to the above keys, there exist also “code macro versions” of them:

• • point macro=⟨some macro⟩. Causes \pgfplotstreampoint to call ⟨some macro⟩ directly (actually, \pgf@plotstreampoint is set to be equal to ⟨some macro⟩). Inside the ⟨some macro⟩ you can use #1 to access the coordinate passed to \pgfplotstreampoint and you can no longer access the parameters passed to the original call to ⟨macro⟩ that installed the handler. So, ⟨some macro⟩ must take exactly one argument, namely #1.

• • special macro=⟨some macro⟩. As point macro, only for specials.

• • start macro=⟨some macro⟩. Causes ⟨some macro⟩ to be executed at the start. This macro, like the below ones, may not take any parameters and will not have access to the parameters passed to the original ⟨macro⟩.

• • end macro=⟨some macro⟩. As above.

• • jump macro=⟨some macro⟩. As above.