summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex788
1 files changed, 405 insertions, 383 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex
index f7a6e54eb09..61504874373 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex
@@ -13,42 +13,40 @@
\subsection{Overview}
-The data visualization system needs a stream of data points as
-input. These data points can be directly generated by repeatedly
-calling the |\pgfdatapoint| command, but usually data is available in
-some special (text) format and one would like to visualize this
-data. The present section explains how data in some specific format
-can be fed to the data visualization system.
+The data visualization system needs a stream of data points as input. These
+data points can be directly generated by repeatedly calling the |\pgfdatapoint|
+command, but usually data is available in some special (text) format and one
+would like to visualize this data. The present section explains how data in
+some specific format can be fed to the data visualization system.
-This section starts with an explanation of the main concepts. Then,
-the standard formats are listed in the reference section. It is also
-possible to define new formats, but this an advanced concept which
-requires an understanding of some of the internals of the parsing mechanism,
-explained in Section~\ref{section-dv-parsing}, and the usage of a
-rather low-level command, explained in Section~\ref{section-dv-declaring-formats}.
+This section starts with an explanation of the main concepts. Then, the
+standard formats are listed in the reference section. It is also possible to
+define new formats, but this an advanced concept which requires an
+understanding of some of the internals of the parsing mechanism, explained in
+Section~\ref{section-dv-parsing}, and the usage of a rather low-level command,
+explained in Section~\ref{section-dv-declaring-formats}.
\subsection{Concepts}
For the purposes of this section, let call a \emph{data format} some
-standardized way of writing down a list of data points. A simple
-example of a data format is the \textsc{csv} format (the acronym
-stands for \emph{comma separated values}), where each line contains a
-data point, specified by values separated by commas. A different
-format is the \emph{key--value format}, where data points are
-specified by lists of key--value pairs. A far more complex format is
-the \textsc{pdb}-format used by the protein database to describe
+standardized way of writing down a list of data points. A simple example of a
+data format is the \textsc{csv} format (the acronym stands for \emph{comma
+separated values}), where each line contains a data point, specified by values
+separated by commas. A different format is the \emph{key--value format}, where
+data points are specified by lists of key--value pairs. A far more complex
+format is the \textsc{pdb}-format used by the protein database to describe
molecules.
-The data visualization system does not use any specific
-format. Instead, whenever data is read by the data visualization
-system, you must specify a format parser (or it is chosen
-automatically for you). It is the job of the parser to read (parse)
-the data lines and to turn them into data points, that is, to setup
-appropriate subkeys of |/data point/|.
+The data visualization system does not use any specific format. Instead,
+whenever data is read by the data visualization system, you must specify a
+format parser (or it is chosen automatically for you). It is the job of the
+parser to read (parse) the data lines and to turn them into data points, that
+is, to setup appropriate subkeys of |/data point/|.
To give a concrete example, suppose a file contains the following
lines:
+%
\begin{codeexample}[code only]
x, y, z
0, 0, 0
@@ -56,44 +54,43 @@ x, y, z
1, 1, 0.5
0, 1, 0.5
\end{codeexample}
-This file is in the \textsc{csv}-format. This format can be read by
-the |table| parser (which is called thus, rather than ``|csv|,'' since
-it can also read files in which the columns are separated by, say, a
-semicolon or a space). The |table| format will then read the data and
-for each line of the data, except for the headline of course, it will
-produce one data point. For instance, for the last data point the key
-|/data point/x| will be set to |0|, the key |/data point/y| will be
-set to |1|, and the key |/data point/z| will be set to |0.5|.
-
-All parsers are basically line-oriented. This means that, normally,
-each line in the input data should contain one data point. This rule
-may not always apply, for instance empty lines are typically ignored
-and sometimes a data point may span several lines, but deviating from
-this ``one data point per line'' rule makes parsers harder to
-program.
+%
+This file is in the \textsc{csv}-format. This format can be read by the |table|
+parser (which is called thus, rather than ``|csv|'', since it can also read
+files in which the columns are separated by, say, a semicolon or a space). The
+|table| format will then read the data and for each line of the data, except
+for the headline of course, it will produce one data point. For instance, for
+the last data point the key |/data point/x| will be set to |0|, the key
+|/data point/y| will be set to |1|, and the key |/data point/z| will be set to
+|0.5|.
+
+All parsers are basically line-oriented. This means that, normally, each line
+in the input data should contain one data point. This rule may not always
+apply, for instance empty lines are typically ignored and sometimes a data
+point may span several lines, but deviating from this ``one data point per
+line'' rule makes parsers harder to program.
\subsection{Reference: Build-In Formats}
-The following format is the default format, when no |format=...| is
-specified.
+The following format is the default format, when no |format=...| is specified.
\begin{dataformat}{table}
- This format is used to parse data that is formatted in the following
- manner: Basically, each line consists of \emph{values} that are
- separated by a \emph{separator} like a comma or a space. The values
- are stored in different \emph{attributes}, that is, subkeys of
- |/data point| like |/data point/x|. In order to decide which
- attribute is chosen for a give value, the headline is
- important. This is the first non-empty line of a table. It is
- formatted in the same way as normal data lines (value separated by
- the separator), but the meaning of the values is different: The
- first value in the headline is the name of the attribute where the
- first values in the following lines should go each time. Similarly,
- the second value in the headline is the name of the attribute for
- the second values in the following lines, and so on.
-
- A simple example is the following:
+ This format is used to parse data that is formatted in the following
+ manner: Basically, each line consists of \emph{values} that are separated
+ by a \emph{separator} like a comma or a space. The values are stored in
+ different \emph{attributes}, that is, subkeys of |/data point| like
+ |/data point/x|. In order to decide which attribute is chosen for a give
+ value, the headline is important. This is the first non-empty line of a
+ table. It is formatted in the same way as normal data lines (value
+ separated by the separator), but the meaning of the values is different:
+ The first value in the headline is the name of the attribute where the
+ first values in the following lines should go each time. Similarly, the
+ second value in the headline is the name of the attribute for the second
+ values in the following lines, and so on.
+
+ A simple example is the following:
+ %
\begin{codeexample}[code only]
angle, radius
0, 1
@@ -101,26 +98,29 @@ angle, radius
90, 3
135, 4
\end{codeexample}
- The headline states that the values in the first column should be
- stored in the |angle| attribute (|/data point/angle| to be precise)
- and that the values in the second column should be stored in the
- |radius| attribute. There are four data points in this data set.
-
- The format will tolerate too few or too many values in a line. If
- there are less values in a line than in the headline, the last
- attributes will simply be empty. If there are more values in a line
- than in the headline, the values are stored in attributes called
- |/data point/attribute |\meta{column number}, where the first value
- of a line gets \meta{column number} equal to |1| and so on.
-
- The |table| format can be configured using the following options:
- \begin{key}{/pgf/data/separator=\meta{character} (initially ,)}
- Use this key to change which character is used to separate values
- in the headline and in the data lines. To set the separator to a
- space, either set this key to an empty value or say
- |separator=\space|. Note that you must surround a comma by curly
- braces if you which to (re)set the separator character to a space.
- \begin{codeexample}[]
+ %
+ The headline states that the values in the first column should be stored in
+ the |angle| attribute (|/data point/angle| to be precise) and that the
+ values in the second column should be stored in the |radius| attribute.
+ There are four data points in this data set.
+
+ The format will tolerate too few or too many values in a line. If there are
+ less values in a line than in the headline, the last attributes will simply
+ be empty. If there are more values in a line than in the headline, the
+ values are stored in attributes called |/data point/attribute |\meta{column
+ number}, where the first value of a line gets \meta{column number} equal to
+ |1| and so on.
+
+ The |table| format can be configured using the following options:
+ %
+ \begin{key}{/pgf/data/separator=\meta{character} (initially ,)}
+ Use this key to change which character is used to separate values in
+ the headline and in the data lines. To set the separator to a space,
+ either set this key to an empty value or say |separator=\space|. Note
+ that you must surround a comma by curly braces if you which to (re)set
+ the separator character to a space.
+ %
+\begin{codeexample}[]
\begin{tikzpicture}
\datavisualization [school book axes, visualize as line]
data [separator=\space] {
@@ -136,13 +136,15 @@ angle, radius
2; 2; 0
};
\end{tikzpicture}
- \end{codeexample}
- \end{key}
- \begin{key}{/pgf/data/headline=\meta{headline}}
- When this key is set to a non-empty value, the value of
- \meta{headline} is used as the headline and the first line of the
- data is treated as a normal line rather than as a headline.
- \begin{codeexample}[]
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/data/headline=\meta{headline}}
+ When this key is set to a non-empty value, the value of \meta{headline}
+ is used as the headline and the first line of the data is treated as a
+ normal line rather than as a headline.
+ %
+\begin{codeexample}[]
\begin{tikzpicture}
\datavisualization [school book axes, visualize as line]
data [headline={x, y}] {
@@ -152,16 +154,16 @@ angle, radius
3, 0
};
\end{tikzpicture}
- \end{codeexample}
- \end{key}
+\end{codeexample}
+ \end{key}
\end{dataformat}
-
\begin{dataformat}{named}
- Basically, each line of the data must consist of a comma-separated
- sequence of attribute--values pairs like |x=5, lo=500|. This will
- cause the attribute |/data point/x| to be set to |5| and
- |/data point/lo| to be set to |500|.
+ Basically, each line of the data must consist of a comma-separated sequence
+ of attribute--values pairs like |x=5, lo=500|. This will cause the
+ attribute |/data point/x| to be set to |5| and |/data point/lo| to be set
+ to |500|.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\datavisualization [school book axes, visualize as line]
@@ -173,16 +175,17 @@ angle, radius
};
\end{tikzpicture}
\end{codeexample}
- However, instead of just specifying a single value for an attribute
- as in |x=5|, you may also specify a whole set of values as in
- |x={1,2,3}|. In this case, three data points will be created, one
- for each value in the list. Indeed, the |\foreach| statement is used
- to iterate over the list of values, so you can write things like
- |x={1,...,5}|.
-
- It is also permissible to specify lists of values for more than one
- attribute. In this case, a data point is created for each possible
- combination of values in the different lists:
+ %
+ However, instead of just specifying a single value for an attribute as in
+ |x=5|, you may also specify a whole set of values as in |x={1,2,3}|. In
+ this case, three data points will be created, one for each value in the
+ list. Indeed, the |\foreach| statement is used to iterate over the list of
+ values, so you can write things like |x={1,...,5}|.
+
+ It is also permissible to specify lists of values for more than one
+ attribute. In this case, a data point is created for each possible
+ combination of values in the different lists:
+ %
\begin{codeexample}[width=7cm]
\tikz \datavisualization
[scientific axes=clean,
@@ -194,15 +197,17 @@ data [format=named] {
x=6, y={5,7,...,15}, set=c
};
\end{codeexample}
+ %
\end{dataformat}
\begin{dataformat}{TeX code}
- This format will simply execute each line of the data, each of which
- should contain some normal TeX code. Note that at the end of each
- line control returns to the format handler, so for instance the
- arguments of a command may not be spread over several
- lines. However, not each line needs to produce a data point.
- \begin{codeexample}[]
+ This format will simply execute each line of the data, each of which should
+ contain some normal TeX code. Note that at the end of each line control
+ returns to the format handler, so for instance the arguments of a command
+ may not be spread over several lines. However, not each line needs to
+ produce a data point.
+ %
+\begin{codeexample}[]
\begin{tikzpicture}
\datavisualization [school book axes, visualize as line]
data [format=TeX code] {
@@ -213,93 +218,95 @@ data [format=named] {
\pgfkeyssetvalue{/data point/y}{0} \pgfdatapoint
};
\end{tikzpicture}
- \end{codeexample}
+\end{codeexample}
+ %
\end{dataformat}
-
-
\subsection{Reference: Advanced Formats}
\begin{tikzlibrary}{datavisualization.formats.functions}
- This library defines the formats described in the following, which
- allow you to specify the data points indirectly, namely via a
- to-be-evaluated function.
-
- \begin{dataformat}{function}
- This format allows you to specify a function that is then
- evaluated in order to create the desired data points. In other
- words, the data lines do not contain the data itself, but rather
- a functional description of the data.
-
- The format used to specify the function works as follows: Each
- nonempty line of the data should contain at least one of either a
- \emph{variable declaration} or a \emph{function declaration}. A
- variable declaration signals that a certain attribute will range
- over a given interval. The function declarations will then, later,
- be evaluated for values inside this interval. The syntax for a
- variable declaration is one of the following:
- \begin{enumerate}
- \item
- |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}|]|
- \opt{|samples |\meta{number}}|;|
- \item
- |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}%
- |] step |\meta{step}|;|
- \item
- |var |\declare{\meta{variable}}| : {|\meta{values}|};|
- \end{enumerate}
- In the first case, if the optional |samples| part is missing, the
- number of |samples| is taken from the value stored in the following key:
- \begin{key}{/pgf/data/samples=\meta{number} (initially 25)}
- Sets the number of samples to be used when no sample number is
- specified.
- \end{key}
- The meaning of declaring a variable declaration to range over an
- |interval| is that the attribute named \meta{variable}, that is, the key
- |/data point/|\meta{variable}, will range over the interval
- $[\meta{low},\meta{high}]$. If the number of |samples| is given
- (directly or indirectly), the interval is evenly divided into
- \meta{number} many points and the attribute is set to each of
- these values. Similarly, when a \meta{step} is specified, this
- stepping is used to increase \meta{low} iteratively up to the
- largest value that is still less or equal to \meta{high}.
-
- The meaning of declaring a variable using a list of \meta{values}
- is that the variable will simply iterate over the values using
- |\foreach|.
-
- You can specify more than one variable. In this case, each
- variable is varied independently of the other variables. For
- instance, if you declare an $x$-variable to range over the
- interval $[0,1]$ in $25$ steps and you also declare a $y$-variable
- to range over the same interval, you get a total of $625$ value
- pairs.
-
- The variable declarations specify which (input) variables will
- take which values. It is the job of the \emph{function
- declarations} to specify how some additional attributes are to
- be computed. The syntax of a function declaration is as follows:
- \begin{quote}
- |func |\declare{\meta{attribute}}| = |\meta{expression}|;|
- \end{quote}
- The meaning of such a declaration is the following: For each
- setting of the input variables (the variables specified using the
- |var| declaration), evaluate the \meta{expression} using the
- standard mathematical parser of \tikzname. The resulting value is
- then stored in |/data point/|\meta{attribute}.
-
- Inside \meta{expression} you can reference data point attributes
- using the following command, which is only defined inside such an
- expression:
- \begin{command}{\value\marg{variable}}
- This expands to the current value of the key |/data point/|\meta{variable}.
- \end{command}
-
- There can be multiple function declarations in a single data
- specification. In this case, all of these functions will be
- evaluated for each setting of input variables.
-
+ This library defines the formats described in the following, which allow
+ you to specify the data points indirectly, namely via a to-be-evaluated
+ function.
+
+ \begin{dataformat}{function}
+ This format allows you to specify a function that is then evaluated in
+ order to create the desired data points. In other words, the data lines
+ do not contain the data itself, but rather a functional description of
+ the data.
+
+ The format used to specify the function works as follows: Each nonempty
+ line of the data should contain at least one of either a \emph{variable
+ declaration} or a \emph{function declaration}. A variable declaration
+ signals that a certain attribute will range over a given interval. The
+ function declarations will then, later, be evaluated for values inside
+ this interval. The syntax for a variable declaration is one of the
+ following:
+ %
+ \begin{enumerate}
+ \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}|]|
+ \opt{|samples |\meta{number}}|;|
+ \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}%
+ |] step |\meta{step}|;|
+ \item |var |\declare{\meta{variable}}| : {|\meta{values}|};|
+ \end{enumerate}
+ %
+ In the first case, if the optional |samples| part is missing, the
+ number of |samples| is taken from the value stored in the following
+ key:
+ %
+ \begin{key}{/pgf/data/samples=\meta{number} (initially 25)}
+ Sets the number of samples to be used when no sample number is
+ specified.
+ \end{key}
+ %
+ The meaning of declaring a variable declaration to range over an
+ |interval| is that the attribute named \meta{variable}, that is, the
+ key |/data point/|\meta{variable}, will range over the interval
+ $[\meta{low},\meta{high}]$. If the number of |samples| is given
+ (directly or indirectly), the interval is evenly divided into
+ \meta{number} many points and the attribute is set to each of these
+ values. Similarly, when a \meta{step} is specified, this stepping is
+ used to increase \meta{low} iteratively up to the largest value that is
+ still less or equal to \meta{high}.
+
+ The meaning of declaring a variable using a list of \meta{values} is
+ that the variable will simply iterate over the values using |\foreach|.
+
+ You can specify more than one variable. In this case, each variable is
+ varied independently of the other variables. For instance, if you
+ declare an $x$-variable to range over the interval $[0,1]$ in $25$
+ steps and you also declare a $y$-variable to range over the same
+ interval, you get a total of $625$ value pairs.
+
+ The variable declarations specify which (input) variables will take
+ which values. It is the job of the \emph{function declarations} to
+ specify how some additional attributes are to be computed. The syntax
+ of a function declaration is as follows:
+ %
+ \begin{quote}
+ |func |\declare{\meta{attribute}}| = |\meta{expression}|;|
+ \end{quote}
+ %
+ The meaning of such a declaration is the following: For each setting of
+ the input variables (the variables specified using the |var|
+ declaration), evaluate the \meta{expression} using the standard
+ mathematical parser of \tikzname. The resulting value is then stored in
+ |/data point/|\meta{attribute}.
+
+ Inside \meta{expression} you can reference data point attributes using
+ the following command, which is only defined inside such an expression:
+ %
+ \begin{command}{\value\marg{variable}}
+ This expands to the current value of the key
+ |/data point/|\meta{variable}.
+ \end{command}
+
+ There can be multiple function declarations in a single data
+ specification. In this case, all of these functions will be evaluated
+ for each setting of input variables.
+ %
\begin{codeexample}[]
\tikz
\datavisualization [school book axes, visualize as smooth line]
@@ -309,6 +316,7 @@ data [format=named] {
func y = \value x * \value x;
};
\end{codeexample}
+ %
\begin{codeexample}[width=6cm]
\tikz \datavisualization [
school book axes,
@@ -321,6 +329,7 @@ data [format=function] {
func y = \value t * sin(\value t r);
};
\end{codeexample}
+ %
\begin{codeexample}[width=7cm]
\tikz \datavisualization [
scientific axes=clean,
@@ -337,58 +346,57 @@ data [format=function] {
func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
};
\end{codeexample}
- \end{dataformat}
-
+ \end{dataformat}
\end{tikzlibrary}
-
\subsection{Advanced: The Data Parsing Process}
-
\label{section-dv-parsing}
-Whenever data is fed to the data visualization system, it will be
-handled by the |\pgfdata| command, declared in the |datavisualization|
-module. The command is both used to parse data stored in external
-sources (that is, in external files or which is produced on the fly by
-calling an external command) as well as data given inline. A data
-format does not need to know whether data comes from a file or is
-given inline, the |\pgfdata| command will take care of this.
+Whenever data is fed to the data visualization system, it will be handled by
+the |\pgfdata| command, declared in the |datavisualization| module. The command
+is both used to parse data stored in external sources (that is, in external
+files or which is produced on the fly by calling an external command) as well
+as data given inline. A data format does not need to know whether data comes
+from a file or is given inline, the |\pgfdata| command will take care of this.
-Since \TeX\ will always read files in a line-wise fashion, data is
-always fed to data format parsers in such a fashion. Thus, even it
-would make more sense for a format to ignore line-breaks, the parser
-must still handle data given line-by-line.
+Since \TeX\ will always read files in a line-wise fashion, data is always fed
+to data format parsers in such a fashion. Thus, even it would make more sense
+for a format to ignore line-breaks, the parser must still handle data given
+line-by-line.
Let us now have a look at how |\pgfdata| works.
\begin{command}{\pgfdata\opt{\oarg{options}\marg{inline data}}}
- This command is used to feed data to the visualization
- pipeline. This command can only be used when a data visualization
- object has been properly setup, see
- Section~\ref{section-dv-main-setup}.
-
- \medskip
- \textbf{Basic options.}
- The |\pgfdata| command may be followed by \meta{options}, which are
- executed with the path |/pgf/data/|. Depending
- on these options, the \meta{options} may either be followed by
- \meta{inline data} or, alternatively, no \meta{inline data} is
- present and the data is read from an external source.
-
- The first important option is \meta{source}, which governs which of these
- two alternatives applies:
- \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)}
- If you set the |read from file| 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. If |read from file| is empty, the data must
- directly follow as \meta{inline data}.
+ This command is used to feed data to the visualization pipeline. This
+ command can only be used when a data visualization object has been properly
+ setup, see Section~\ref{section-dv-main-setup}.
+
+
+ \medskip
+ \textbf{Basic options.}
+ The |\pgfdata| command may be followed by \meta{options}, which are
+ executed with the path |/pgf/data/|. Depending on these options, the
+ \meta{options} may either be followed by \meta{inline data} or,
+ alternatively, no \meta{inline data} is present and the data is read from
+ an external source.
+
+ The first important option is \meta{source}, which governs which of these
+ two alternatives applies:
+ %
+ \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)}
+ If you set the |read from file| 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. If |read from file| is empty, the data must directly
+ follow as \meta{inline data}.
+ %
\begin{codeexample}[code only]
% Data is read from two external files:
\pgfdata[format=table, read from file=file1.csv]
\pgfdata[format=table, read from file=file2.csv]
\end{codeexample}
+ %
\begin{codeexample}[code only]
% Data is given inline:
\pgfdata[format=table]
@@ -398,171 +406,181 @@ Let us now have a look at how |\pgfdata| works.
2, 3
}
\end{codeexample}
- \end{key}
- \begin{key}{/pgf/data/inline}
- This is a shorthand file |read from file={}|. You can add this to
- make it clear(er) to the reader that data follows inline.
- \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. The \meta{format} must be a format that has been previously
- declared using the |\pgfdeclaredataformat| command. See the
- reference section for a list of the predefined formats.
- \end{key}
- In case all your data is in a certain format, you may wish to
- generally set the above key somewhere at the beginning of your
- file. Alternatively, you can use the following style to setup the
- |format| key and possibly further keys concerning the data format:
- \begin{stylekey}{/pgf/every data}
- This style is executed by |\pgfdata| before the \meta{options} are
- parsed.
-
- Note that the path of this key is just |/pgf/|, not
- |/pgf/data/|. Also note that \tikzname\ internally sets the value
- of this key up in such a way that the keys |/tikz/every data| and
- also |/tikz/data visualization/every data| are executed. The
- bottom line of this is that when using \tikzname, you should not
- set this key directly, set |/tikz/every data| instead.
- \end{stylekey}
-
- \medskip
- \textbf{Gathering of the data.}
- Once the data format and the source have been decided upon, the data
- is ``gathered.'' During this phase the data is not actually parsed
- in detail, but just gathered so that it can later be parsed during
- the visualization. There are two different ways in which the data is
- gathered:
- \begin{itemize}
- \item In case you have specified an external source, the data
- visualization object is told (by means of invoking the |add data|
- method) that it should (later) read data from the file specified
- by the |source| key using the format specified
- by the |format| key. The file is not read at this point, but only
- later during the actual visualization.
- \item Otherwise, namely when data is given inline, depending on
- which format is used, some catcodes get changed. This is necessary
- since \TeX's special characters are often not-so-special in a
- certain format.
-
- Independently of the format, the end-of-line character
- (carriage return) is made an active character.
-
- Finally, the \meta{inline data} is then read as a normal argument
- and the data visualization object is told that later on it should
- parse this data using the given format parser. Note that in this
- case the data visualization object must store the whole data
- internally.
- \end{itemize}
- In both cases the ``data visualization object'' is the object stored
- in the |/pgf/data visualization/obj| key.
-
- \medskip
- \textbf{Parsing of the data.}
- During the actual data visualization, all code that has been added
- to the data visualization object by means of the |add data| method
- is executed several times. It is the job of this code to call the
- |\pgfdatapoint| method for all data points present in the data.
-
- When the |\pgfdata| method calls |add data|, the code that is passed
- to the data visualization object is just a call to internal macros
- of |\pgfdata|, which are able to parse the data stored in an
- external file or in the inlined data. Independently of where the
- data is stored, these macros always do the following:
- \begin{enumerate}
- \item The catcodes are setup according to what the data
- format requires.
- \item Format-specific startup code gets called, which can initialize
- internal
- variables of the parsing process. (The catcode changes are not
- part of the startup code since in order to read inline data
- |\pgfdata| must be able to setup to temporarily setup the catcodes
- needed later on by the parsers, but since no reading is to be
- done, no startup code should be called at this point.)
- \item For each line of the data a format-specific code handler,
- which depends on the
- data format, is called. This handler gets the current line as
- input and should call |\pgfdatapoint| once for each data point
- that is encoded by this line (a line might define multiple data
- points or none at all). Empty lines are handled by special
- format-specific code.
- \item At the end, format-specific end code is executed.
- \end{enumerate}
- For an example of how this works, see the description of the
- |\pgfdeclaredataformat| command.
-
- \medskip
- \textbf{Data sets.}
- There are three options that allow you to create \emph{data
- sets}. Such a data set is essentially a macro that stores a
- pre-parsed set of data that can be used multiple times in subsequent
- visualizations (or even in the same visualization).
- \begin{key}{/pgf/data/new set=\meta{name}}
- Creates an empty data set called \meta{name}. If a data set of the
- same name already exists, it is overwritten and made empty. Data
- sets are global.
- \end{key}
- \begin{key}{/pgf/data/store in set=\meta{name}}
- When this key is set to any non-empty \meta{name} and if this
- \meta{name} has previously been used with the |new set| key, then
- the following happens: For the current |\pgfdata| command, all
- parsed data is not passed to the rendering pipeline. Instead, the
- parsed data is appended to the data set \meta{name}. This includes
- all options parsed to the |\pgfdata| command, which is why neither
- this key nor the previous key should be passed as options to a
- |\pgfdata| command.
- \end{key}
- \begin{key}{/pgf/data/use set=\meta{name}}
- This works similar to |read from file|. When this key is used with
- a |\pgfdata| command, no inline data may follow. Instead, the data
- stored in the data set \meta{name} is used.
- \end{key}
+ \end{key}
+ %
+ \begin{key}{/pgf/data/inline}
+ This is a shorthand file |read from file={}|. You can add this to make
+ it clear(er) to the reader that data follows inline.
+ \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. The
+ \meta{format} must be a format that has been previously declared using
+ the |\pgfdeclaredataformat| command. See the reference section for a
+ list of the predefined formats.
+ \end{key}
+ %
+ In case all your data is in a certain format, you may wish to generally set
+ the above key somewhere at the beginning of your file. Alternatively, you
+ can use the following style to setup the |format| key and possibly further
+ keys concerning the data format:
+ %
+ \begin{stylekey}{/pgf/every data}
+ This style is executed by |\pgfdata| before the \meta{options} are
+ parsed.
+
+ Note that the path of this key is just |/pgf/|, not |/pgf/data/|. Also
+ note that \tikzname\ internally sets the value of this key up in such a
+ way that the keys |/tikz/every data| and also
+ |/tikz/data visualization/every data| are executed. The bottom line of
+ this is that when using \tikzname, you should not set this key
+ directly, set |/tikz/every data| instead.
+ \end{stylekey}
+
+ \medskip
+ \textbf{Gathering of the data.}
+ Once the data format and the source have been decided upon, the data is
+ ``gathered''. During this phase the data is not actually parsed in detail,
+ but just gathered so that it can later be parsed during the visualization.
+ There are two different ways in which the data is gathered:
+ %
+ \begin{itemize}
+ \item In case you have specified an external source, the data
+ visualization object is told (by means of invoking the |add data|
+ method) that it should (later) read data from the file specified
+ by the |source| key using the format specified by the |format| key.
+ The file is not read at this point, but only later during the
+ actual visualization.
+ \item Otherwise, namely when data is given inline, depending on which
+ format is used, some catcodes get changed. This is necessary since
+ \TeX's special characters are often not-so-special in a certain
+ format.
+
+ Independently of the format, the end-of-line character (carriage
+ return) is made an active character.
+
+ Finally, the \meta{inline data} is then read as a normal argument
+ and the data visualization object is told that later on it should
+ parse this data using the given format parser. Note that in this
+ case the data visualization object must store the whole data
+ internally.
+ \end{itemize}
+ %
+ In both cases the ``data visualization object'' is the object stored
+ in the |/pgf/data visualization/obj| key.
+
+
+ \medskip
+ \textbf{Parsing of the data.}
+ During the actual data visualization, all code that has been added to the
+ data visualization object by means of the |add data| method is executed
+ several times. It is the job of this code to call the |\pgfdatapoint|
+ method for all data points present in the data.
+
+ When the |\pgfdata| method calls |add data|, the code that is passed to the
+ data visualization object is just a call to internal macros of |\pgfdata|,
+ which are able to parse the data stored in an external file or in the
+ inlined data. Independently of where the data is stored, these macros
+ always do the following:
+ %
+ \begin{enumerate}
+ \item The catcodes are setup according to what the data format
+ requires.
+ \item Format-specific startup code gets called, which can initialize
+ internal variables of the parsing process. (The catcode changes are
+ not part of the startup code since in order to read inline data
+ |\pgfdata| must be able to setup to temporarily setup the catcodes
+ needed later on by the parsers, but since no reading is to be done,
+ no startup code should be called at this point.)
+ \item For each line of the data a format-specific code handler, which
+ depends on the data format, is called. This handler gets the
+ current line as input and should call |\pgfdatapoint| once for each
+ data point that is encoded by this line (a line might define
+ multiple data points or none at all). Empty lines are handled by
+ special format-specific code.
+ \item At the end, format-specific end code is executed.
+ \end{enumerate}
+ %
+ For an example of how this works, see the description of the
+ |\pgfdeclaredataformat| command.
+
+
+ \medskip
+ \textbf{Data sets.}
+ There are three options that allow you to create \emph{data sets}. Such a
+ data set is essentially a macro that stores a pre-parsed set of data that
+ can be used multiple times in subsequent visualizations (or even in the
+ same visualization).
+ %
+ \begin{key}{/pgf/data/new set=\meta{name}}
+ Creates an empty data set called \meta{name}. If a data set of the same
+ name already exists, it is overwritten and made empty. Data sets are
+ global.
+ \end{key}
+ %
+ \begin{key}{/pgf/data/store in set=\meta{name}}
+ When this key is set to any non-empty \meta{name} and if this
+ \meta{name} has previously been used with the |new set| key, then the
+ following happens: For the current |\pgfdata| command, all parsed data
+ is not passed to the rendering pipeline. Instead, the parsed data is
+ appended to the data set \meta{name}. This includes all options parsed
+ to the |\pgfdata| command, which is why neither this key nor the
+ previous key should be passed as options to a |\pgfdata| command.
+ \end{key}
+ %
+ \begin{key}{/pgf/data/use set=\meta{name}}
+ This works similar to |read from file|. When this key is used with a
+ |\pgfdata| command, no inline data may follow. Instead, the data stored
+ in the data set \meta{name} is used.
+ \end{key}
\end{command}
\subsection{Advanced: Defining New Formats}
\label{section-dv-declaring-formats}
-In order to define a new data format you can use the following
-command, which is basic layer command defined in the module
-|datavisualization|:
+In order to define a new data format you can use the following command, which
+is basic layer command defined in the module |datavisualization|:
\begin{command}{\pgfdeclaredataformat\marg{format name}\marg{catcode
- code}\marg{startup code}\marg{line arguments}\\\marg{line
- code}\marg{empty line code}\marg{end code}}
- This command defines a new data format called \meta{format name},
- which can subsequently be used in the |\pgfdata| command. (The
- \tikzname's |data| maps directly to |\pgfdata|, so the following
- applies to \tikzname\ as well.)
-
- As explained in the description of the |\pgfdata| command, when data
- is being parsed that is formatted according to \meta{format name},
- the following happens:
- \begin{enumerate}
- \item The \meta{catcode code} is executed. This code should just
- contain catcode changes. The \meta{catcode code} will also be
- executed when inline data is read.
- \item Next, the \meta{startup code} is executed.
- \item Next, for each non-empty line of the data, the line is passed
- to a macro whose argument list is given by \meta{line
- arguments} and whose body is given by \meta{line code}. The idea
- is that you can use \TeX's powerful pattern matching capabilities
- to parse the non-empty lines. See also the below example.
- \item Empty lines are not processed by the \meta{line code}, but
- rather by the \meta{empty line code}. Typically, empty lines can
- simply be ignored and in this case you can let this parameter be
- empty.
- \item At the end of the data, the \meta{end code} is executed.
- \end{enumerate}
-
- As an example, let us now define a simple data format for reading
- files formatted in the following manner: Each line should contain a
- coordinate pair as in |(1.2,3.2)|, so two numbers separated by a
- comma and surrounded by parentheses. To make things more
- interesting, suppose that the hash mark symbol can be used to
- indicate comments. Here is an example of some data given in this
- format:
+ code}\marg{startup code}\marg{line arguments}\\\marg{line
+ code}\marg{empty line code}\marg{end code}%
+}
+ This command defines a new data format called \meta{format name}, which can
+ subsequently be used in the |\pgfdata| command. (The \tikzname's |data|
+ maps directly to |\pgfdata|, so the following applies to \tikzname\ as
+ well.)
+
+ As explained in the description of the |\pgfdata| command, when data is
+ being parsed that is formatted according to \meta{format name}, the
+ following happens:
+ %
+ \begin{enumerate}
+ \item The \meta{catcode code} is executed. This code should just
+ contain catcode changes. The \meta{catcode code} will also be
+ executed when inline data is read.
+ \item Next, the \meta{startup code} is executed.
+ \item Next, for each non-empty line of the data, the line is passed to
+ a macro whose argument list is given by \meta{line arguments} and
+ whose body is given by \meta{line code}. The idea is that you can
+ use \TeX's powerful pattern matching capabilities to parse the
+ non-empty lines. See also the below example.
+ \item Empty lines are not processed by the \meta{line code}, but rather
+ by the \meta{empty line code}. Typically, empty lines can simply be
+ ignored and in this case you can let this parameter be empty.
+ \item At the end of the data, the \meta{end code} is executed.
+ \end{enumerate}
+
+ As an example, let us now define a simple data format for reading files
+ formatted in the following manner: Each line should contain a coordinate
+ pair as in |(1.2,3.2)|, so two numbers separated by a comma and surrounded
+ by parentheses. To make things more interesting, suppose that the hash mark
+ symbol can be used to indicate comments. Here is an example of some data
+ given in this format:
+ %
\begin{codeexample}[code only]
# This is some data formatted according to the "coordinates" format
(0,0)
@@ -572,7 +590,8 @@ command, which is basic layer command defined in the module
(2,4)
\end{codeexample}
- A format parser for this format could be defined as follows:
+ A format parser for this format could be defined as follows:
+ %
\begin{codeexample}[code only]
\pgfdeclaredataformat{coordinates}
% First comes the catcode argument. We turn the hash mark into a comment character.
@@ -596,7 +615,9 @@ command, which is basic layer command defined in the module
% And we also have no end-of-line code.
{}
\end{codeexample}
-This format could now be used as follows:
+ %
+ This format could now be used as follows:
+ %
\begin{codeexample}[code only]
\begin{tikzpicture}
\datavisualization[school book axes, visualize as smooth line]
@@ -611,4 +632,5 @@ This format could now be used as follows:
};
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}