diff options
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.tex | 936 |
1 files changed, 469 insertions, 467 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 index 1efb972e439..26a97fa4e7f 100644 --- 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 @@ -14,72 +14,68 @@ \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: +The \todosp{why two labels? The first doesn't seem to be used.} 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. + 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. + \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''. +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. +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. +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}[] +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 { @@ -93,9 +89,9 @@ formats: 1.5, 2.25 }; \end{tikzpicture} - \end{codeexample} +\end{codeexample} - \begin{codeexample}[] +\begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes, visualize as smooth line] data [format=function] { @@ -103,88 +99,81 @@ formats: func y = \value x*\value x; }; \end{tikzpicture} - \end{codeexample} +\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. +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.}\label{section-dv-expressions} -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. +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. + \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 $100\,000$ 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. - - +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}[] +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, @@ -196,10 +185,9 @@ predefined styles take care of this for you: func y = \value x*\value x; }; \end{tikzpicture} - \end{codeexample} - +\end{codeexample} - \begin{codeexample}[] +\begin{codeexample}[] \begin{tikzpicture} \datavisualization [ scientific axes=clean, @@ -212,24 +200,23 @@ predefined styles take care of this for you: func y = \value x*\value x; }; \end{tikzpicture} - \end{codeexample} +\end{codeexample} -Section~\ref{section-dv-axes} explains in more detail how axes, ticks, -and grid lines can be chosen and configured. +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}[] +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 axes=clean, @@ -241,8 +228,9 @@ visualizers or pie chart visualizers. func y = \value x*\value x; }; \end{tikzpicture} - \end{codeexample} - \begin{codeexample}[] +\end{codeexample} +% +\begin{codeexample}[] \begin{tikzpicture} \datavisualization [ scientific axes=clean, @@ -254,41 +242,39 @@ visualizers or pie chart visualizers. func y = \value x*\value x; }; \end{tikzpicture} - \end{codeexample} +\end{codeexample} -Section~\ref{section-dv-visualizers} provides more information on -visualizers as well as reference lists. +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: - +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. + \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. - +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 axes=clean, @@ -315,87 +301,80 @@ coloring and the dashing is varied. \end{tikzpicture} \end{codeexample} -Section~\ref{section-dv-style-sheets} details style sheets and -legends. +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. +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/read from file=\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{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/read from file=\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 [read from file=file1.csv] data [read from file=file2.csv]; \end{codeexample} - The other way round, if |read from file| is empty, the data must directly - follow as \meta{inline data}. + % + The other way round, if |read from file| is empty, the data must + directly follow as \meta{inline data}. + % \begin{codeexample}[code only] \datavisualization ... data { @@ -404,34 +383,35 @@ visualizations. 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: + \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, read from file=experiment007.csv] @@ -453,58 +433,60 @@ visualizations. }; \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} + \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}{data point}{\opt{\oarg{options}}} - This command is used to specify data a single data point. The - \meta{options} are simply executed with the path |/data point| and - then a data point is created. This means that inside the - \meta{options} you just specify the values of all attributes in - key-value syntax. + This command is used to specify data a single data point. The + \meta{options} are simply executed with the path |/data point| and then a + data point is created. This means that inside the \meta{options} you just + specify the values of all attributes in key--value syntax. + % \begin{codeexample}[] \tikz \datavisualization [school book axes, visualize as line] data point [x=1, y=1] data point [x=1, y=2] data point [x=2, y=2] data point [x=2, y=0.5]; \end{codeexample} + % \end{datavisualizationoperation} \begin{key}{/tikz/data visualization/data point=\meta{options}} - This key is the ``key version'' of the previous command. The - difference is that this key can be used internally inside styles. + This key is the ``key version'' of the previous command. The difference is + that this key can be used internally inside styles. + % \begin{codeexample}[] \tikzdatavisualizationset{ horizontal/.style={ @@ -515,38 +497,44 @@ visualizations. horizontal=1, horizontal=2 ]; \end{codeexample} + % \end{key} \begin{datavisualizationoperation}{data group}{\opt{\oarg{options}}\marg{name}\opt{|+=|\marg{data specifications}}} - You can store a whole \meta{data specification} in a \emph{data - group}. This allows you to reuse data in multiple places without - having to write the data to an external file. - - The syntax of this command comes in the following three variants: - \begin{itemize} - \item |data group| \opt{\oarg{options}} \marg{name} |=| \marg{data specifications} - \item |data group| \opt{\oarg{options}} \marg{name} |+=| \marg{data specifications} - \item |data group| \opt{\oarg{options}} \marg{name} - \end{itemize} - In the first case, a new data group called \meta{name} is created (an - existing data group of the same name will be erased) and the following - \meta{data specifications} is stored in this data group. The data group - will not be fed to the rendering pipeline, but it is parsed at this - point as if it were. The defined data group is defined globally, so - you can used it in subsequent visualizations. The \meta{options} are - saved with the parsed \meta{data specifications}. - - In the second case, an already existing data group is extended by - adding the \meta{data specifications} to it. - - In the third case (detected by noting that the \meta{name} is - neither followed by an equal sign nor a plus sign), the contents of - the previously defined data group \meta{name} is inserted. The - \meta{options} are also executed. - - Let is now first create a data group. Note that nothing is drawn since - the ``dummy'' data visualization is empty and used only for the - definition of the data group. + You can store a whole \meta{data specification} in a \emph{data group}. + This allows you to reuse data in multiple places without having to write + the data to an external file. + + The syntax of this command comes in the following three variants: + % + \begin{itemize} + \item |data group| \opt{\oarg{options}} \marg{name} |=| \marg{data + specifications} + \item |data group| \opt{\oarg{options}} \marg{name} |+=| \marg{data + specifications} + \item |data group| \opt{\oarg{options}} \marg{name} + \end{itemize} + % + In the first case, a new data group called \meta{name} is created (an + existing data group of the same name will be erased) and the following + \meta{data specifications} is stored in this data group. The data group + will not be fed to the rendering pipeline, but it is parsed at this point + as if it were. The defined data group is defined globally, so you can used + it in subsequent visualizations. The \meta{options} are saved with the + parsed \meta{data specifications}. + + In the second case, an already existing data group is extended by adding + the \meta{data specifications} to it. + + In the third case (detected by noting that the \meta{name} is neither + followed by an equal sign nor a plus sign), the contents of the previously + defined data group \meta{name} is inserted. The \meta{options} are also + executed. + + Let is now first create a data group. Note that nothing is drawn since the + ``dummy'' data visualization is empty and used only for the definition of + the data group. + % \begin{codeexample}[] \tikz \datavisualization data group {points} = { data { @@ -561,21 +549,22 @@ visualizations. }; \end{codeexample} - We can now use this data in different plots: + We can now use this data in different plots: + % \begin{codeexample}[] \tikz \datavisualization [school book axes, visualize as line] data group {points}; \qquad \tikz \datavisualization [scientific axes=clean, visualize as line] data group {points}; \end{codeexample} + % \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{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] @@ -590,22 +579,20 @@ visualizations. data [read from file=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. - - + 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 ] @@ -620,26 +607,25 @@ visualizations. \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} + 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} \begin{datavisualizationoperation}{info'}{\opt{\oarg{options}}\marg{code}} - This command works like |info|, only the \meta{code} will be - executed just before the visualization is done. This allows you to - draw things \emph{behind} the visualization. - + This command works like |info|, only the \meta{code} will be executed just + before the visualization is done. This allows you to draw things + \emph{behind} the visualization. + % \begin{codeexample}[] \begin{tikzpicture}[baseline] \datavisualization [ school book axes, visualize as line ] @@ -652,120 +638,126 @@ visualizations. }; \end{tikzpicture} \end{codeexample} + % \end{datavisualizationoperation} -\label{section-dv-bounding-box} - +\label{section-dv-bounding-box}% \begin{predefinednode}{data visualization bounding box} - This rectangle node stores a bounding box of the data visualization - that is currently being constructed. This node can be useful inside - |info| commands or when labels need to be added. + This rectangle node stores a bounding box of the data visualization that is + currently being constructed. This node can be useful inside |info| commands + or when labels need to be added. \end{predefinednode} \begin{predefinednode}{data bounding box} - This rectangle node is similar to |data visualization bounding box|, - but it keeps track only of the actual data. The spaces needed for - grid lines, ticks, axis labels, tick labels, and other all other - information that is not part of the actual data is not part of this - box. + This rectangle node is similar to |data visualization bounding box|, but it + keeps track only of the actual data. The spaces needed for grid lines, + ticks, axis labels, tick labels, and other all other information that is + not part of the actual data is not part of this box. \end{predefinednode} + \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}. +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 \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: + 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}. +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 serves 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. + This key serves 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: + 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={ @@ -775,12 +767,16 @@ you are familiar with the concepts of Section~\ref{section-dv-backend}. } } \end{codeexample} - causes the following object creation code to be executed later on: + % + 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: + % + 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={ @@ -790,17 +786,20 @@ you are familiar with the concepts of Section~\ref{section-dv-backend}. } } \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: + % + 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} + \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{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={ @@ -810,17 +809,20 @@ you are familiar with the concepts of Section~\ref{section-dv-backend}. } \tikzset{some key/.initial=foobar} \end{codeexample} - causes the following to be executed: + % + 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} + % + 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} |