summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-dv-visualizers.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-dv-visualizers.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-dv-visualizers.tex818
1 files changed, 818 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-dv-visualizers.tex b/graphics/pgf/base/doc/pgfmanual-en-dv-visualizers.tex
new file mode 100644
index 0000000000..f1e5c06ed8
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-dv-visualizers.tex
@@ -0,0 +1,818 @@
+% Copyright 2019 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{Visualizers}
+\label{section-dv-visualizers}
+
+\subsection{Overview}
+
+In a data visualization a long stream of data points is \emph{visualized} using
+\emph{visualizers}. Recall that it is the job of the axis systems as described
+in Section~\ref{section-dv-axes} to determine \emph{where} data points are
+visualized. It is the job of the visualizers to determine \emph{how} they are
+visualized.
+
+The most basic and common visualizer is the \emph{line visualizer}. It simply
+connects subsequent data points by straight lines to indicate either that the
+points on these lines interpolate between the real data points or the straight
+lines are used to indicate the order in which the data points appear. A
+different, more ``conservative'' visualizer is the \emph{scatter visualizer} or
+\emph{mark visualizer}, which just places a small mark at each data point. Such
+a visualizer does not imply any interpolation or ordering between the data
+points.
+
+Visualizers may, however, also be more complicated. For instance, a visualizer
+used for a box plot could visualize a data point as a box with a median value,
+standard deviation, outliers, and other information; a rectangle visualizer
+might visualize data points as larger areas; a projection visualizer might
+visualize the projection of data points onto different axes; and so.
+
+Creating a new visualizer is not quite trivial since a new \pgfname\ class
+needs to be implemented. Fortunately, using visualizers is much simpler: For
+each kind of visualizer there is a key that allows you to create such a
+visualizer. You can then use further keys to configure the visualizer and to
+connect it to the data.
+
+In a data visualization multiple visualizers may exist at the same time. This
+happens in different situations:
+%
+\begin{itemize}
+ \item A data visualization may contain several independent data sets that
+ are to be visualized. There might be a line plot, for which a line
+ visualizer is used, and also a scatter plot, for which a scatter
+ visualizer would be used.
+
+ In this case, for each data point only one visualizer will do anything.
+ To achieve this, each data point has an attribute called |visualizer|
+ which tells the visualizer objects whether they should ``react'' to the
+ data point or not.
+ \item A single data point might be visualized several times. For instance,
+ a scatter visualizer might draw a mark at the data point's position on
+ the page and a projection visualizer might draw, additionally, a mark
+ at the projected position.
+\end{itemize}
+
+
+\subsection{Usage}
+
+\subsubsection{Using a Single Visualizer}
+
+The simplest scenario for using visualizers are data visualizations in which
+there is only a single data set that is visualized in one style. In this case,
+all that needs to be done in order to choose a visualizer is use one of the
+options starting with |visualize as ...| together with the |\datavisualization|
+command:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+% Define a data set:
+\tikz \datavisualization data group {example} = {
+data {
+ x, y
+ 0, 0
+ 0.5, 2
+ 1, 2
+ 1.5, 1.5
+ 2, 0.5
+}};
+\tikz \datavisualization [school book axes, visualize as line] data group {example};
+\qquad
+\tikz \datavisualization [school book axes, visualize as smooth line] data group {example};
+\qquad
+\tikz \datavisualization [school book axes, visualize as scatter] data group {example};
+\end{codeexample}
+
+Methods for styling visualizers are discussed in
+Section~\ref{section-dv-visualizer-styling}.
+
+
+\subsubsection{Using Multiple Visualizers}
+
+A data visualization may contain multiple data groups and for each data set we
+might wish to use a different visualizer. In this case, we need some way of
+telling the data visualization engine to which visualizer should be used with
+the different data points.
+
+To solve this problem, you can \emph{name} a visualizer. The visualizer's name
+can then both be used to configure the visualizer and also to indicate that
+data points ``belong'' to the visualizer.
+
+Naming a visualizer is quite simple: The |visualize as ...| keys actually take
+a single parameter, which is the name of the visualizer. For instance, the
+following code creates three visualizers, named |sin|, |cos|, and |tan|:
+%
+\begin{codeexample}[code only]
+visualize as line=sin,
+visualize as line=cos,
+visualize as scatter=tan
+\end{codeexample}
+
+(When you just say |visualize as line| without providing a name, the name
+|line| is chosen as a default, for |visualize as scatter| the name |scatter| is
+the default and so.)
+
+In order to indicate which data points should be visualized by which of these
+visualizers, the following key is important:
+
+\begin{key}{/data point/set}
+ A visualizer will only act on a data point when its name matches the value
+ of this key. Initially, this key is set to the last visualizer created, so
+ if there is only one, there is no need to set or worry about this key.
+\end{key}
+
+Since the |set| key has the path prefix |/data point|, it can be set like any
+other attribute of a data key:
+%
+\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization
+ [scientific axes=clean,
+ visualize as line=sin,
+ visualize as line=cos,
+ visualize as scatter=tan]
+data {
+ x, y, set
+ 0, 0, sin
+ 1, 1, sin
+ 2, 0, sin
+ 3, -1, sin
+ 4, 0, sin
+ 0, 1, cos
+ 1, 0, cos
+ 0, 0, tan
+ 1, 1, tan
+ 2, 2, tan
+ 3, 4, tan
+ 2, -1, cos
+ 3, 0, cos
+ 4, 1, cos
+};
+\end{codeexample}
+
+As can be seen, the data points with the same |set| attribute do not need to be
+consecutive.
+
+The above method of specifying the visualizer works nicely, but in most cases
+it would be more natural to keep the |set| attribute out of the table. This is
+easy to achieve by using multiple |data| and using the following key:
+
+\begin{key}{/pgf/data/set=\meta{name}}
+ Shorthand for |/data point/set=|\meta{name}.
+ %
+\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization
+ [scientific axes=clean,
+ visualize as line=sin,
+ visualize as line=cos]
+data [set=sin] {
+ x, y
+ 0, 0
+ 1, 1
+ 2, 0
+ 3, -1
+ 4, 0
+}
+data [set=cos] {
+ x, y
+ 0, 1
+ 1, 0
+ 2, -1
+ 3, 0
+ 4, 1
+};
+\end{codeexample}
+ %
+\end{key}
+
+When you need to visualize several similar things in a single plot (like ten
+lines that all get visualized by |visualize as line|), it is somewhat
+cumbersome having to write this ten times. In this case you can shorten your
+code by making use of the |.list| key handler: When you add it to a key, the
+``value'' passed to the key is parsed as a list of values. The key is then
+executed once for each of these values:
+%
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes=clean,
+ visualize as line/.list={sin, cos, tan}]
+data [set=sin, format=function] {
+ var x : interval[0:3*pi];
+ func y = sin(\value x r);
+}
+data [set=cos, format=function] {
+ var x : interval[0:3*pi];
+ func y = cos(\value x r);
+}
+data [set=tan, format=function] {
+ var x : interval[0:pi/2.2];
+ func y = tan(\value x r);
+};
+\end{codeexample}
+
+
+\subsubsection{Styling a Visualizer}
+\label{section-dv-visualizer-styling}
+
+In order to style a visualizer that has been created using for instance
+|visualize as line=|\meta{visualizer name}, you can use the following key:
+
+\begin{key}{/tikz/data visualization/\meta{visualizer name}=\meta{options}}
+ For each visualizer, a key of the same name is created with the path prefix
+ |/tikz/data visualization|. This key takes the \meta{options} and executes
+ them with the path prefix
+ %
+\begin{codeexample}[code only]
+/tikz/data visualization/visualizer options/
+\end{codeexample}
+ %
+ These options are then used to configure the appearance of the current
+ visualizer. (This is quite similar to the way options are passed to an axis
+ in order to configure the axis.) Possible options include |style|, but also
+ |label in legend| and |label in data|. The latter two options are discussed
+ in Section~\ref{section-dv-labels-in}, the first option below.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes=clean,
+ visualize as smooth line/.list={sin, cos},
+ sin={style=red},
+ cos={style=blue}]
+data [set=sin, format=function] {
+ var x : interval[0:3*pi];
+ func y = sin(\value x r);
+}
+data [set=cos, format=function] {
+ var x : interval[0:3*pi];
+ func y = cos(\value x r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/style=\meta{options}}
+ The \meta{options} given to this key should be normal \tikzname\ options.
+ They will be executed when the visualizer is used.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes=clean,
+ visualize as smooth line=sin,
+ sin={style={red, densely dotted}},
+ visualize as smooth line=cos,
+ cos={style={mark=x}},
+]
+data [set=sin, format=function] {
+ var x : interval[0:3*pi];
+ func y = sin(\value x r);
+}
+data [set=cos, format=function] {
+ var x : interval[0:3*pi];
+ func y = cos(\value x r);
+};
+\end{codeexample}
+
+ When you have multiple visualizers in a single data visualization, you can
+ use the |style| option with each visualizer to configure their different
+ appearances as in the above example. However, it is usually much better
+ (and easier) to use a style sheet, see
+ Section~\ref{section-dv-style-sheets}.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes={clean, end labels},
+ x axis={label=$x$}, y axis={grid={major also at=0}},
+ visualize as smooth line/.list={sin,cos,sin 2,cos 2},
+ legend={below, rows=2},
+ sin={label in legend={text=$\sin x$}},
+ cos={label in legend={text=$\cos x$}},
+ sin 2={label in legend={text=$\sin 2x$}},
+ cos 2={label in legend={text=$\cos 2x$}},
+ style sheet=strong colors]
+data [set=sin, format=function] {
+ var x : interval[0:3*pi];
+ func y = sin(\value x r);
+}
+data [set=cos, format=function] {
+ var x : interval[0:3*pi];
+ func y = cos(\value x r);
+}
+data [set=sin 2, format=function] {
+ var x : interval[0:3*pi];
+ func y = sin(2*\value x r);
+}
+data [set=cos 2, format=function] {
+ var x : interval[0:3*pi];
+ func y = cos(2*\value x r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/ignore style sheets}
+ This option, which should be passed to a visualizer after its creation
+ before another visualizer is created, causes style sheets \emph{not} to
+ apply to the visualizer (but the |style| option will still have an effect).
+ This allows you to create visualizers that are used for special purposes
+ and that do not ``take part'' in the usual styling. For instance, a
+ visualizer might be used internally to depict a regression line, even
+ though the regression line itself should not participate in the usual
+ styling by, say, dashing or different coloring.
+\end{key}
+
+In addition to the options passed to a visualizer via |style|, the following
+also gets executed when a visualizer is used:
+
+\begin{stylekey}{/tikz/data visualization/every visualizer}
+ This style is used with every visualizer. Note that it should contain
+ normal \tikzname\ keys.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes=clean,
+ every visualizer/.style={dashed},
+ visualize as smooth line]
+data [format=function] {
+ var x : interval[0:3*pi];
+ func y = sin(\value x r);
+};
+\end{codeexample}
+ %
+\end{stylekey}
+
+
+\subsection{Reference: Basic Visualizers}
+
+\subsubsection{Visualizing Data Points Using Lines}
+
+\begin{key}{/tikz/data visualizers/visualize as line=\meta{visualizer name} (default line)}
+ Creates a new visualizer named \meta{visualizer name}. Basically, this
+ visualizer connects all data points for which the |/data point/set|
+ attribute equals \meta{visualizer name} by a line that is styled by the
+ visualizer's style.
+
+ In more detail, the following happens:
+ %
+ \begin{enumerate}
+ \item A new object is created (of class |plot handler visualizer|) that
+ is configured to collect the canvas positions of all data points
+ whose |set| attribute equals \meta{visualizer name}.
+ \item During the end of the data visualization, \pgfname's plotting
+ mechanism (see Section~\ref{section-plots}) is used to plot the
+ stream of recorded data points.
+
+ This means that, in principle, all of the plot handlers available
+ in \tikzname\ could be used for the visualization (such as the
+ |smooth| handler). However, some plot handlers such as, say, the
+ |xcomb| are unsuitable as plot handlers since they do not support
+ the advanced axis handling done by the data visualization engine.
+ Because of this (and also for other reasons), you cannot set the
+ plot handler directly, but must use one of the options like
+ |straight line|, |smooth line| and others, documented in a moment.
+ \item Additionally, plot marks can be drawn at the collected data
+ points. Here, all of the options available to \tikzname\ for
+ drawing plot marks are available. To configure them, all options
+ offered by \tikzname\ for configuring marks are available such as
+ |mark repeat|:
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes=clean,
+ visualize as line=my data,
+ my data={style={mark=x, mark repeat=3}}]
+data [format=function] {
+ var x : interval [0:pi] samples 10;
+ func y = sin(\value x r);
+};
+\end{codeexample}
+ \end{enumerate}
+
+ The line visualizer also provides a method of dealing with gaps in a line.
+ Take for instance the function $f(x) = \tan x$. When this function is
+ plotted over the interval $[0,\pi]$, then the function will go to $\pm
+ \infty$ at $\pi/2$. When we plot this, we might plot the function in the
+ interval $[0,\frac{\pi}{2}-\epsilon]$ and then continue in the interval
+ $[\frac{\pi}{2}+\epsilon,\pi]$. However, we do not want the point at
+ coordinate $\bigl(\frac{\pi}{2}- \epsilon, \tan(\frac{\pi}{2}-
+ \epsilon)\bigr)$ to be connected to the coordinate $\bigl(\frac{\pi}{2}+
+ \epsilon, \tan(\frac{\pi}{2}+ \epsilon)\bigr)$ by a line. Rather, there
+ should be a ``gap'' or a ``jump'' between these coordinates. To achieve
+ this, the following key can be used:
+ %
+ \begin{key}{/data point/outlier=\meta{value} (default true, initially \normalfont empty)}
+ When this key is set to anything non-empty value, a visualizer will
+ consider this data point to be an ``outlier''. For a line visualizer
+ this means that the point is not shown and that the current line ends
+ at the previous data point and a new line starts at the next data
+ point.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes=clean, x axis={grid={major at=(pi/2)}},
+ visualize as smooth line]
+data [format=function] {
+ var x : interval[0:pi/2-0.1];
+ func y = tan(\value x r);
+}
+data point [outlier]
+data [format=function] {
+ var x : interval[pi/2+0.1:pi];
+ func y = tan(\value x r);
+};
+\end{codeexample}
+ \end{key}
+\end{key}
+
+\begin{key}{/tikz/data visualizers/visualize as smooth line=\meta{visualizer name} (default line)}
+ A shorthand |visualize as line=|\meta{visualizer name} followed
+ \meta{visualizer name}|=smooth line|.
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/straight line}
+ Causes the data points to be connected by straight lines.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz [scale=.55] \datavisualization
+ [scientific axes=clean, all axes={ticks=few},
+ visualize as smooth line=my data, my data={straight line}]
+data [format=function] {
+ var t : interval [0:4] samples 5;
+ func x = cos(\value t r);
+ func y = sin(\value t r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/straight cycle}
+ Causes the data points to be connected by a polygon.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz [scale=.55] \datavisualization
+ [scientific axes=clean, all axes={ticks=few},
+ visualize as smooth line=my data, my data={straight cycle}]
+data [format=function] {
+ var t : interval [0:4] samples 5;
+ func x = cos(\value t r);
+ func y = sin(\value t r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/polygon}
+ This is an alias for |straight cycle|.
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/smooth line}
+ Causes the data points to be connected by a line that is smoothed at the
+ joins:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz [scale=.55] \datavisualization
+ [scientific axes=clean, all axes={ticks=few},
+ visualize as smooth line=my data, my data={smooth line}]
+data [format=function] {
+ var t : interval [0:4] samples 5;
+ func x = cos(\value t r);
+ func y = sin(\value t r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/smooth cycle}
+ Causes the data points to be connected by a circular line that is smoothed
+ at the joins:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz [scale=.55] \datavisualization
+ [scientific axes=clean, all axes={ticks=few},
+ visualize as smooth line=my data, my data={smooth cycle}]
+data [format=function] {
+ var t : interval [0:4] samples 5;
+ func x = cos(\value t r);
+ func y = sin(\value t r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/gap line}
+ This key causes the data points to be connected by lines that ``do not
+ quite touch'' the data points. This is implemented by using the
+ |\pgfplothandlergaplineto|, see Section~\ref{section-plot-gapped}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz [scale=.55] \datavisualization
+ [scientific axes=clean, all axes={ticks=few},
+ visualize as smooth line=my data, my data={gap line}]
+data [format=function] {
+ var t : interval [0:4] samples 5;
+ func x = cos(\value t r);
+ func y = sin(\value t r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/gap cycle}
+ Like |gapped line|, only with a cycle:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz [scale=.55] \datavisualization
+ [scientific axes=clean, all axes={ticks=few},
+ visualize as smooth line=my data, my data={gap cycle}]
+data [format=function] {
+ var t : interval [0:4] samples 5;
+ func x = cos(\value t r);
+ func y = sin(\value t r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/data visualization/visualizer options/no lines}
+ Suppresses the line. This option only makes sense when the |mark| option is
+ used.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz [scale=.55] \datavisualization
+ [scientific axes=clean, all axes={ticks=few},
+ visualize as smooth line=my data, my data={no lines, style={mark=x}}]
+data [format=function] {
+ var t : interval [0:4] samples 5;
+ func x = cos(\value t r);
+ func y = sin(\value t r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsubsection{Visualizing Data Points Using Marks}
+
+\begin{key}{/tikz/data visualizers/visualize as scatter=\meta{visualizer name} (default scatter)}
+ A shorthand |visualize as line=|\meta{visualizer name} followed
+ \meta{visualizer name}|=no lines| and setting the |style| of the visualizer
+ so that is will use |mark=x| (plus some size adjustments) to draw marks at
+ the data points.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes=clean,
+ visualize as scatter]
+data [format=function] {
+ var x : interval [0:pi] samples 10;
+ func y = sin(\value x r);
+};
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsection{Advanced: Creating New Visualizers}
+
+Creating a new visualizer is a two-stage process that does, unfortunately,
+require in-depth knowledge of the data visualization backend:
+%
+\begin{enumerate}
+ \item First, you need to create a new class using |\pgfooclass| whose
+ instances react to the signal |visualize datapoint signal|. This
+ requires detailed knowledge of the data visualization engine, see
+ Section~\ref{section-dv-backend}.
+ \item Second, you should provide keys on the \tikzname\ level for creating
+ the necessary objects. These keys invoke the key |new visualizer|
+ internally.
+\end{enumerate}
+
+\begin{key}{/tikz/data visualization/new visualizer=\marg{name}\marg{options}\marg{legend entry options}}
+ This key configures a new visualizer named \meta{name}. This entails the
+ following actions:
+ %
+ \begin{itemize}
+ \item The key |/tikz/data visualization/|\meta{name} is created. As
+ described earlier, this key can be used to pass for instance
+ |style| options to the visualizer.
+ \item The style key
+ |/tikz/data visualization/visualizers/|\meta{name}|/styling| is
+ created and made empty. This is the key in which the |style| key
+ will store the options passed to the visualizer.
+ \item The style key
+ |/tikz/data visualization/visualizers/|\meta{name}|/label in legend options|
+ is set to \meta{legend entry options}. These options are used to
+ configure how the visualizer should be rendered in a legend, see
+ Section~\ref{section-dv-legend-entries} for details.
+ \item The key |/data point/set/|\meta{name} is set to a number that is
+ increased for each visualizer in the current data visualization.
+ This number is important for style sheets, see
+ Section~\ref{section-dv-style-sheets}.
+ \item The key |/data point/|\meta{name}|/execute at begin| is set to
+ code that creates a |{scope}| that executes the following styles as
+ options:
+ %
+ \begin{enumerate}
+ \item The \meta{options} passed to the |new visualizer| key.
+ \item The |every visualizer| style.
+ \item The styling from the currently active style sheets, see
+ Section~\ref{section-dv-style-sheets}.
+ \item The styling stored in the |styling| key mentioned above.
+ \end{enumerate}
+ %
+ \item The key |/data point/|\meta{name}|/execute at end| is set to code
+ that will finish all paths that may have been created by the
+ visualizer and closes the scope.
+ \end{itemize}
+
+ All of the above mean the following in practice:
+ %
+ \begin{itemize}
+ \item Inside a new |visualize as ...| key, you pass the name of the
+ to-be-created to |new visualizer| as the first parameter and any
+ special default styling setup of the visualizer as the second
+ parameter.
+ \item The new |visualize as ...| key should also create a visualizer
+ object using |new object|.
+ \item When this object finally is about to create the actual
+ visualization, it should surround the code by invoking the code
+ stored in the |execute at begin| and the |execute at end| keys of
+ the visualizer.
+ \end{itemize}
+
+ Everything else is usually taken care of by the |new visualizer| key
+ automatically.
+\end{key}
+
+As an example, let us create a simple visualizer that creates a circle whose
+radius is dictated by the |radius| attribute. To keep things simple in this
+example, this attribute cannot be configured.
+
+First, we need the visualizer class. For this example I have boiled it down to
+a minimum:
+%
+\begin{codeexample}[code only]
+\pgfooclass{circle visualizer}
+{
+ % Stores the name of the visualizer. This is needed for filtering and configuration
+ \attribute name;
+
+ % The constructor. Just setup the attribute.
+ \method circle visualizer(#1) { \pgfooset{name}{#1} }
+
+ % Connect to visualize signal.
+ \method default connects() {
+ \pgfoothis.get handle(\me)
+ \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal)
+ }
+
+ % This method is invoked for each data point. It checks whether the data point belongs to the correct
+ % visualizer and, if so, calls the macro \dovisualization to do the actual visualization.
+ \method visualize() {
+ \pgfdvfilterpassedtrue
+ \pgfdvnamedvisualizerfilter
+ \ifpgfdvfilterpassed
+ \dovisualization
+ \fi
+ }
+}
+\end{codeexample}
+
+The |\dovisualization| method must now do the correct visualization.
+%
+\begin{codeexample}[code only]
+\def\dovisualization{
+ \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin}
+ \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}}
+ % \pgfusepath is done by |execute at end|
+ \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end}
+}
+\end{codeexample}
+
+Finally, we create a |visualize as| key:
+%
+\begin{codeexample}[code only]
+\tikzdatavisualizationset{
+ visualize as circle/.style={
+ new object={
+ when=after survey,
+ store=/tikz/data visualization/visualizers/#1,
+ class=circle visualizer,
+ arg1=#1
+ },
+ new visualizer={#1}{%
+ color=visualizer color, % a color setup by the style sheet
+ every path/.style={fill,draw}, % fill and draw the circle by default,
+ }{}, % let's ignore legends in this example
+ /data point/set=#1
+ },
+ visualize as circle/.default=circle
+}
+\end{codeexample}
+
+Now, let's see how this works:
+
+% TODOsp: codeexamples: This stuff is all needed for the next `codeexample`
+% but cannot be stored (simply) in `setup code`, `preample` or `pre`
+\pgfooclass{circle visualizer} {
+ % Stores the name of the visualizer. This is needed for filtering
+ % and configuration
+ \attribute name;
+
+ % The constructor. Just setup the attribute.
+ \method circle visualizer(#1) { \pgfooset{name}{#1} }
+
+ % Connect to visualize signal.
+ \method default connects() {
+ \pgfoothis.get handle(\me)
+ \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal)
+ }
+
+ % This method is invoked for each data point. It checks whether the
+ % data point belongs to the correct visualizer and, if so, calls the
+ % macro \dovisualization to do the actual visualization.
+ \method visualize() {
+ \pgfdvfilterpassedtrue
+ \pgfdvnamedvisualizerfilter
+ \ifpgfdvfilterpassed
+ \dovisualization
+ \fi
+ }
+}
+
+\def\dovisualization{
+ \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin}
+ \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}}
+ % \pgfusepath is done by |execute at end|
+ \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end}
+}
+
+\tikzdatavisualizationset{
+ visualize as circle/.style={
+ new object={
+ when=after survey,
+ store=/tikz/data visualization/visualizers/#1,
+ class=circle visualizer,
+ arg1=#1
+ },
+ new visualizer={#1}{%
+ color=visualizer color, % a color setup by the style sheet
+ every path/.style={fill,draw}, % fill and draw the circle by default,
+ }{},
+ /data point/set=#1
+ },
+ visualize as circle/.default=circle
+}
+
+\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [
+ scientific axes=clean,
+ visualize as circle/.list={a, b, c},
+ style sheet=strong colors]
+data [set=a] {
+ x, y, radius
+ 0, 0, 2pt
+ 1, 1, 3pt
+ 1, 2, 3pt
+ 2, 0, 1pt
+}
+data [set=b] {
+ x, y, radius
+ 0.5, 0.5, 5pt
+ 1, 1.5, 2pt
+ 1, 2.5, 3pt
+ 0, 2, 4pt
+}
+data [set=c] {
+ x, y, radius
+ 3, 2, 3pt
+ 2.5, 0.5, 4pt
+};
+\end{codeexample}