% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Plot Handler Library}
\label{section-library-plothandlers}

\begin{pgflibrary}{plothandlers}
  This library packages defines additional plot handlers, see
  Section~\ref{section-plot-handlers} for an introduction to plot
  handlers. The additional handlers are described in the following.

  This library is loaded automatically by \tikzname.
\end{pgflibrary}


\subsection{Curve Plot Handlers}
  
\begin{command}{\pgfplothandlercurveto}
  This handler will issue a |\pgfpathcurveto| command for each point of
  the plot, \emph{except} possibly for the first. As for the line-to
  handler, what happens with the first point can be specified using
  |\pgfsetmovetofirstplotpoint| or |\pgfsetlinetofirstplotpoint|.

  Obviously, the |\pgfpathcurveto| command needs, in addition to the
  points on the path, some control points. These are generated
  automatically using a somewhat ``dumb'' algorithm: Suppose you have
  three points $x$, $y$, and $z$ on the curve such that $y$ is between
  $x$ and $z$:
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlercurveto
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}

  In order to determine the control points of the curve at the point
  $y$, the handler computes the vector $z-x$ and scales it by the
  tension factor (see below). Let us call the resulting vector
  $s$. Then $y+s$ and $y-s$ will be the control points around $y$. The
  first control point at the beginning of the curve will be the
  beginning itself, once more; likewise the last control point is the
  end itself.
\end{command}

\begin{command}{\pgfsetplottension\marg{value}}
  Sets the factor used by the curve plot handlers to determine the
  distance of the control points from the points they control. The
  higher the curvature of the curve points, the higher this value
  should be. A value of $1$ will cause four points at quarter
  positions of a circle to be connected using a circle. The default is
  $0.5$. 

\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfsetplottension{0.75}
  \pgfplothandlercurveto
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}


\begin{command}{\pgfplothandlerclosedcurve}
  This handler works like the curve-to plot handler, only it will
  add a new part to the current path that is a closed curve through
  the plot points.
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerclosedcurve
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\subsection{Constant Plot Handlers}
There are three plot handlers which produce piecewise constant interpolations between successive points.

\begin{command}{\pgfplothandlerconstantlineto}
  This handler works like the line-to plot handler, only it will
  produce a connected, piecewise constant path to connect the points.
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerconstantlineto
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfplothandlerconstantlinetomarkright}
A variant of |\pgfplothandlerconstantlineto| which places its mark on
the right line ends.
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerconstantlinetomarkright
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfplothandlerjumpmarkleft}
  This handler works like the line-to plot handler, only it will
  produce a non-connected, piecewise constant path to connect the points. If there are any plot marks, they will be placed on the left open pieces.
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerjumpmarkleft
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfplothandlerjumpmarkright}
  This handler works like the line-to plot handler, only it will
  produce a non-connected, piecewise constant path to connect the points. If there are any plot marks, they will be placed on the right open pieces.
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerjumpmarkright
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\subsection{Comb Plot Handlers}

There are three ``comb'' plot handlers. There name stems from the fact
that the plots they produce look like ``combs'' (more or less).

\begin{command}{\pgfplothandlerxcomb}
  This handler converts each point in the plot stream into a line from
  the $y$-axis to the point's coordinate, resulting in a ``horizontal
  comb.''

  
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerxcomb
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}


\begin{command}{\pgfplothandlerycomb}
  This handler converts each point in the plot stream into a line from
  the $x$-axis to the point's coordinate, resulting in a ``vertical
  comb.''
  
  This handler is useful for creating ``bar diagrams.''
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerycomb
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfplothandlerpolarcomb}
  This handler converts each point in the plot stream into a line from
  the origin to the point's coordinate.
  
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerpolarcomb
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\pgfname\ bar or comb plots usually draw something from zero to the
current plot's coordinate. The ``zero'' offset can be changed using an
input stream which returns the desired offset successively for each
processed coordinate. 

There are two such streams, which can be configured independently.
The first one returns ``zeros'' for coordinate~$x$, the second one
returns ``zeros'' for coordinate~$y$. They are used as follows.

\begin{codeexample}[code only]
\pgfplotxzerolevelstreamstart
\pgfplotxzerolevelstreamnext % assigns \pgf@x
\pgfplotxzerolevelstreamnext
\pgfplotxzerolevelstreamnext
\pgfplotxzerolevelstreamend
\end{codeexample}
%
\begin{codeexample}[code only]
\pgfplotyzerolevelstreamstart
\pgfplotyzerolevelstreamnext % assigns \pgf@x
\pgfplotyzerolevelstreamend
\end{codeexample}
Different zero level streams can be implemented by overwriting these macros.

