summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex620
1 files changed, 314 insertions, 306 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex
index 784e838baee..3923339a115 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex
@@ -13,50 +13,50 @@
\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:
+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.
+ \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}
@@ -64,14 +64,14 @@ time. This happens in different situations:
\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:
-
+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}[]
-% Define a data set:
+% Define a data set:
\tikz \datavisualization data group {example} = {
data {
x, y
@@ -82,54 +82,53 @@ data {
2, 0.5
}};
\tikz \datavisualization [school book axes, visualize as line] data group {example};
-\qquad
+\qquad
\tikz \datavisualization [school book axes, visualize as smooth line] data group {example};
-\qquad
+\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}.
+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.
+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.
-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|:
+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.)
+(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:
+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.
+ 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:
-
+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]
\tikz \datavisualization
[scientific axes=clean,
@@ -155,16 +154,16 @@ data {
};
\end{codeexample}
-As can be seen, the data points with the same |set| attribute
-do not need to be consecutive.
+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:
+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}.
+ Shorthand for |/data point/set=|\meta{name}.
+ %
\begin{codeexample}[width=7cm]
\tikz \datavisualization
[scientific axes=clean,
@@ -187,16 +186,16 @@ data [set=cos] {
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:
-
+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]
\tikz \datavisualization
[scientific axes=clean,
@@ -216,29 +215,27 @@ data [set=tan, format=function] {
\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:
+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{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/
+/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.
-
+ %
+ 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]
\tikz \datavisualization
[scientific axes=clean,
@@ -254,13 +251,13 @@ data [set=cos, format=function] {
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{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]
\tikz \datavisualization
[scientific axes=clean,
@@ -279,13 +276,12 @@ data [set=cos, format=function] {
};
\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}.
-
-
+ 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]
\tikz \datavisualization
[scientific axes={clean, end labels},
@@ -314,28 +310,27 @@ data [set=cos 2, format=function] {
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.
+\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:
+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.
-
+ This style is used with every visualizer. Note that it should contain
+ normal \tikzname\ keys.
+ %
\begin{codeexample}[width=7cm]
\tikz \datavisualization
[scientific axes=clean,
@@ -346,6 +341,7 @@ data [format=function] {
func y = sin(\value x r);
};
\end{codeexample}
+ %
\end{stylekey}
@@ -353,39 +349,39 @@ data [format=function] {
\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{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]
\tikz \datavisualization
- [scientific axes=clean,
+ [scientific axes=clean,
visualize as line=my data,
my data={style={mark=x, mark repeat=3}}]
data [format=function] {
@@ -393,26 +389,27 @@ data [format=function] {
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.
+ \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]
\tikz \datavisualization
[scientific axes=clean, x axis={grid={major at=(pi/2)}},
@@ -427,19 +424,17 @@ data [format=function] {
func y = tan(\value x r);
};
\end{codeexample}
- \end{key}
+ \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|.
+\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.
+ Causes the data points to be connected by straight lines.
+ %
\begin{codeexample}[]
\tikz [scale=.55] \datavisualization
[scientific axes=clean, all axes={ticks=few},
@@ -450,10 +445,12 @@ data [format=function] {
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.
+ Causes the data points to be connected by a polygon.
+ %
\begin{codeexample}[]
\tikz [scale=.55] \datavisualization
[scientific axes=clean, all axes={ticks=few},
@@ -464,15 +461,17 @@ data [format=function] {
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|.
+ 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:
+ Causes the data points to be connected by a line that is smoothed at the
+ joins:
+ %
\begin{codeexample}[]
\tikz [scale=.55] \datavisualization
[scientific axes=clean, all axes={ticks=few},
@@ -483,11 +482,13 @@ data [format=function] {
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:
+ Causes the data points to be connected by a circular line that is smoothed
+ at the joins:
+ %
\begin{codeexample}[]
\tikz [scale=.55] \datavisualization
[scientific axes=clean, all axes={ticks=few},
@@ -498,12 +499,14 @@ data [format=function] {
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}.
+ 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}[]
\tikz [scale=.55] \datavisualization
[scientific axes=clean, all axes={ticks=few},
@@ -514,10 +517,12 @@ data [format=function] {
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:
+ Like |gapped line|, only with a cycle:
+ %
\begin{codeexample}[]
\tikz [scale=.55] \datavisualization
[scientific axes=clean, all axes={ticks=few},
@@ -528,11 +533,13 @@ data [format=function] {
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.
+ Suppresses the line. This option only makes sense when the |mark| option is
+ used.
+ %
\begin{codeexample}[]
\tikz [scale=.55] \datavisualization
[scientific axes=clean, all axes={ticks=few},
@@ -543,122 +550,127 @@ data [format=function] {
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{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]
\tikz \datavisualization
- [scientific axes=clean,
+ [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{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:
+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.
+ \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.
+\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.
-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:
-
+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.
+ % visualizer and, if so, calls the macro \dovisualization to do the actual visualization.
\method visualize() {
\pgfdvfilterpassedtrue
\pgfdvnamedvisualizerfilter
@@ -669,9 +681,8 @@ down to a minimum:
}
\end{codeexample}
-The |\dovisualization| method must now do the correct
-visualization.
-
+The |\dovisualization| method must now do the correct visualization.
+%
\begin{codeexample}[code only]
\def\dovisualization{
\pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin}
@@ -682,7 +693,7 @@ visualization.
\end{codeexample}
Finally, we create a |visualize as| key:
-
+%
\begin{codeexample}[code only]
\tikzdatavisualizationset{
visualize as circle/.style={
@@ -704,25 +715,23 @@ Finally, we create a |visualize as| key:
Now, let's see how this works:
-
-\pgfooclass{circle visualizer}
-{
+\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.
+ % macro \dovisualization to do the actual visualization.
\method visualize() {
\pgfdvfilterpassedtrue
\pgfdvnamedvisualizerfilter
@@ -756,7 +765,6 @@ Now, let's see how this works:
visualize as circle/.default=circle
}
-
\begin{codeexample}[width=7cm]
\tikz \datavisualization [
scientific axes=clean,
@@ -780,5 +788,5 @@ data [set=c] {
x, y, radius
3, 2, 3pt
2.5, 0.5, 4pt
-};
+};
\end{codeexample}