diff options
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.tex | 156 |
1 files changed, 117 insertions, 39 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 2afb9568a2b..f7a6e54eb09 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 @@ -157,22 +157,43 @@ angle, radius \end{dataformat} -\begin{dataformat}{key value pairs} - Each line of the data is simply passed to the |\pgfkeys| command - with the path set to |/data point/|. This means that each data line - will typically consist of comma-separated assignments of the form - \meta{attribute}|=|\meta{value}. - \begin{codeexample}[] +\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|. +\begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes, visualize as line] - data [format=key value pairs] { + data [format=named] { x=0, y=0 x=1, y=1 x=2, y=1 x=3, y=0 }; \end{tikzpicture} - \end{codeexample} +\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: +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as scatter/.list={a,b,c}, + style sheet=cross marks] +data [format=named] { + x=0, y={1,2,3}, set=a + x={2,3,4}, y={3,4,5,7}, set=b + x=6, y={5,7,...,15}, set=c +}; +\end{codeexample} \end{dataformat} \begin{dataformat}{TeX code} @@ -196,6 +217,8 @@ angle, radius \end{dataformat} + + \subsection{Reference: Advanced Formats} \begin{tikzlibrary}{datavisualization.formats.functions} @@ -215,20 +238,25 @@ angle, radius 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 as follows: - \begin{quote} + variable declaration is one of the following: + \begin{enumerate} + \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}|]| - \opt{|samples |\meta{number}} \opt{|step |\meta{step}}|;| - \end{quote} - The |samples| and |step| options cannot be given both at the same - time. If both are missing, |samples| is used with the value stored - in the following key: + \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 a declaration like the above is the following: The - attribute named \meta{variable}, that is, the 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 @@ -237,6 +265,10 @@ angle, radius 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 @@ -268,28 +300,43 @@ angle, radius specification. In this case, all of these functions will be evaluated for each setting of input variables. - \begin{codeexample}[] -\begin{tikzpicture} +\begin{codeexample}[] +\tikz \datavisualization [school book axes, visualize as smooth line] data [format=function] { var x : interval [-1.5:1.5]; func y = \value x * \value x; }; -\end{tikzpicture} - \end{codeexample} - \begin{codeexample}[] -\begin{tikzpicture} - \datavisualization [school book axes, visualize as smooth line, - all axes={ticks={few},unit length=3mm}] - data [format=function] { - var t : interval [0:2*pi]; - - func x = \value t * cos(\value t r); - func y = \value t * sin(\value t r); - }; -\end{tikzpicture} - \end{codeexample} +\end{codeexample} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, + all axes={unit length=5mm, ticks={step=2}}, + visualize as smooth line] +data [format=function] { + var t : interval [0:2*pi]; + + func x = \value t * cos(\value t r); + func y = \value t * sin(\value t r); +}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes=clean, + y axis={ticks={style={ + /pgf/number format/fixed, + /pgf/number format/fixed zerofill, + /pgf/number format/precision=2}}}, + x axis={ticks={tick suffix=${}^\circ$}}, + visualize as smooth line/.list={1,2,3,4,5,6}, + style sheet=vary hue] +data [format=function] { + var set : {1,...,6}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); +}; +\end{codeexample} \end{dataformat} \end{tikzlibrary} @@ -331,16 +378,16 @@ Let us now have a look at how |\pgfdata| works. The first important option is \meta{source}, which governs which of these two alternatives applies: - \begin{key}{/pgf/data/source=\meta{filename} (initially \normalfont empty)} - If you set the |source| attribute to a non-empty \meta{filename}, + \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 |source| is empty, the data must directly - follow as \meta{inline data}. + 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,source=file1.csv] -\pgfdata[format=table,source=file2.csv] +\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: @@ -352,6 +399,10 @@ Let us now have a look at how |\pgfdata| works. } \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)} @@ -440,6 +491,33 @@ Let us now have a look at how |\pgfdata| works. \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} |