\begin{command}{\pgfplotxzerolevelstreamconstant\marg{dimension}}
  This zero level stream always returns \marg{dimension} instead of
  $x=0$pt. 

  It is used for |xcomb| and |xbar|.
\end{command}

\begin{command}{\pgfplotyzerolevelstreamconstant\marg{dimension}}
  This zero level stream always returns \marg{dimension} instead of
  $y=0$pt. 

  It is used for |ycomb| and |ybar|.
\end{command}

\subsection{Bar Plot Handlers}
\label{section-plotlib-bar-handlers}

While comb plot handlers produce a line-to operation to generate
combs, bar plot handlers employ rectangular shapes, allowing filled
bars (or pattern bars). 

\begin{command}{\pgfplothandlerybar}
  This handler converts each point in the plot stream into a rectangle
  from the $x$-axis to the point's coordinate. The rectangle is placed
  centered at the $x$-axis. 
  
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerybar
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfplothandlerxbar}
  This handler converts each point in the plot stream into a rectangle
  from the $y$-axis to the point's coordinate. The rectangle is placed
  centered at the $y$-axis. 
  
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlerxbar
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\label{key-bar-width}%
\begin{key}{/pgf/bar width=\marg{dimension} (initially 10pt)}
  \keyalias{tikz}
  Sets the width of |\pgfplothandlerxbar| and |\pgfplothandlerybar| to
  \marg{dimension}. The argument \marg{dimension} will be evaluated
  using the math parser. 
\end{key}

\label{key-bar-shift}%
\begin{key}{/pgf/bar shift=\marg{dimension} (initially 0pt)}
  \keyalias{tikz}
  Sets a shift used by |\pgfplothandlerxbar| and |\pgfplothandlerybar|
  to \marg{dimension}. It has the same effect as |xshift|, but it
  applies only to those bar plots. The argument \marg{dimension} will
  be evaluated using the math parser. 
\end{key}

\begin{command}{\pgfplotbarwidth}
  Expands to the value of |/pgf/bar width|.
\end{command}


\begin{command}{\pgfplothandlerybarinterval}
  This handler is a variant of |\pgfplothandlerybar| which works with
  intervals instead of points. 
  
  Bars are drawn between successive input coordinates and the width is
  determined relatively to the interval length. 
  
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,2) node {$x_1$} (1,1) node {$x_2$} (2,.5) node {$x_3$} (4,0.7) node {$x_4$};
  \pgfplothandlerybarinterval
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}

In more detail, if $(x_i,y_i)$ and $(x_{i+1},y_{i+1})$ denote
successive input coordinates, the bar will be placed above the
interval $[x_i,x_{i+1}]$, centered at \[ x_i + \text{\meta{bar
    interval shift}} \cdot (x_{i+1} - x_i) \] with width \[
\text{\meta{bar interval width}} \cdot (x_{i+1} - x_i). \] Here,
\meta{bar interval shift} and \meta{bar interval width} denote the
current values of the associated options. 

If you have $N+1$ input points, you will get $N$ bars (one for each
interval). The $y$~value of the last point will be ignored. 
\end{command}

\begin{command}{\pgfplothandlerxbarinterval}
   As |\pgfplothandlerybarinterval|, this handler provides bar plots
   with relative bar sizes and offsets, one bar for each
   $y$~coordinate interval. 
\end{command}

\label{key-bar-interval-shift}%
\begin{key}{/pgf/bar interval shift=\marg{shift} (initially 0.5)}
  \keyalias{tikz}
  Sets the \emph{relative} shift of |\pgfplothandlerxbarinterval| and
  |\pgfplothandlerybarinterval| to \marg{shift}. As
  |/pgf/bar interval width|, the argument is relative to the interval
  length of the input coordinates. 
	
  The argument \marg{scale} will be evaluated using the math parser.
\end{key}

\label{key-bar-interval-width}%
\begin{key}{/pgf/bar interval width=\marg{scale} (initially 1)}
  \keyalias{tikz}
  Sets the \emph{relative} width of |\pgfplothandlerxbarinterval| and
  |\pgfplothandlerybarinterval| to \marg{scale}. The argument is
  relative to $(x_{i+1} - x_i)$ for $y$~bar plots and relative to
  $(y_{i+1}-y_i)$ for $x$~bar plots. 
	
  The argument \marg{scale} will be evaluated using the math parser.
