PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.9a

Libraries

65 Plot Handler Library

  • TikZ Library plothandlers

  • \usepgflibrary{plothandlers} % and plain and pure pgf
    \usepgflibrary[plothandlers] % Cont and pure pgf
    \usetikzlibrary{plothandlers} % and plain when using TikZ
    \usetikzlibrary[plothandlers] % Cont when using TikZ

    This library packages defines additional plot handlers, see Section 112.3 for an introduction to plot handlers. The additional handlers are described in the following.

    This library is loaded automatically by TikZ.

65.1 Curve Plot Handlers
  • \pgfplothandlercurveto

  • This handler will issue a \pgfpathcurveto command for each point of the plot, 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\):

    (-tikz- diagram)

    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.

65.2 Constant Plot Handlers

There are several plot handlers which produce piecewise constant interpolations between successive points:

65.3 Comb Plot Handlers

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

pgf 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.


\pgfplotxzerolevelstreamstart
\pgfplotxzerolevelstreamnext % assigns \pgf@x
\pgfplotxzerolevelstreamnext
\pgfplotxzerolevelstreamnext
\pgfplotxzerolevelstreamend

\pgfplotyzerolevelstreamstart
\pgfplotyzerolevelstreamnext % assigns \pgf@x
\pgfplotyzerolevelstreamend

Different zero level streams can be implemented by overwriting these macros.

  • \pgfplotxzerolevelstreamconstant{dimension}

  • This zero level stream always returns {dimension} instead of \(x=0\)pt.

    It is used for xcomb and xbar.

  • \pgfplotyzerolevelstreamconstant{dimension}

  • This zero level stream always returns {dimension} instead of \(y=0\)pt.

    It is used for ycomb and ybar.

65.4 Bar Plot 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).

  • /pgf/bar width={dimension} (no default, initially 10pt)

  • alias /tikz/bar width

    Sets the width of \pgfplothandlerxbar and \pgfplothandlerybar to {dimension}. The argument {dimension} will be evaluated using the math parser.

  • /pgf/bar shift={dimension} (no default, initially 0pt)

  • alias /tikz/bar shift

    Sets a shift used by \pgfplothandlerxbar and \pgfplothandlerybar to {dimension}. It has the same effect as xshift, but it applies only to those bar plots. The argument {dimension} will be evaluated using the math parser.

  • \pgfplotbarwidth

  • Expands to the value of /pgf/bar width.

  • \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.

    (-tikz- diagram)


    \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}

    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, bar interval shift and 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.

  • \pgfplothandlerxbarinterval

  • As \pgfplothandlerybarinterval, this handler provides bar plots with relative bar sizes and offsets, one bar for each \(y\) coordinate interval.

  • /pgf/bar interval shift={factor} (no default, initially 0.5)

  • alias /tikz/bar interval shift

    Sets the relative shift of \pgfplothandlerxbarinterval and \pgfplothandlerybarinterval to factor. As /pgf/bar interval width, the argument is relative to the interval length of the input coordinates.

    The argument {scale} will be evaluated using the math parser.

65.5 Gapped Plot Handlers
65.6 Mark Plot Handler
  • \pgfsetplotmarkrepeat{repeat}

  • Sets the \(r\) parameter to repeat, that is, only every \(r\)th mark will be drawn.

  • \pgfsetplotmarkphase{phase}

  • Sets the \(p\) parameter to 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.

  • \pgfplotmarksize

  • A dimension that is a “recommendation” for the size of plot marks.

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

\pgfuseplotmark{*} (-tikz- diagram)
\pgfuseplotmark{x} (-tikz- diagram)
\pgfuseplotmark{+} (-tikz- diagram)