summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-10-29 00:31:31 +0000
committerKarl Berry <karl@freefriends.org>2010-10-29 00:31:31 +0000
commit6bc1f5497cfb2f56d65c80a4c36ea3bad6dc046c (patch)
treef7751da75030fb1e06653eeb44e579fcee09c65f /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex
parented0c7c756e441b2d2ba3633da233fc24361ac0d3 (diff)
pgf 2.10 (28oct10)
git-svn-id: svn://tug.org/texlive/trunk@20236 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex721
1 files changed, 721 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex
new file mode 100644
index 00000000000..a2743a9fb57
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex
@@ -0,0 +1,721 @@
+% Copyright 2008 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{Creating Data Visualizations}
+\label{section-dv-main}
+\label{section-dv-main-setup}
+
+\subsection{Overview}
+
+The present section explains how a data visualization is created in
+\tikzname. For this, you need to include the |datavisualization|
+library and then use the command |\datavisualization| whose syntax is
+explained in the rest of the present section. This command is part of
+the following library:
+
+\begin{tikzlibrary}{datavisualization}
+ This library must be loaded if you wish to use the
+ |\datavisualization| command. It defines all styles needed to create
+ basic data visualizations; additional, more specialized libraries
+ need to be loaded for more advanced features.
+\end{tikzlibrary}
+
+
+In order to visualize, you basically need to do three things:
+\begin{enumerate}
+\item You need to select what kind of plot you would like to have (a
+ ``school book plot'' or a ``scientific 2d plot'' or a ``scientific
+ spherical plot'' etc.). This is done by passing an option to the
+ |\datavisualization| command that selects this kind of plot.
+\item You need to provide data points, which is done using the |data|
+ command.
+\item Additionally, you can add options that give you more
+ fine-grained control over the way the visualization will look. You
+ can configure the number of ticks and grid lines, where the labels
+ are placed, the colors, or the fonts. Indeed, since the
+ data visualization engine internally uses \tikzname-styles, you can
+ have extremely fine-grained control over how a plot will look like.
+\end{enumerate}
+
+The syntax of the |\datavisualization| command is designed in such a
+way that if you only need to provide very few options to create plots
+that ``look good by default''.
+
+This section is structured as follows: First, the philosophy behind
+concepts like ``data points,'' ``axes,'' or ``visualizers'' is
+explained. Each of these concepts is further detailed in later
+section. Then, the syntax of the |\datavisualization| command is
+covered. The reference sections explain which predefined plot kinds
+are available.
+
+
+\subsection{Concept: Data Points and Data Formats}
+
+As explained in Section~\ref{section-dv-intro-data-points}, data
+points are the basic entities that are processed by the data
+visualization engine. In order to specify data points, you use the
+|data| command, whose syntax is explained in more detail in
+Section~\ref{section-dv-data-syntax}. The |data| command allows you to
+either specify points ``inline,'' directly inside your \TeX-file; or
+you can specify the name of file that contains the data points.
+
+\medskip
+\textbf{Specifying data points.}
+Data points can be formatted in different ways. For instance, in the so
+called \emph{comma separated values} format, there is one line for
+each data point and the different attributes of a data point are
+separated by commas. Another common format is to specify data points
+using the so called \emph{key-value} format, where on each line the
+different attributes of a data point are set using a comma-separated
+list of strings of the form |attribute=value|.
+
+Here are two examples, where similar data is given in different
+formats:
+
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \datavisualization [school book axes, visualize as smooth line]
+ data {
+ x, y
+ -1.5, 2.25
+ -1, 1
+ -.5, .25
+ 0, 0
+ .5, .25
+ 1, 1
+ 1.5, 2.25
+ };
+\end{tikzpicture}
+ \end{codeexample}
+
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \datavisualization [school book axes, visualize as smooth line]
+ data [format=function] {
+ var x : interval [-1.5:1.5] samples 7;
+ func y = \value x*\value x;
+ };
+\end{tikzpicture}
+ \end{codeexample}
+
+In the first example, no format needed to be specified explicitly
+since the default format is the one used for the data following the
+|data| keyword: A list of comma-separated values, where each line
+represents a data point.
+
+\medskip
+\textbf{Number accuracy.}
+Data visualizations typically demand a much higher accuracy and range
+of values than \TeX\ provides: \TeX\ numbers are limited to 13 bits
+for the integer part and 16 bits for the fractional part. Because of
+this, the data visualization engine does not use \pgfname's standard
+representation of numbers and \TeX\ dimensions and is does not use the
+standard parser when reading numbers in a data point. Instead, the
+|fpu| library, described in Section~\ref{section-library-fpu}, is used
+to handle numbers.
+
+This use of the |fpu| library has several effects that users of the data
+visualization system should be aware of:
+\begin{enumerate}
+\item You can use numbers like |100000000000000| or |0.00000000001| in
+ a data points.
+\item Since the |fpu| library does not support advanced parsing, you
+ currently \emph{cannot} write things like |3+2| in a data point
+ number. This will result in an error
+\item However, there is a loop-hole: If a ``number'' in a data point
+ starts with a parenthesis, the value between the parentheses
+ \emph{is} parsed using the normal parser:
+ \begin{itemize}
+ \item |100000| is allowed.
+ \item |2+3| yields an error.
+ \item |(2+3)| is allowed and evaluates to |5|.
+ \item |(100000)| yields an error since $100000$ is beyond the normal
+ parser's precision.
+ \end{itemize}
+ The bottom line is that any normal calculations should be set inside
+ round parentheses, while large numbers should not be surrounded by
+ parentheses. Hopefully, in the future, these restrictions will be
+ lifted.
+\end{enumerate}
+
+
+Section~\ref{section-dv-formats} gives an
+in-depth coverage of the available data formats and explains how new
+data formats can be defined.
+
+
+
+
+\subsection{Concept: Axes, Ticks, and Grids}
+
+Most plots have two or three axes: A horizontal axis usually called
+the $x$-axis, a vertical axis called the $y$-axis, and possibly some
+axis pointing in a sloped direction called the $z$-axis. Axes are
+usually drawn as lines with \emph{ticks} indicating interesting
+positions on the axes. The data visualization engine gives you
+detailed control over where these ticks are rendered and how many of
+them are used. Great care is taken to ensure that the position of
+ticks are chosen well by default.
+
+From the point of view of the data visualization engine, axes are a
+somewhat more general concept than ``just'' lines that point ``along''
+some dimension: The data visualization engine uses axes to visualize
+any change of an attribute by varying the position of data points in the
+plane. For instance, in a polar plot, there is an ``axis'' for the
+angle and another ``axis'' for the distance if the point from the
+center. Clearly these axes vary the position of data points in the
+plane according to some attribute of the data points; but just as
+clearly they do not point in any ``direction.''
+
+A great benefit of this approach is that the powerful methods for
+specifying and automatic inference of ``good'' positions for ticks or
+grid lines apply to all sorts of situations. For instance, you can use
+it to automatically put ticks and grid lines at well-chosen angles of
+a polar plot.
+
+Typically, you will not need to specify axes explicitly. Rather,
+predefined styles take care of this for you:
+
+
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \datavisualization [
+ scientific axes,
+ x axis={length=3cm, ticks=few},
+ visualize as smooth line
+ ]
+ data [format=function] {
+ var x : interval [-1.5:1.5] samples 7;
+ func y = \value x*\value x;
+ };
+\end{tikzpicture}
+ \end{codeexample}
+
+
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \datavisualization [
+ scientific clean axes,
+ x axis={length=3cm, ticks=few},
+ all axes={grid},
+ visualize as smooth line
+ ]
+ data [format=function] {
+ var x : interval [-1.5:1.5] samples 7;
+ func y = \value x*\value x;
+ };
+\end{tikzpicture}
+ \end{codeexample}
+
+Section~\ref{section-dv-axes} explains in more detail how axes, ticks,
+and grid lines can be chosen and configured.
+
+
+\subsection{Concept: Visualizers}
+
+Data points and axes specify \emph{what} is visualized and
+\emph{where}. A \emph{visualizer} specifies \emph{how} they are
+visualized. One of the most common visualizers is a \emph{line
+ visualizer} which connects the positions of the data points in the
+plane using a line. Another common visualizer is the \emph{scatter
+ plot visualizer} where small marks are drawn at the positions of the
+data points. More advanced visualizers include, say, box plot
+visualizers or pie chart visualizers.
+
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \datavisualization [
+ scientific clean axes,
+ x axis={length=3cm, ticks=few},
+ visualize as smooth line
+ ]
+ data [format=function] {
+ var x : interval [-1.5:1.5] samples 7;
+ func y = \value x*\value x;
+ };
+\end{tikzpicture}
+ \end{codeexample}
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \datavisualization [
+ scientific clean axes,
+ x axis={length=3cm, ticks=few},
+ visualize as scatter
+ ]
+ data [format=function] {
+ var x : interval [-1.5:1.5] samples 7;
+ func y = \value x*\value x;
+ };
+\end{tikzpicture}
+ \end{codeexample}
+
+Section~\ref{section-dv-visualizers} provides more information on
+visualizers as well as reference lists.
+
+
+\subsection{Concept: Style Sheets and Legends}
+
+A single data visualizations may use more than one visualizer. For
+instance, if you wish to create a plot containing several lines, a
+separate visualizer is used for each line. In this case, two problems
+arise:
+
+\begin{enumerate}
+\item You may wish to make it easy for the reader to differentiate
+ between the different visualizers. For instance, one line should be
+ black, another should be red, and another blue. Alternatively, you
+ might wish one line to be solid, another to be dashed, and a third
+ to be dotted.
+
+ Specifying such styles is trickier than one might expect; experience
+ shows that many plots use ill-chosen and inconsistent
+ styling. For this reason, the data visualization introduces the
+ notion of \emph{style sheets} for visualizers and comes with some
+ well-designed predefined style sheets.
+\item You may wish to add information concerning what the different
+ visualizers represent. This is typically done using a legend, but it
+ is even better to add labels directly inside the visualization. Both
+ approaches are supported.
+\end{enumerate}
+
+An example where three functions are plotted and a legend is added is
+shown below. Two style sheets are used so that \emph{both} the
+coloring and the dashing is varied.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[baseline]
+ \datavisualization [ scientific clean axes,
+ y axis=grid,
+ visualize as smooth line/.list={sin,cos,tan},
+ visualizer style sheet=strong colors,
+ visualizer style sheet=vary dashing,
+ sin={label in legend={text=$\sin x$}},
+ cos={label in legend={text=$\cos x$}},
+ tan={label in legend={text=$\tan x$}},
+ data/format=function ]
+ data [sin] {
+ var x : interval [-0.5*pi:4];
+ func y = sin(\value x r);
+ }
+ data [cos] {
+ var x : interval [-0.5*pi:4];
+ func y = cos(\value x r);
+ }
+ data [tan] {
+ var x : interval [-0.3*pi:.3*pi];
+ func y = tan(\value x r);
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+Section~\ref{section-dv-style-sheets} details style sheets and
+legends.
+
+
+\subsection{Usage}
+\label{section-dv-data-syntax}
+
+Inside a \tikzname\ picture you can use the |\datavisualization|
+command to create a data visualization. You can use this command
+several times in a picture to create pictures containing multiple data
+visualizations.
+
+\begin{command}{\datavisualization\opt{\oarg{data visualization
+ options}}\meta{data specification}|;|}
+ This command is available only inside a |{tikzpicture}| environment.
+
+ The \meta{data visualization options} are used to configure the data visualization,
+ that is, how the data is to be depicted. The options are executed
+ with the path prefix |/tikz/data visualization|. This means that
+ normal \tikzname\ options like |thin| or |red| cannot be used
+ here. Rather, a large number of options specific to data
+ visualizations are available.
+
+ As a minimum, you should specify at least two options: First, you
+ should use an option that selects an axis system that is appropriate
+ for your plot. Typical possible keys are |school book axes| or
+ |scientific axes|, detailed information on them can be found in
+ Section~\ref{section-dv-axes}.
+
+ Second, you use an option to select
+ \emph{how} the data should be visualized. This is done using a key
+ like |visualize as line| which will, as the name suggests, visualize
+ the data by connecting data points in the plane using a
+ line. Similarly, |visualize as smooth cycle| will try to fit a smooth
+ cycle through the data points. Detailed information on possible
+ visualizers can be found in Section~\ref{section-dv-visualizers}.
+
+ Following these options, the \meta{data specification} is used to
+ provide the actual to-be-visualized data. The syntax is somewhat
+ similar to commands like |\path|: The \meta{data
+ specification} is a sequence of keywords followed by local options
+ and parameters, terminated with a semicolon. (Indeed, like for the
+ |\path| command, the \meta{data visualizers options} need not be
+ specified at the beginning, but additional option surrounded by
+ square brackets may be given anywhere inside the \meta{data specification}.)
+
+ The different possible keywords inside the \meta{data specification}
+ are explained in the following.
+\end{command}
+
+
+\begin{datavisualizationoperation}{data}{\opt{\oarg{options}}\opt{\marg{inline
+ data}}}
+ This command is used to specify data for the data visualization. It
+ can be used several times inside a single visualization and each
+ time the to-be-read data may have a different format, but the data
+ will be visualized as if it have been specified inside a single |data|
+ command.
+
+ The behaviour of the |data| command depends on
+ whether the \meta{inline data} is present. If it is not present, the
+ \meta{options} must be used to specify a source file from which the
+ data is read; if the \meta{inline data} is present no file will be
+ used, instead the data should directly reside inside the \TeX-file
+ and be given between the curly braces surrounding the \meta{inline
+ data}.
+
+ The \meta{options} are executed with the prefix |/pgf/data|. The
+ following options are always available:
+ \begin{key}{/pgf/data/source=\meta{filename} (initially \normalfont empty)}
+ If you set the |source| attribute to a non-empty \meta{filename},
+ the data will be read from this file. In this case, no
+ \meta{inline data} may be present, not even empty curly braces
+ should be provided.
+\begin{codeexample}[code only]
+\datavisualization ...
+ data [source=file1.csv]
+ data [source=file2.csv];
+\end{codeexample}
+ The other way round, if |source| is empty, the data must directly
+ follow as \meta{inline data}.
+\begin{codeexample}[code only]
+\datavisualization ...
+ data {
+ x, y
+ 1, 2
+ 2, 3
+ };
+\end{codeexample}
+ \end{key}
+ The second important key is |format|, which is used to specify the
+ data format:
+ \begin{key}{/pgf/data/format=\meta{format} (initially table)}
+ Use this key to locally set the format used for parsing the
+ data, see Section~\ref{section-dv-formats} for a list of
+ predefined formats.
+
+ The default format is the |table|-format, also known as
+ ``comma-separated values.'' The first line contains names of
+ attributes separated by commas, all following lines constitute a
+ data point where the attributes are given by the comma-separated
+ values in that line.
+ \end{key}
+
+ \medskip
+ \textbf{Presetting attributes.}
+ Normally, the inline data or the external data contains for each
+ data point the values of the different attributes. However,
+ sometimes you may also wish to set an attribute to a fixed value for
+ all data points of a data set. Suppose, for instance, that you have
+ to source files |experiment007.csv| and |experiment023.csv| and you
+ would like that for all data points of the first file the attribute
+ |/data point/experiment id| is set to 7 while for the data points of
+ the second file they are set to 23. In this case, you can specify
+ the desired settings using an absolute path inside the
+ \meta{options}. The effect will be local to the current |data|
+ command:
+\begin{codeexample}[code only]
+\datavisualization...
+ data [/data point/experiment=7, source=experiment007.csv]
+ data [/data point/experiment=23, source=experiment023.csv];
+\end{codeexample}
+
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \datavisualization [school book axes, visualize as line]
+ data [/data point/x=1] {
+ y
+ 1
+ 2
+ }
+ data [/data point/x=2] {
+ y
+ 2
+ 0.5
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+ \medskip
+ \textbf{Setting options for multiple |data| commands.}
+ You may wish to generally set the format once and for all. This can
+ be done by using the following key:
+ \begin{stylekey}{/tikz/every data}
+ This key is executed for every |data| command.
+ \end{stylekey}
+
+ Another way of passing options to multiple |data| commands is to use
+ the following facility: Whenever an option with the path
+ |/tikz/data visualization/data| is used, the path will be remapped
+ to |/pgf/data|. This means, in particular, that you can pass an
+ option like |data/format=table| to the |\datavisualization| command
+ to set the data format for all |data| commands of the data
+ visualization.
+
+ \medskip
+ \textbf{Parsing inline data.}
+ When you specify data inline, \TeX\ needs to read the data
+ ``line-by-line,'' while \TeX\ normally largely ignores end-of-line
+ characters. For this reason, the data visualization system
+ temporarily changes the meaning of the end-of-line character. This
+ is only possible if \TeX\ has not already processed the data in some
+ other way (namely as the parameter to some macro).
+
+ The bottom line is that you cannot use inline data when the whole
+ |\datavisualization| command is passed as a parameter to some
+ macro that is not setup to handle ``fragile'' code. For instance, in
+ a \textsc{beamer} |frame| you need to add the |fragile| option when
+ a data visualization contains inline data.
+
+ The problem does not arise when an external data |source| is
+ specified.
+\end{datavisualizationoperation}
+
+
+
+\begin{datavisualizationoperation}{scope}{\opt{\oarg{options}}\marg{data
+ specification}}
+ Scopes can be used to nest hierarchical data sets. The
+ \meta{options} will be executed with the path |/pgf/data| and will
+ only apply to the data sets specified inside the \meta{data
+ specification}, which may contain |data| or |scope| commands once more:
+\begin{codeexample}[code only]
+\datavisualization...
+ scope [/data point/experiment=7]
+ {
+ data [source=experiment007-part1.csv]
+ data [source=experiment007-part2.csv]
+ data [source=experiment007-part3.csv]
+ }
+ scope [/data point/experiment=23, format=foo]
+ {
+ data [source=experiment023-part1.foo]
+ data [source=experiment023-part2.foo]
+ };
+\end{codeexample}
+\end{datavisualizationoperation}
+
+
+\begin{datavisualizationoperation}{info}{\opt{\oarg{options}}\marg{code}}
+ This command will execute normal \tikzname\ \meta{code} at the end
+ of a data visualization. The \meta{options} are executed with the
+ normal path |/tikz/|.
+
+ The only difference between this command and just giving the
+ \meta{code} directly following the data visualization is that inside
+ the \meta{code} following an |info| command you still have access
+ to the coordinate system of the data visualization. In sharp
+ contrast, \tikzname\ code given after a data visualization can no
+ longer access this coordinate system.
+
+
+\begin{codeexample}[]
+\begin{tikzpicture}[baseline]
+ \datavisualization [ school book axes, visualize as line ]
+ data [format=function] {
+ var x : interval [-0.1*pi:2];
+ func y = sin(\value x r);
+ }
+ info {
+ \draw [red] (visualization cs: x={(.5*pi)}, y=1) circle (1pt)
+ node [above,font=\footnotesize] {extremal point};
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+ As can be seen, inside a data visualization a special coordinate
+ system is available:
+
+ \begin{coordinatesystem}{visualization}
+ As for other coordinate systems, the syntax is
+ \declare{|(visualization cs:|\meta{list
+ of attribute-value pairs}|)|}. The effect is the following:
+ For each pair \meta{attribute}|=|\meta{value} in the \meta{list}
+ the key |/data point/|\meta{attribute} is set to
+ \meta{value}. Then, it is computed where the resulting data point
+ ``would lie'' on the canvas (however, no data point is passed to
+ the visualizers).
+ \end{coordinatesystem}
+\end{datavisualizationoperation}
+
+In order to put information \emph{behind} the data visualization,
+you should usually use the |background| library and the background
+layer. However, it is also possible to execute code at other points
+during the data visualization process. Since this is potentially
+more disruptive, special keys documented in
+Section~\ref{section-dv-user-code} must be used.
+
+
+
+\subsection{Advanced: Executing User Code During a Data Visualization}
+\label{section-dv-user-code}
+
+The following keys can be passed to the |\datavisualization| command
+and allow you to execute some code at some special time during the
+data visualization process. For details of the process and on which
+signals are emitted when,
+see Section~\ref{section-dv-backend}.
+
+\begin{key}{/tikz/data visualization/before survey=\meta{code}}
+ The \meta{code} is passed to the |before survey| method of the data
+ visualization object and then executed at the appropriate time (see
+ Section~\ref{section-dv-backend} for details).
+
+ The following commands work likewise:
+\end{key}
+\begin{key}{/tikz/data visualization/at start survey=\meta{code}}
+\end{key}
+\begin{key}{/tikz/data visualization/at end survey=\meta{code}}
+\end{key}
+\begin{key}{/tikz/data visualization/after survey=\meta{code}}
+\end{key}
+\begin{key}{/tikz/data visualization/before visualization=\meta{code}}
+\end{key}
+\begin{key}{/tikz/data visualization/at start visualization=\meta{code}}
+\end{key}
+\begin{key}{/tikz/data visualization/at end visualization=\meta{code}}
+\end{key}
+\begin{key}{/tikz/data visualization/after visualization=\meta{code}}
+\end{key}
+
+
+
+\subsection{Advanced: Creating New Objects}
+
+You will need the following key only when you wish to create new
+rendering pipelines from scratch -- instead of modifying an existing
+pipeline as you would normally do. In the following it is assumed that
+you are familiar with the concepts of Section~\ref{section-dv-backend}.
+
+\begin{key}{/tikz/data visualization/new object=\meta{options}}
+ This key servers two purposes:
+ \begin{enumerate}
+ \item
+ This method makes it easy to create a new object as part of the
+ rendering pipeline, using \meta{options} to specify arguments rather
+ that directly calling |\pgfoonew|. Since you have the full power
+ of the keys mechanism at your disposal, it is easy, for instance,
+ to control whether or not parameters to the constructor are
+ expanded or not.
+ \item
+ The object is not created immediately, but only just before the
+ visualization starts. This allows you to specify that an object
+ must be created, but the parameter values of for its constructor
+ may depend on keys that are not yet set. A typical application is
+ the creating of an axis object: When you say |scientific axes|,
+ the |new object| command is used internally to create two
+ objects representing these axes. However, keys like
+ |x={length=5cm}| can only \emph{later} be used to specify the
+ parameters that need to be passed to the constructor of the
+ objects.
+ \end{enumerate}
+
+ The following keys may be used inside the \meta{options}:
+ \begin{key}{/tikz/data visualization/class=\meta{class name}}
+ The class of the to-be-created object.
+ \end{key}
+ \begin{key}{/tikz/data visualization/when=\meta{phase name}
+ (initially before survey)}
+ This key is used to specify when the object is to be created. As
+ described above, the object is not created immediately, but at
+ some time during the rendering process. You can specify any of the
+ phases defined by the data visualization object, see
+ Section~\ref{section-dv-backend} for details.
+ \end{key}
+ \begin{key}{/tikz/data visualization/store=\meta{key name}}
+ If the \meta{key name} is not empty, once the object has been
+ created, a handle to the object will be stored in \meta{key
+ name}. If a handle is already stored in \meta{key name}, the
+ object is not created twice.
+ \end{key}
+ \begin{key}{/tikz/data visualization/before creation=\meta{code}}
+ This code is executed right before the object is finally
+ created. It can be used to compute values that are then passed to
+ the constructor.
+ \end{key}
+ \begin{key}{/tikz/data visualization/after creation=\meta{code}}
+ This code is executed right after the object has just been
+ created. A handle to the just-created object is available in
+ |\tikzdvobj|.
+ \end{key}
+ \begin{key}{/tikz/data visualization/arg1=\meta{value}}
+ The value to be passed as the first parameter to the
+ constructor. Similarly, the keys |arg2| to |arg8| specify further
+ parameters passed. Naturally, only as many arguments are passed as
+ parameters are set. Here is an example:
+\begin{codeexample}[code only]
+\tikzdatavisualizationset{
+ new object={
+ class = example class,
+ arg1 = foo,
+ arg2 = \bar
+ }
+}
+\end{codeexample}
+ causes the following object creation code to be executed later on:
+\begin{codeexample}[code only]
+\pgfoonew \tikzdvobj=new example class(foo,\bar)
+\end{codeexample}
+ Note that you key mechanisms like |.expand once| to pass the value of
+ a macro instead of the macro itself:
+\begin{codeexample}[code only]
+\tikzdatavisualizationset{
+ new object={
+ class = example class,
+ arg1 = foo,
+ arg2/.expand once = \bar
+ }
+}
+\end{codeexample}
+ Now, if |\bar| is set to |This \emph{is} it.| at the moment to
+ object is created later on, the following object creation code is executed:
+\begin{codeexample}[code only]
+\pgfoonew \tikzdvobj=new example class(foo,This \emph{is} it)
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/tikz/data visualization/arg1 from key=\meta{key}}
+ Works like the |arg1|, only the value that is passed to the
+ constructor is the current value of the specified \meta{key} at
+ the moment when the object is created.
+\begin{codeexample}[code only]
+\tikzdatavisualizationset{
+ new object={
+ class = example class,
+ arg1 from key = /tikz/some key
+ }
+}
+\tikzset{some key/.initial=foobar}
+\end{codeexample}
+ causes the following to be executed:
+\begin{codeexample}[code only]
+\pgfoonew \tikzdvobj=new example class(foobar)
+\end{codeexample}
+ Naturally, the keys |arg2 from key| to |arg8 from key| are also
+ provided.
+ \end{key}
+
+ \begin{key}{/tikz/data visualization/arg1 handle from key=\meta{key}}
+ Works like the |arg1 from key|, only the key must store an object
+ and instead of the object a handle to the object is passed to the
+ constructor.
+ \end{key}
+\end{key}