\begin{codeexample}[]
\begin{tikzpicture}[bar interval width=0.5]  
  \draw[gray] 
  	(0,3) -- (0,-0.1) 
    (1,3) -- (1,-0.1)
    (2,3) -- (2,-0.1)
    (4,3) -- (4,-0.1);
  \pgfplothandlerybarinterval
  \begin{scope}[bar interval shift=0.25,fill=blue]
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
  \pgfplotstreamend
  \pgfusepath{fill}
  \end{scope}
  \begin{scope}[bar interval shift=0.75,fill=red]
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{3cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{0.2cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.7cm}}
  \pgfplotstreampoint{\pgfpoint{4cm}{0.2cm}}
  \pgfplotstreamend
  \pgfusepath{fill}
  \end{scope}
\end{tikzpicture}
\end{codeexample}
  Please note that bars are always centered, so we have to use shifts
  $0.25$ and $0.75$ instead of $0$ and $0.5$. 
\end{key}

\subsection{Mark Plot Handler}

\label{section-plot-marks}

\begin{command}{\pgfplothandlermark\marg{mark code}}
  This command will execute the \meta{mark code} for some points of the
  plot, but each time the coordinate transformation matrix will be
  setup such that the origin is at the position of the point to be
  plotted. This way, if the \meta{mark code} draws a little circle
  around the origin, little circles will be drawn at some point of the
  plot.

  By default, a mark is drawn at all points of the plot. However, two
  parameters $r$ and $p$ influence this. First, only every $r$th mark
  is drawn. Second, the first mark drawn is the $p$th. These
  parameters can be influenced using the commands below.
  
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}

  Typically, the \meta{code} will be |\pgfuseplotmark{|\meta{plot mark
      name}|}|, where \meta{plot mark name} is the name of a
  predefined plot mark.
\end{command}

\begin{command}{\pgfsetplotmarkrepeat\marg{repeat}}
  Sets the $r$ parameter to \meta{repeat}, that is, only every $r$th
  mark will be drawn.
\end{command}

\begin{command}{\pgfsetplotmarkphase\marg{phase}}
  Sets the $p$ parameter to \meta{phase}, that is, the first mark to
  be drawn is the $p$th, followed by the $(p+r)$th, then the
  $(p+2r)$th, and so on.
\end{command}

\begin{command}{\pgfplothandlermarklisted\marg{mark code}\marg{index list}}
  This command works similar to the previous one. However, marks will
  only be placed at those indices in the given \meta{index list}. The
  syntax for the list is the same as for the |\foreach| statement. For
  example, if you provide the list |1,3,...,25|, a mark will be placed
  only at every second point. Similarly, |1,2,4,8,16,32| yields marks
  only at those points that are powers of two.
  
\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlermarklisted
    {\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
    {1,3}
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfuseplotmark\marg{plot mark name}}
  Draws the given \meta{plot mark name} at the origin. The \meta{plot
    mark name} must previously have been declared using
  |\pgfdeclareplotmark|. 

\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlermark{\pgfuseplotmark{pentagon}}
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}}
  Declares a plot mark for later used with the |\pgfuseplotmark|
  command.

\begin{codeexample}[]
\pgfdeclareplotmark{my plot mark}
  {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke}  
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfplothandlermark{\pgfuseplotmark{my plot mark}}
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}


\begin{command}{\pgfsetplotmarksize\marg{dimension}}
  This command sets the \TeX\ dimension |\pgfplotmarksize| to
  \meta{dimension}. This dimension is a ``recommendation'' for plot
  mark code at which size the plot mark should be drawn; plot mark
  code may choose to ignore this \meta{dimension} altogether. For
  circles, \meta{dimension} should  be the radius, for other shapes it
  should be about half the width/height.

  The predefined plot marks all take this dimension into account.

\begin{codeexample}[]
\begin{tikzpicture}    
  \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
  \pgfsetplotmarksize{1ex}
  \pgfplothandlermark{\pgfuseplotmark{*}}
  \pgfplotstreamstart
  \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
  \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
  \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
  \pgfplotstreamend
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{textoken}{\pgfplotmarksize}
  A \TeX\ dimension that is a ``recommendation'' for the size of plot
  marks.
\end{textoken}

The following plot marks are predefined (the filling color has been
set to yellow):

\medskip
\begin{tabular}{lc}
  \plotmarkentry{*}
  \plotmarkentry{x}
  \plotmarkentry{+}
\end{tabular}


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: