summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex448
1 files changed, 416 insertions, 32 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
index c4be25d48f4..1db93c31c52 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
@@ -26,6 +26,7 @@
\usepackage{colortbl}
\usepackage{booktabs}
\usepackage{eurosym}
+\usepackage{multirow}
\pgfqkeys{/codeexample}{%
every codeexample/.style={
@@ -143,10 +144,29 @@ Lines starting with `|%|' or `|#|' are considered to be comment lines and are ig
There is future support for a second header line which must start with `|$flags |' (the space is obligatory, even if the column separator is \emph{not} space!). Currently, such a line is ignored. It may be used to provide number formatting options like precision and number format.
-\begin{command}{\pgfplotstabletypeset\oarg{optional arguments}\marg{file name or \textbackslash macro}}
+\begin{command}{\pgfplotstabletypeset\oarg{optional arguments}\marg{file name {\normalfont or} \textbackslash macro {\normalfont or} inline table}}
Loads (or acquires) a table and typesets it using the current configuration of number formats and table options.
- In case the first argument is a file name, the table will be loaded from disk. Otherwise, it is assumed to be an already loaded table (see |\pgfplotstableread| or |\pgfplotstablenew|).
+ In case the first argument is a file name, the table will be loaded from disk. If it is an already loaded table (see |\pgfplotstableread| or |\pgfplotstablenew|), it will be used. Otherwise, if it is inline table data, this data will be parsed just as if it would have been found in a file (see |\pgfplotstableread|).
+{
+ % allow to typeset the example. I couldn't get the \catcodes
+ % correctly...
+ \pgfplotstableset{
+ /codeexample/newline=\noexpand\\,
+ row sep=\\,
+ }%
+\begin{codeexample}[]
+\pgfplotstabletypeset[sci zerofill]{
+ a b
+ 5000 1.234e5
+ 6000 1.631e5
+ 7000 2.1013e5
+ 9000 1000000
+}
+\end{codeexample}
+}%
+
+
\begin{codeexample}[]
\pgfplotstabletypeset{pgfplotstable.example1.dat}
\end{codeexample}
@@ -190,6 +210,26 @@ There is future support for a second header line which must start with `|$flags
\end{codeexample}
\noindent All of these options are explained in all detail in the following sections.
+You may also use a similar input format as for tabular environment:
+\begin{codeexample}[width=8cm]
+\pgfplotstabletypeset
+ [col sep=&,row sep=\\,sci zerofill]
+{
+ level & dof & error \\
+ 1 & 4 & 2.50000000e-01 \\
+ 2 & 16 & 6.25000000e-02 \\
+ 3 & 64 & 1.56250000e-02 \\
+ 4 & 256 & 3.90625000e-03 \\
+ 5 & 1024 & 9.76562500e-04 \\
+ 6 & 4096 & 2.44140625e-04 \\
+ 7 & 16384 & 6.10351562e-05 \\
+ 8 & 65536 & 1.52587891e-05 \\
+ 9 & 262144 & 3.81469727e-06 \\
+ 10 & 1048576 &9.53674316e-07 \\
+}
+\end{codeexample}
+
+
Technical note: every opened file will be protocolled into your log file.
\end{command}
@@ -198,22 +238,51 @@ Technical note: every opened file will be protocolled into your log file.
\end{command}
-\begin{command}{\pgfplotstableread\marg{file name}\marg{\textbackslash macro}}
- Loads the table \marg{file name} into a \TeX-macro \meta{\textbackslash macro}. This macro can then be used several times.
+\begin{commandlist}{%
+ \pgfplotstableread\marg{file name}\marg{\textbackslash macro},
+ \pgfplotstableread\marg{inline table}\marg{\textbackslash macro}}
+ Loads a table into the \TeX-macro \meta{\textbackslash macro}. This macro will store the table as internal structure and can be used several times.
\begin{codeexample}[]
\pgfplotstableread{pgfplotstable.example1.dat}\loadedtable
\pgfplotstabletypeset[columns={dof,error1}]\loadedtable
\hspace{2cm}
\pgfplotstabletypeset[columns={dof,error2}]\loadedtable
\end{codeexample}
- There are variants of this command which do not really built up a struct but which report every line to a ``listener''. There is also a struct which avoids protection by \TeX\ scopes. In case you need such things, consider reading the source code comments.
+ The first argument can be either a \meta{file name} as in the example here. It is also possible to provide the table data directly:
+\begin{codeexample}[code only]
+% Alternative: inline table data:
+\pgfplotstableread{
+level dof error1 error2 info grad(log(dof),log(error2)) quot(error1)
+1 4 2.50000000e-01 7.57858283e-01 48 0 0
+2 16 6.25000000e-02 5.00000000e-01 25 -3.00000000e-01 4
+3 64 1.56250000e-02 2.87174589e-01 41 -3.99999999e-01 4
+4 256 3.90625000e-03 1.43587294e-01 8 -5.00000003e-01 4
+5 1024 9.76562500e-04 4.41941738e-02 22 -8.49999999e-01 4
+6 4096 2.44140625e-04 1.69802322e-02 46 -6.90000001e-01 4
+7 16384 6.10351562e-05 8.20091159e-03 40 -5.24999999e-01 4
+8 65536 1.52587891e-05 3.90625000e-03 48 -5.35000000e-01 3.99999999e+00
+9 262144 3.81469727e-06 1.95312500e-03 33 -5.00000000e-01 4.00000001e+00
+10 1048576 9.53674316e-07 9.76562500e-04 2 -5.00000000e-01 4.00000001e+00
+}\loadedtable
+% can be used as above:
+\pgfplotstabletypeset[columns={dof,error1}]\loadedtable
+\hspace{2cm}
+\pgfplotstabletypeset[columns={dof,error2}]\loadedtable
+\end{codeexample}
+ It is checked automatically whether the first argument contains inline data or a file name.
-Technical note: every opened file will be protocolled into your log file.
+ The check whether the first argument is inline data or a file name works as follows: if |format=auto|, the first argument is considered to be a file name unless it contains the |row sep| character (see |row sep|). If |format=inline|, it is always considered to be inline data. If |format=file|, it is a file name.
- Note: avoid using `|\table|' as name, it conflicts with |\begin{table}| of \LaTeX.
-\end{command}
+ \paragraph{Special cases and more details:}
+ \begin{itemize}
+ \item The inline data format is ``fragile''. If you experience problems, terminate your tables with `|\\|' combined with |row sep=\\| (the docs for |row sep| contain alternative ways and more explanation).
+ \item There are variants of this command which do not really built up a struct but which report every line to a ``listener''. There is also a struct which avoids protection by \TeX\ scopes. In case you need such things, consider reading the source code comments.
+ \item Technical note: every opened file will be protocolled into your log file.
+ \item Note: avoid using `|\table|' as name, it conflicts with |\begin{table}| of \LaTeX.
+ \end{itemize}
+\end{commandlist}
-\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces} (initially space)}
+\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces,\&,ampersand} (initially space)}
Specifies the column separation character for table reading. The initial choice, |space| means ``at least one white space''. White spaces are tab stops or spaces (newlines always delimit lines).
For example, the file |pgfplotstable.example1.csv| uses commas as separation characters.
@@ -247,6 +316,14 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
The value |col sep=braces| is special since it actually uses two separation characters. Every single cell entry is delimited by an opening and a closing brace, \marg{entry}, for this choice. Furthermore, any white spaces (spaces and tabs) between cell entries are \emph{skipped} in case |braces| until the next \marg{entry} is found.
A further speciality of |col sep=braces| is that it has support for \emph{multi-line} cells: everything within balanced braces is considered to be part of a cell. This includes newlines\footnote{This treatment of newlines within balanced braces actually applies to every other column separator as well (it is a \TeX\ readline feature). In other words: you \emph{can} have multi line cells for every column separator if you enclose them in balanced curly braces. However, \texttt{col sep=braces} has the special treatment that end-of-line counts as white space character; for every other \texttt{col sep} value, this white space is suppressed to remove spurious spaces.}.
+
+ The |col sep=&| case (probably together with |row sep=\\|) allows to read tables as you'd usually type them in \LaTeX. This will automatically enable |trim cells|.
+\end{key}
+
+\begin{key}{/pgfplots/table/trim cells=\mchoice{true,false} (initially false)}
+ If enabled, leading and trailing white spaces will be removed while tables are read.
+
+ This might be necessary if you have |col sep|$\neq$|space| but your cells contain spaces. It will be activated automatically for |col sep=&|.
\end{key}
\begin{key}{/pgfplots/table/header=\mchoice{true,false,has colnames} (initially true)}
@@ -261,7 +338,67 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Finally, the choice \declaretext{has colnames} is the opposite of |false|: it assumes that the first non--comment line \emph{contains} column names. In other words: even if only numbers are contained in the first line, they are considered to be column \emph{names}.
\end{key}
-\subsection{Selecting Columns}
+\begin{pgfplotskey}{table/format=\mchoice{auto,inline,file} (initially auto)}
+ Configures the format expected as first argument for |\pgfplotstableread|\marg{input}.
+
+ The choice \declaretext{inline} expects the table data directly as argument where rows are separated by |row sep|. Inline data is ``fragile'', because \TeX\ may consume end--of--line characters (or |col sep| characters). See |row sep| for details.
+
+ The choice \declaretext{file} expects a file name.
+
+ The choice \declaretext{auto} searches for a |row sep| in the first argument supplied to |\pgfplotstableread|. If a |row sep| has been found, it is inline data, otherwise it is a file name.
+\end{pgfplotskey}
+\begin{pgfplotskey}{table/row sep=\mchoice{newline,\string\\} (initially newline)}
+ Configures the character to separate rows of the inline table data format (see |format=inline|).
+
+ The choice \declaretext{newline} uses the end of line as it appears in the table data (i.e.\ the input file or any inline table data).
+
+ The choice \declaretext{\string\\} uses `|\\|' to indicate the end of a row.
+
+ Note that \declaretext{newline} for inline table data is ``fragile'': you can't provide such data inside of \TeX\ macros (this does not apply to input files). Whenever you experience problems, proceed as follows:
+ \begin{enumerate}
+ \item First possibility: call |\pgfplotstableread|\marg{data}|\yourmacro| \emph{outside} of any macro declaration.
+ \item Use |row sep=\\|.
+ \end{enumerate}
+ The same applies if you experience problems with inline data and special |col sep| choices (like |col sep=tab|).
+
+ The reasons for such problems is that \TeX\ scans the macro bodies and replaces newlines by white spaces. It does other substitutions of this sort as well, and these substitutions can't be undone (maybe not even found).
+\end{pgfplotskey}
+
+\begin{key}{/pgfplots/table/ignore chars=\marg{comma-separated-list} (initially empty)}
+ Allows to define an ``ignore list'' for single characters. Any characters found in an input file which occur also in \meta{comma-separated-list} will silently by thrown away. The processing is exactly the same as if you did not write them at all in the first place.
+
+ For example, suppose we are given |pgfplotstable.example5.dat| with
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{pgfplotstable.example5.dat}
+
+ \noindent then, we can ignore several of the characters by writing
+\begin{codeexample}[]
+\pgfplotstabletypeset
+ [col sep=comma,ignore chars={(,),\ ,\#}]
+ {pgfplotstable.example5.dat}
+\end{codeexample}
+
+ The \meta{comma-separated-list} should contain exactly one character in each list element, and the single characters should be separated by commas. Some special characters like commas, white spaces, hashes, percents or backslashes need to be escaped by prefixing them with a backslash.
+
+ Besides normal characters, it is also supported to eliminate any binary code from your input files. For example, suppose you have binary characters of code |0x01| (hex notation) in your files. Then, use
+\begin{codeexample}[code only]
+\pgfplotstableset{ignore chars={\^^01}}
+\end{codeexample}
+ \noindent to eliminate them silently. The |^^|\meta{digit}\meta{digit} notation is a \TeX\ feature to provide characters in hexadecimal encoding where \meta{digit} is one of |0123456789abcdef|. I don't know if the backslash in |\^^01| is always necessary, try it out. There is also a character based syntax, in which |\^^M| is \meta{newline} and |\^^I| is \meta{tab}. Refer to~\cite{texbook} for more details.
+
+ Note that after stripping all these characters, the input table must be valid -- it should still contain column separators and balanced columns.
+
+ This setting applies to |\addplot table| and |\addplot file| for \PGFPlots\ as well.
+
+ Note that |ignore chars| is ``fragile'' when it is applied to |format=inline| or |format=auto|. Consider |format=file| if you experience problems\footnote{See also |row\ sep| for more information about dealing with fragile inline tables formats.}.
+\end{key}
+
+\begin{key}{/pgfplots/table/white space chars=\marg{comma-separated-list} (initially empty)}
+ Allows to define a list of single characters which are actually treated like white spaces (in addition to tabs and spaces). It might be useful in order to get more than one column separator character.
+
+ The |white space chars| list is used in exactly the same way as |ignore chars|, and the same remarks as above apply as well.
+\end{key}
+
+\subsection{Selecting Columns and their Appearance Styles}
\begin{key}{/pgfplots/table/columns=\marg{comma-separated-list}}
Selects particular columns the table. If this option is empty (has not been provided), all available columns will be selected.
@@ -275,7 +412,23 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
\begin{pgfplotstablealiaskey}
Assigns the new name \meta{col name} for the column denoted by \meta{real col name}. Afterwards, accessing \meta{col name} will use the data associated with column \meta{real col name}.
-
+\begin{codeexample}[]
+% in preamble:
+\pgfplotstableset{
+ alias/newname/.initial=b,
+}%
+%
+% in document:
+\pgfplotstabletypeset[
+ row sep=\\,
+ columns={a,newname},% access to `newname' is the same as to `b'
+]{
+ a b\\
+ 1 2\\
+ 3 4\\
+ 5 6\\
+}%
+\end{codeexample}
You can use |columns/|\meta{col name}|/.style| to assign styles for the alias, not for the original column name.
If there exists both an alias and a column of the same name, the column name will be preferred. Furthermore, if there exists a |create on use| statement with the same name, this one will also be preferred.
@@ -482,6 +635,27 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
A style which can be used together with the |dcolumn| package of David Carlisle. It also enables alignment at the decimal separator. However, the decimal separator needs to be exactly one character which is incompatible with `|{,}|' (the default setting for |use comma|).
\end{stylekey}
+\begin{pgfplotskey}{table/sort=\marg{true,false} (initially false)}
+ If set to |true|, |\pgfplotstabletypeset| will sort the table before applying its operation.
+
+ See the description of |\pgfplotstablesort| for how to configure |sort key| and |sort cmp|.
+
+\begin{codeexample}[]
+\pgfplotstabletypeset[
+ sort,sort key=error2,
+ columns={dof,error1,error2},
+ columns/error1/.style={sci,sci subscript,sci zerofill,dec sep align},
+ columns/error2/.style={sci,sci subscript,sci zerofill,dec sep align},
+]
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+
+ The |sort| mechanism is applied before the actual typesetting routine starts, i.e.\ it has the same effect as if you'd call |\pgfplotstablesort| manually before typesetting the table (however, the |sort| key has the advantage of respective the |include outfiles| caching mechanism). Any |create on use| specifications are resolved before calling the |sort key|.
+
+
+ %The |sort| key applies also to |\addplot table[sort,read completely]|.
+\end{pgfplotskey}
+
\begin{stylekey}{/pgfplots/table/every first column}
A style which is installed for every first column only.
\begin{codeexample}[narrow]
@@ -579,7 +753,7 @@ A style which is installed for every column with odd column index (starting with
\end{command}
-\subsection{Configuring Row Appearance}
+\subsection{Configuring Row Appearance: Styles}
The following styles allow to configure the final table code \emph{after any cell contents have been assigned}.
\begin{key}{/pgfplots/table/before row=\marg{\TeX\ code}}
@@ -671,8 +845,9 @@ The following styles allow to configure the final table code \emph{after any cel
\end{stylekey}
\subsection{Customizing and Getting the Tabular Code}
+The following keys allow changes of alignment (|begin table|) and |font| and they allow to write the generated code to |outfile|s (see also |write to macro|). Furthermore, the generated code can be fine--tuned to provide other sorts of table output, beyond \LaTeX.
\begin{stylekey}{/pgfplots/table/every table=\marg{file name}}
- A style which is installed at the beginning of every |\pgfplotstabletypeset| command.
+ A style which is installed at the beginning of every |\pgfplotstabletypeset| command\footnote{The \texttt{every table} style is installed \emph{after} options provided to \texttt{\textbackslash pgfplotstabletypeset}; it has higher precedence.}.
The table file name is given as first argument.
\end{stylekey}
@@ -776,7 +951,7 @@ The command |\pgfutilensuremath| checks whether math mode is active and switches
The comment sign which is inserted into outfiles to suppress trailing white spaces.
\end{key}
-\noindent As last example, we use \PGFPlotstable\ to write an |.html| (without number formatting, however):
+\noindent As last example, we use \PGFPlotstable\ to write an |.html| file (including number formatting and rounding!):
% \usepackage{listings}
\begin{codeexample}[width=8cm]
\pgfplotstabletypeset[
@@ -785,9 +960,10 @@ The command |\pgfutilensuremath| checks whether math mode is active and switches
/pgfplots/table/@cell content={<td>#1</td>}
},
before row=<tr>,after row=</tr>,
- skip coltypes, typeset=false, string type,
+ skip coltypes, typeset=false,
+ verbatim,% configures number printer
TeX comment=,
- columns={level,dof},
+ columns={level,dof,error1},
outfile=pgfplotstable.example1.out.html,
]{pgfplotstable.example1.dat}
\lstinputlisting
@@ -907,7 +1083,7 @@ See section~\ref{sec:number:styles} for how to change the appearance.
\end{key}
\begin{key}{/pgf/number format/sci}
-Configures |\pgfmathprintnumber| to display numbers in scientific format, that means sign, mantisse and exponent (basis~$10$). The mantisse is rounded to the desired precision.
+Configures |\pgfmathprintnumber| to display numbers in scientific format, that means sign, mantisse and exponent (basis~$10$). The mantisse is rounded to the desired |precision| (or |sci precision|, see below).
\begin{codeexample}[]
\pgfkeys{/pgf/number format/.cd,sci,precision=2}
@@ -996,6 +1172,62 @@ Truncates every number to integers (discards any digit after the period).
\end{codeexample}
\end{key}
+\begin{key}{/pgf/number format/frac}
+Displays numbers as fractionals.
+
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/frac}
+\pgfmathprintnumber{0.333333333333333}\hspace{1em}
+\pgfmathprintnumber{0.5}\hspace{1em}
+\pgfmathprintnumber{2.133333333333325e-01}\hspace{1em}
+\pgfmathprintnumber{0.12}\hspace{1em}
+\pgfmathprintnumber{2.666666666666646e-02}\hspace{1em}
+\pgfmathprintnumber{-1.333333333333334e-02}\hspace{1em}
+\pgfmathprintnumber{7.200000000000000e-01}\hspace{1em}
+\pgfmathprintnumber{6.666666666666667e-02}\hspace{1em}
+\pgfmathprintnumber{1.333333333333333e-01}\hspace{1em}
+\pgfmathprintnumber{-1.333333333333333e-02}\hspace{1em}
+\pgfmathprintnumber{3.3333333}\hspace{1em}
+\pgfmathprintnumber{1.2345}\hspace{1em}
+\pgfmathprintnumber{1}\hspace{1em}
+\pgfmathprintnumber{-6}
+\end{codeexample}
+
+\begin{key}{/pgf/number format/frac TeX=\marg{\textbackslash macro} (initially \texttt{\textbackslash frac})}
+ Allows to use a different implementation for |\frac| inside of the |frac| display type.
+\end{key}
+\begin{key}{/pgf/number format/frac denom=\meta{int} (initially empty)}
+ Allows to provide a custom denominator for |frac|.
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/.cd,frac, frac denom=10}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{0.5}\hspace{1em}
+\pgfmathprintnumber{1.2}\hspace{1em}
+\pgfmathprintnumber{-0.6}\hspace{1em}
+\pgfmathprintnumber{-1.4}\hspace{1em}
+\end{codeexample}
+\end{key}
+\begin{key}{/pgf/number format/frac whole=\mchoice{true,false} (initially true)}
+ Configures whether complete integer parts shall be placed in front of the fractional part. In this case, the fractional part will be less then $1$. Use |frac whole=false| to avoid whole number parts.
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/.cd,frac, frac whole=false}
+\pgfmathprintnumber{20.1}\hspace{1em}
+\pgfmathprintnumber{5.5}\hspace{1em}
+\pgfmathprintnumber{1.2}\hspace{1em}
+\pgfmathprintnumber{-5.6}\hspace{1em}
+\pgfmathprintnumber{-1.4}\hspace{1em}
+\end{codeexample}
+\end{key}
+\begin{key}{/pgf/number format/frac shift=\marg{integer} (initially 4)}
+ In case you experience problems because of stability problems, try experimenting with a different |frac shift|.
+ Higher shift values $k$ yield higher sensitivity to inaccurate data or inaccurate arithmetics.
+
+ Technically, the following happens. If $r < 1$ is the fractional part of the mantissa, then a scale $i = 1/r \cdot 10^k$ is computed where $k$ is the shift; fractional parts of $i$ are neglected. The value $1/r$ is computed internally, its error is amplified.
+
+ If you still experience stability problems, use |\usepackage{fp}| in your preamble. The |frac| style will then automatically employ the higher absolute precision of |fp| for the computation of $1/r$.
+\end{key}
+\end{key}
+
\begin{key}{/pgf/number format/precision=\marg{number}}
Sets the desired rounding precision for any display operation. For scientific format, this affects the mantisse.
\end{key}
@@ -1273,7 +1505,7 @@ Allows to define an own number style for the scientific format. Here, \meta{keys
-\section{Fine Tuning of Loaded Data}
+\section{From Input Data To Output Tables: Data Processing}
The conversion from an unprocessed input table to a final typesetted |tabular| code uses four stages for every cell,
\begin{enumerate}
\item Loading the table,
@@ -1293,6 +1525,38 @@ Typesetting cells means to take their value and ``do something''. In many cases,
Allows to redefine the algorithm which assigns cell contents. The argument |#1| is the (unformatted) contents of the input table.
The resulting output needs to be written to |/pgfplots/table/@cell content|.
+% \usepackage{booktabs}
+% \usepackage{multirow}
+\begin{codeexample}[]
+% An example how to use
+% \usepackage{multirow} and
+% \usepackage{booktabs}:
+\pgfplotstabletypeset[
+ columns/Z/.style={
+ column name={},
+ assign cell content/.code={% use \multirow for Z column:
+ \ifnum\pgfplotstablerow=0
+ \pgfkeyssetvalue{/pgfplots/table/@cell content}
+ {\multirow{4}{*}{##1}}%
+ \else
+ \pgfkeyssetvalue{/pgfplots/table/@cell content}{}%
+ \fi
+ },
+ },
+ % use \booktabs as well (compare examples above):
+ every head row/.style={before row=\toprule,after row=\midrule},
+ every last row/.style={after row=\bottomrule},
+ row sep=\\,col sep=&,
+]{% here: inline data in tabular format:
+ Z & a & b \\
+ data & 1 & 2 \\
+ & 3 & 4 \\
+ & 5 & 6 \\
+ & 7 & 8 \\
+}
+\end{codeexample}
+\index{multirow}%
+\noindent The example above uses |\usepackage{multirow}| to format column |Z|. More precisely, it uses |\multirow{4}{*}{data}| for row \#0 of column |Z| and the empty string for any other row in column |Z|.
Please note that you may need special attention for |#1=|\marg{}, i.e. the empty string. This may happen if a column has less rows than the first column. \PGFPlotstable\ will balance columns automatically in this case, inserting enough empty cells to match the number of rows of the first column.
@@ -1301,16 +1565,26 @@ Typesetting cells means to take their value and ``do something''. In many cases,
This key is evaluated inside of a local \TeX\ group, so any local macro assignments will be cleared afterwards.
\end{codekey}
-\begin{key}{/pgfplots/table/assign cell content as number}
- This here is the default implementation of |assign cell content|.
-
+\begin{stylekey}{/pgfplots/table/numeric type}
+ A style which (re)-defines |assign cell content| back to its original value which assumes numerical data.
+
It invokes |\pgfmathprintnumberto| and writes the result into |@cell content|.
-\end{key}
+\end{stylekey}
\begin{stylekey}{/pgfplots/table/string type}
A style which redefines |assign cell content| to simply return the ``raw'' input data, that means as text column. This assumes input tables with valid \LaTeX\ content (verbatim printing is not supported).
\end{stylekey}
+\begin{stylekey}{/pgfplots/table/verb string type}
+ A style which redefines |assign cell content| to return the ``raw'' as--is. Thus, it is quite similar to |string type| -- but it will return control sequences and (many, not all) special characters without expanding them.
+
+ You may need to combine |verb string type| with |special chars|.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/numeric as string type}
+ A style which redefines |assign cell content| such that it assumes numerical input data. It returns a string literal describing the input number either as integer or in scientific (exponential) notation. In contrast to |numeric type|, it does not apply number formatting.
+\end{stylekey}
+
\begin{stylekey}{/pgfplots/table/date type=\marg{date format}}% (initially \year-\month-\day)}
A style which expects ISO dates of the form |YYYY-MM-DD| in each cell and produces pretty-printed strings on output. The output format is given as \marg{date format}. Inside of \marg{date format}, several macros which are explained below can be used.
% \usepackage{pgfcalendar}
@@ -1343,7 +1617,6 @@ Typesetting cells means to take their value and ``do something''. In many cases,
\begin{codeexample}[code only]
\usepackage{pgfcalendar}
\end{codeexample}
-\end{stylekey}
\begin{command}{\year}
Inside of \marg{date format}, this macro expands to the year as number (like |2008|).
@@ -1373,8 +1646,10 @@ Typesetting cells means to take their value and ``do something''. In many cases,
Inside of \marg{date format}, this macro expands to the weekday's short name in the current language (like |Wed|).
See below for how to change the language.
\end{command}
+
\subsubsection*{Changing the language for dates}
The date feature is implemented using the \PGF\ calendar module. This module employs the package |translator| (if it is loaded). I don't have more detail yet, sorry. Please refer to \cite{tikz} for more details.
+\end{stylekey}
\subsection{Preprocessing Cell Content}
\label{sec:pgfplotstable:preproc}
@@ -1796,6 +2071,7 @@ The following macros are useful during cell assignments:
\item |\pgfplotstablerow| and |\pgfplotstablerows| which contain the current row's index and the total number of rows, respectively. See page~\pageref{pgfplotstable:page:tablerow} for details.
\item \declareandlabel{\pgfmathaccuma} and \declareandlabel{\pgfmathaccumb} can be used to transport intermediate results.
Both maintain their value from one column assignment to the next. All other local variables will be deleted after leaving the assignment routines. The initial value is the empty string for both of them unless they are already initialised by column creation styles.
+ \item \declareandlabel{\pgfplotstablename} a macro containing the name of the currently processed table (i.e.\ it contains the second argument of |\pgfplotstablecreatecol|).
\item commands which are valid throughout every part of this package, for example |\pgfplotstablerow| to get the current row index or |\pgfplotstablerows| to get the total number of rows.
\end{enumerate}
The \marg{col name} is expected to be a \emph{physical} column name, no alias or column index is allowed (unless column indices and column names are the same).
@@ -2080,6 +2356,37 @@ The example creates two columns: the |new| column is just the sum of each value
This style employs methods of the floating point unit, that means it works with a relative precision of about $10^{-6}$ ($6$ significant digits in the mantisse).
\end{keylist}
+\begin{stylekey}{/pgfplots/table/create col/linear regression=\marg{key-value-config}}%
+ Computes a linear (least squares) regression $y(x) = a \cdot x + b$ using the sample data $(x_i,y_i)$ which has to be specified inside of \meta{key-value-config}.
+
+\begin{codeexample}[pre={\vbox\bgroup\hsize=3cm},post=\egroup]
+% load table from somewhere:
+\pgfplotstableread[row sep=\\]{
+ x y\\
+ 1 1 \\
+ 2 4\\
+ 3 9\\
+ 4 16\\
+ 5 25\\
+ 6 36\\
+}\loadedtbl
+
+% create the `regression' column:
+\pgfplotstablecreatecol[linear regression]
+ {regression}
+ {\loadedtbl}
+% store slope
+\xdef\slope{\pgfplotstableregressiona}
+
+\pgfplotstabletypeset\loadedtbl\\
+
+The slope is `\slope'.
+\end{codeexample}
+ \noindent The example above loads a table from inline data, appends a column named `|regression|' and typesets it. Since no \meta{key-value-config} has been provided, |x=[index]0| and |y=[index]1| will be used. The |\xdef\slope{...}| command stores the `$a$' value of the regression line into a newly defined macro `|\slope|'\footnote{The \texttt{\textbackslash xdef} means ``global expanded definition'': it expands the argument until it can't be expanded any further and assigns a (global) name to the result. See any \TeX\ book for details.}.
+
+ The complete documentation for this feature has been moved to \PGFPlots\ due to its close relation to plotting. Please refer to the \PGFPlots\ manual coming with this package.
+\end{stylekey}
+
\begin{stylekey}{/pgfplots/table/create col/function graph cut y=\marg{cut value}\marg{common options}\marg{one key-value set for each plot}}
A specialized style for use in |create on use| statements which computes cuts of (one or more) discrete plots $y(x_1), \dotsc, y(x_N)$ with a fixed \marg{cut value}. The $x_i$ are written into the table's cells.
@@ -2089,10 +2396,10 @@ The example creates two columns: the |new| column is just the sum of each value
\begin{codeexample}[]
\pgfplotstablenew[
create on use/cut/.style={create col/function graph cut y=
- {2.5e-4}% search for fixed L2 = 2.5e-4
- {x=Basis,y=L2,ymode=log,xmode=log}% double log, each function is L2(Basis)
-% now, provide each single function f_i(Basis):
-{{table=plotdata/newexperiment1.dat},{table=plotdata/newexperiment2.dat}}
+ {2.5e-4} % search for fixed L2 = 2.5e-4
+ {x=Basis,y=L2,ymode=log,xmode=log} % double log, each function is L2(Basis)
+ % now, provide each single function f_i(Basis):
+ {{table=plotdata/newexperiment1.dat},{table=plotdata/newexperiment2.dat}}
},
columns={cut}]
{2}
@@ -2166,7 +2473,9 @@ The example creates two columns: the |new| column is just the sum of each value
This command simply invokes |\pgfplotstabletypeset| with cleared output parameters. That means any of the column creation methods apply here as well, including any postprocessing steps (without the final typesetting).
- |\pgfplotstablesave| uses the keys |reset styles| and |disable rowcol styles| to clear any typesetting related options. Furthermore, it sets |string type| to allow verbatim output.
+ |\pgfplotstablesave| uses the keys |reset styles| and |disable rowcol styles| to clear any typesetting related options.
+
+ Furthermore, it sets |string type| to allow verbatim output. You may want to use |numeric as string type| instead in case you only have numerical data -- this will display integers resulting from arithmetics not in scientific notation\footnote{Note however, that |string type| doesn't round or truncate integers as well, even though they are displayed as floats.}.
\begin{codeexample}[]
\pgfplotstablesave[
create on use/postproc1/.style={create col/dyadic refinement rate=error1},
@@ -2227,6 +2536,10 @@ This section summarizes features of |pgfkeys|. The complete documentation can be
Use |\pgfplotstableset{|\meta{key}|/.append style={|\meta{key-value-list}|}}| to append \marg{key-value-list} to the style \meta{key}. This will assume the prefix |/pgfplots/table|.
\end{handler}
+\begin{handler}{{.initial}=\marg{value}}
+ Defines a new \meta{key} and assigns \meta{value}.
+\end{handler}
+
\begin{handler}{{.add}=\marg{before}\marg{after}}
Changes \meta{key} by prepending \meta{before} and appending \meta{after}.
\begin{codeexample}[]
@@ -2334,9 +2647,11 @@ The value (2,0) is `\pgfplotsretval'.
\paragraph{Attention:} If possible, avoid using this command inside of loops. It is quite slow.
\end{command}
-\begin{command}{\pgfplotstablegetrowsof\marg{file name or \textbackslash loadedtable}}
+\begin{commandlist}{%
+ \pgfplotstablegetrowsof\marg{file name or \textbackslash loadedtable},
+ \pgfplotstablegetcolsof\marg{file name or \textbackslash loadedtable}}
Defines |\pgfplotsretval| to be the number of rows in a table\footnote{It will also assign \texttt{\textbackslash pgfmathresult} to the same value.}. The argument may be either a file name or an already loaded table (the \meta{\textbackslash macro} of |\pgfplotstableread|).
-\end{command}
+\end{commandlist}
\begin{command}{\pgfplotstablevertcat\marg{\textbackslash table1}\marg{\textbackslash table2 or filename}}
@@ -2383,7 +2698,7 @@ The value (2,0) is `\pgfplotsretval'.
\begin{pgfplotskey}{table/input colnames to=\marg{name} (initially colnames)}
Inside of |\pgfplotstabletranspose|, this key handles what to do with \emph{input} column names.
- Will create a further column named \meta{name} which will be filled with the input column names (as string type).
+ This key will create a further column named \meta{name} which will be filled with the input column names (as string type).
\begin{codeexample}[]
\pgfplotstabletranspose[input colnames to=Input]\loadedtable{pgfplotstable.example3.dat}
\pgfplotstabletypeset[string type]\loadedtable
@@ -2400,7 +2715,7 @@ The value (2,0) is `\pgfplotsretval'.
If \meta{list} is empty, all columns of the input table will be used (which is the initial configuration).
- If \meta{list} is not empty, it is expected to be a list of column names. Only these columns will be used as input for the transposition, just as if the remaining one weren't there. It is acceptable to provide column aliases or |create on use| arguments inside of \meta{list}.
+ If \meta{list} is not empty, it is expected to be a list of column names. Only these columns will be used as input for the transposition, just as if the remaining ones weren't there. It is acceptable to provide column aliases or |create on use| arguments inside of \meta{list}.
\begin{codeexample}[]
\pgfplotstabletranspose[columns={a,b}]\loadedtable{pgfplotstable.example3.dat}
\pgfplotstabletypeset[string type]\loadedtable
@@ -2410,6 +2725,75 @@ The value (2,0) is `\pgfplotsretval'.
\end{pgfplotskey}
\end{commandlist}
+\begin{command}{\pgfplotstablesort\oarg{options}\meta{\textbackslash resulttable}\meta{\textbackslash table or filename}}
+ Sorts \meta{\textbackslash table or filename} according to \meta{options} and writes the sorted table to \meta{\textbackslash resulttable}.
+
+ Use the high level |sort| key to enable sorting automatically during |\pgfplotstabletypeset|.
+
+\begin{codeexample}[]
+\pgfplotstablesort[row sep=\\]\result{%
+ a b c \\
+ 19 2 [a]\\
+ -6 -14 [b]\\
+ 4 -14 [c]\\
+ -11 -9 [d]\\
+ 11 14 [e]\\
+ -9 -9 [f]\\
+ 1 13 [g]\\
+ 8 -10 [h]\\
+ 16 18 [i]\\
+ 19 -6 [j]\\
+}
+\pgfplotstabletypeset[columns/c/.style={string type}]{\result}%
+\end{codeexample}
+
+ The sort key and comparison function can be customized using the following keys:
+ \begin{key}{/pgfplots/table/sort key=\marg{column} (initially [index]0)}
+ Specifies the column which contains the sort key. The argument \meta{column} can be any of the columns of the input table, including |create on use|, |alias| or |[index]|\meta{integer} specifications. The initial setting uses the first available column.
+ \end{key}
+ \begin{key}{/pgfplots/table/sort key from=\marg{table} (initially empty)}
+ Allows to load the |sort key| from a different \meta{table}, which can be either a \meta{\textbackslash macro} or a \meta{file name}.
+ \end{key}
+
+ \begin{key}{/pgfplots/table/sort cmp=\marg{less than routine} (initially float <)}
+ Allows to use a different comparison function.
+ \begin{pgfplotskeylist}{%
+ fixed <,
+ fixed >,
+ int <,
+ int >,
+ float <,
+ float >,
+ date <,
+ date >,
+ string <,
+ string >}
+ These styles constitute the predefined comparison functions. The |fixed <|, |int <| and |float <| routines operate on numerical data where |int <| expects positive or negative integers and the other two expect real numbers. The |fixed <| has considerably smaller number range but is slightly faster than |float <|.
+
+ The |date <| compares dates of the form |YYYY-MM-DD|. The |string <| uses lexicographical string comparison based on the ASCII character codes of the sort keys. The |string <| routine also evaluates ASCII codes of control sequences or active characters\footnote{As long as they haven't been consumed by \TeX's preprocessing.}.
+\begin{codeexample}[]
+\pgfplotstablesort[row sep=\\,sort cmp=string <]\result{%
+ Header:\\% the column name
+ the\\
+ quick\\
+ brown\\
+ fox\\
+ jumps\\
+ over\\
+ the\\
+ lazy\\
+ dog\\
+}
+\pgfplotstabletypeset[string type]{\result}%
+\end{codeexample}
+ \end{pgfplotskeylist}
+ \begin{codeargskey}{/pgfplots/iflessthan}{#1#2#3#4}
+ Allows to define custom comparison functions (a strict ordering). It compares |#1 < #2| and invokes |#3| in case the comparison is true and |#4| if not.
+ The comparison will be evaluated in local scopes (local variables are freed afterwise).
+ \end{codeargskey}
+ \end{key}
+\end{command}
+
\subsection{Repeating Things: Loops}
\begin{command}{\foreach \meta{variables} |in| \meta{list} \marg{commands}}
A powerful loop command provided by \Tikz, see~\cite[Section Utilities]{tikz}.