summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex293
1 files changed, 270 insertions, 23 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
index 89b51dffbad..61e627f8304 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
@@ -51,13 +51,22 @@ sets of commands exist. The commands for creating streams start with
\subsection{Generating Plot Streams}
\subsubsection{Basic Building Blocks of Plot Streams}
-A \emph{plot stream} is a (long) sequence of the following three
+
+A \emph{plot stream} is a (long) sequence of the following
commands:
\begin{enumerate}
\item
|\pgfplotstreamstart|,
\item
- |\pgfplotstreampoint|, and
+ |\pgfplotstreampoint|,
+\item
+ |\pgfplotstreampointoutlier|,
+\item
+ |\pgfplotstreampointundefined|,
+\item
+ |\pgfplotstreamnewdataset|,
+\item
+ |\pgfplotstreamspecial|, and
\item
|\pgfplotstreamend|.
\end{enumerate}
@@ -75,11 +84,17 @@ end with the last command. Here is an example of a plot stream:
\pgfplotstreamend
\end{codeexample}
+Streams are \emph{global}, meaning that they are not influenced by
+\TeX\ groups.
+
\begin{command}{\pgfplotstreamstart}
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.
+ 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).
\end{command}
\begin{command}{\pgfplotstreampoint\marg{point}}
@@ -88,18 +103,110 @@ end with the last command. Here is an example of a plot stream:
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.
+\end{command}
+
+\begin{command}{\pgfplotstreampointoutlier\marg{point}}
+ An \emph{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 \textsc{gnuplot} when a value is
+ outside the specified range.
+
+ You can configure how outliers are treated using the following key:
+ \begin{key}{/pgf/handle outlier points in plots=\meta{how}
+ (initially jump)}
+ \keyalias{tikz}
+ You can set \meta{how} to one of the following values:
+ \begin{itemize}
+ \item |plot| This will cause the outlier to be drawn normally,
+ just as if |\pgfplotstreampoint| had been used rather than this
+ command.
+ \item |ignore| The outlier will be completely ignored, just as if
+ the command had not been used at all.
+ \item |jump| This causes the internal macro |\pgf@plotstreamjump|
+ to be called. A ``jump'' in a stream is a position where a
+ ``gap'' is introduced. For instance, a simple line-to plot
+ handler will stop the current subpath at a jump position and
+ begin with a move-to operation at the next normal point of the
+ stream.
+
+ The net effect of this setting is that at outlier points plots
+ get interrupted and ``restarted'' when the points are no longer
+ outliers. This is usually the behaviour you will be looking for.
+ \end{itemize}
+ \end{key}
+\end{command}
+
+\begin{command}{\pgfplotstreampointundefined}
+ 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 \emph{can} result in a jump in
+ the plot, depending on the setting of the following key:
+ \begin{key}{/pgf/handle undefined points in plots=\meta{how}
+ (initially jump)}
+ \keyalias{tikz}
+ You can set \meta{how} to one of the following values:
+ \begin{itemize}
+ \item |ignore| The undefined point will be completely ignored, just as if
+ the command had not been used at all.
+ \item |jump| This causes the internal macro |\pgf@plotstreamjump|
+ to be called.
+ \end{itemize}
+ \end{key}
+\end{command}
+
+\begin{command}{\pgfplotstreamnewdataset}
+ 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:
+ \begin{key}{/pgf/handle new data sets in plots=\meta{how}
+ (initially jump)}
+ \keyalias{tikz}
+ You can set \meta{how} to one of the following values:
+ \begin{itemize}
+ \item |ignore| The command will be completely ignored, just as if
+ the command had not been used at all.
+ \item |jump| This causes the internal macro |\pgf@plotstreamjump|
+ to be called.
+ \end{itemize}
+ \end{key}
+\end{command}
+
+\begin{command}{\pgfplotstreamspecial\marg{text}}
+ This command causes |\pgf@plotstreamspecial| to be called with
+ \meta{text} as its parameter. This allows handler-specific
+ information to be passed to the handler. All normal handlers ignore
+ this command.
\end{command}
\begin{command}{\pgfplotstreamend}
This command signals that a plot stream ends. It calls
- |\pgf@plotstreamend|, which should now do any necessary ``cleanup.''
+ |\pgf@plotstreamend|, which should now do any necessary ``cleanup.''
\end{command}
Note that plot streams are not buffered, that is, the different points
are handled immediately. However, using the recording handler, it is
possible to record a stream.
+
\subsubsection{Commands That Generate Plot Streams}
+\label{section-plot-jumps}
Plot streams can be created ``by hand'' as in the earlier
example. However, most of the time the coordinates will be produced
@@ -109,23 +216,44 @@ file and converts it into a plot stream.
\begin{command}{\pgfplotxyfile\marg{filename}}
This command will try to open the file \meta{filename}. If this
succeeds, it will convert the file contents into a plot stream as
- follows: A |\pgfplotstreamstart| is issued. Then, each nonempty line
- of the file should start with two numbers separated by a space, such
- as |0.1 1| or |100 -.3|. Anything following the numbers is ignored.
-
- Each pair \meta{x} and \meta{y} of numbers is converted into one
- plot stream point in the xy-coordinate system. Thus, a line like
-\begin{codeexample}[code only]
-2 -5 some text
+ follows: A |\pgfplotstreamstart| is issued. Then, for each nonempty
+ 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 \emph{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 \meta{x} and \meta{y} of numbers is
+ converted into one plot stream point in the xy-coordinate
+ system. Thus, a line like
+\begin{codeexample}[code only, tikz syntax=false]
+0 Nan u
+1 1 some text
+2 4
+3 9
+
+4 16 o
+5 25 oo
\end{codeexample}
is turned into
\begin{codeexample}[code only]
-\pgfplotstreampoint{\pgfpointxy{2}{-5}}
+\pgfplotstreamstart
+\pgfplotstreampointundefined
+\pgfplotstreampoint{\pgfpointxy{1}{1}}
+\pgfplotstreampoint{\pgfpointxy{2}{4}}
+\pgfplotstreampoint{\pgfpointxy{3}{9}}
+\pgfplotstreamnewdataset
+\pgfplotstreampointoutlier{\pgfpointxy{4}{16}}
+\pgfplotstreampoint{\pgfpointxy{5}{25}}
+\pgfplotstreamend
\end{codeexample}
+ (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 empty and, hence, ignored.
+ either of them is treated as empty.
When the file has been read completely, |\pgfplotstreamend| is
called.
@@ -136,24 +264,25 @@ file and converts it into a plot stream.
This command works like |\pgfplotxyfile|, only \emph{three} numbers
are expected on each non-empty line. They are converted into points
in the xyz-coordinate system. Consider, the following file:
-\begin{codeexample}[code only]
+\begin{codeexample}[code only, tikz syntax=false]
% Some comments
# more comments
2 -5 1 first entry
-2 -.2 2 second entry
+2 -.2 2 o
2 -5 2 third entry
\end{codeexample}
It is turned into the following stream:
\begin{codeexample}[code only]
\pgfplotstreamstart
+\pgfplotstreamnewdataset
+\pgfplotstreamnewdataset
\pgfplotstreampoint{\pgfpointxyz{2}{-5}{1}}
-\pgfplotstreampoint{\pgfpointxyz{2}{-.2}{2}}
+\pgfplotstreampointoutlier{\pgfpointxyz{2}{-.2}{2}}
\pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}}
\pgfplotstreamend
\end{codeexample}
\end{command}
-
Currently, there is no command that can decide automatically whether
the xy-coordinate system should be used or whether the xyz-system
should be used. However, it would not be terribly difficult to write a
@@ -202,7 +331,7 @@ intelligently.
Let us start with the situation where none of these files
exists. Then \pgfname\ will first generate the file
\meta{prefix}|.gnuplot|. In this file it writes
-\begin{codeexample}[code only]
+\begin{codeexample}[code only, tikz syntax=false]
set terminal table; set output "#1.table"; set format "%.5f"
\end{codeexample}
where |#1| is replaced by \meta{prefix}. Then, in a second line, it
@@ -239,11 +368,23 @@ set terminal table; set output "#1.table"; set format "%.5f"
read.
As explained in Section~\ref{section-tikz-gnuplot}, the net effect
- of the above mechanism is that |gnuplot| is called as little as
+ 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.
+
+ \begin{key}{/pgf/plot/gnuplot call=\meta{gnuplot invocation} (initially gnuplot)}
+ This key can be used to change the way gnuplot is called.
+
+ Some portable Mik\TeX{} distribution needs something like the
+ following.
+
+\begin{codeexample}[code only]
+ \pgfkeys{/pgf/plot/gnuplot call="/Programs/gnuplot/binary/gnuplot"}
+\end{codeexample}
+
+ \end{key}
\end{command}
@@ -252,13 +393,13 @@ set terminal table; set output "#1.table"; set format "%.5f"
\label{section-plot-handlers}
-A \emph{plot handler} prescribes what ``should be done'' with a
+A \emph{plot handler} determines what ``should be done'' with a
plot stream. You must set the plot handler before the stream starts.
The following commands install the most basic plot handlers; more plot
handlers are defined in the file |pgflibraryplothandlers|, which is
documented in Section~\ref{section-library-plothandlers}.
-All plot handlers work by setting redefining the following three
+All plot handlers work by setting or redefining the following three
macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and
|\pgf@plotstreamend|.
@@ -322,7 +463,7 @@ macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and
\begin{command}{\pgfplothandlerrecord\marg{macro}}
When this handler is installed, each time a plot stream command is
- called, this command will be appended to \meta{macros}. Thus, at
+ called, this command will be appended to \meta{macro}. Thus, at
the end of the stream, \meta{macro} will contain all the
commands that were issued on the stream. You can then install
another handler and invoke \meta{macro} to ``replay'' the stream
@@ -346,6 +487,112 @@ macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and
\end{codeexample}
\end{command}
+
+
+\subsection{Defining New Plot Handlers}
+
+You can define new plot handlers using the following command:
+
+\begin{command}{\pgfdeclareplothandler\marg{macro}\marg{arguments}\marg{configuration}}
+ This command creates a new plot handler that can subsequently be
+ called using the macro \meta{macro}. This macro take the arguments
+ given in \meta{arguments}, which can be a list like |#1#2| if
+ \meta{macro} should be invoked with two arguments. Here is a typical example:
+\begin{codeexample}[code only]
+\pgfdeclareplothandler{\myhandler}{#1}{...}
+...
+\myhandler{foo}
+\pgfplotstreamstart
+...
+\pgfplotstreamend
+\end{codeexample}
+
+ The \meta{configuration} is used to define the behaviour of the
+ handler. It is a list of key--value pairs, where the following keys
+ are allowed:
+ \begin{itemize}
+ \item |start=|\meta{code}. The \meta{code} will be executed whenever
+ |\pgfplotstreamstart| is used while the handler \meta{macro} is
+ selected. Inside the \meta{code}, you can use |#1|, |#2|, and so
+ on to refer to the parameters that were given to \meta{macro}:
+\begin{codeexample}[width=6cm]
+\pgfdeclareplothandler{\myhandler}{#1}{
+ start = Hi #1.,
+ end = Bye #1.,
+}
+\myhandler{foo}
+\pgfplotstreamstart
+\pgfplotstreamend
+\myhandler{bar}
+\pgfplotstreamstart
+\pgfplotstreamend
+\end{codeexample}
+ \item |end=|\meta{code} Works just like |start|.
+ \item |point=|\meta{code}. The \meta{code} will be executed whenever
+ |\pgfplotstreampoint| is used while the handler \meta{macro} is in
+ force. Inside the \meta{code}, you can use |#1|, |#2|, and so on
+ to refer to the arguments give to \meta{macro}, while you can use
+ |##1| to refer to the argument given to |\pgfplotstreampoint|
+ itself (this will be the coordinate).
+\begin{codeexample}[]
+\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}
+\end{codeexample}
+ The \meta{code} will also be called for
+ |\pgfplotstreampointoutlier| when this command has been configured
+ to |plot| the outliers.
+ \item |jump=|\meta{code} The \meta{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
+ \meta{code} you can access |#1| and so on.
+ \item |special=|\meta{code} Causes \meta{code} to be executed
+ whenever |\pgfplotstreamspecial|\marg{something} is used. Inside
+ the \meta{code}, you can access \meta{something} via |##1| and the
+ parameters of \meta{macro} as |#1|, |#2|, and so on.
+ \end{itemize}
+
+ In addition to the above keys, there exist also ``code macro
+ versions'' of them:
+ \begin{itemize}
+ \item |point macro=|\meta{some macro}. Causes |\pgfplotstreampoint|
+ to call \meta{some macro} directly (actually,
+ |\pgf@plotstreampoint| is set to be equal to \meta{some
+ macro}). Inside the \meta{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
+ \meta{macro} that installed the handler. So, \meta{some macro}
+ must take exactly one argument, namely |#1|.
+ \item |special macro=|\meta{some macro}. As |point macro|, only for
+ specials.
+ \item |start macro=|\meta{some macro}. Causes \meta{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 \meta{macro}.
+ \item |end macro=|\meta{some macro}. As above.
+ \item |jump macro=|\meta{some macro}. As above.
+ \end{itemize}
+\end{command}
+
+
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"