diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex | 862 |
1 files changed, 862 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex new file mode 100644 index 00000000000..e2e3c74fa37 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex @@ -0,0 +1,862 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% Package pgfplots.sty documentation. +% +% Copyright 2007/2008 by Christian Feuersaenger. +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\input{pgfplots.preamble.tex} + +\usepackage{array} +\usepackage{colortbl} +\usepackage{booktabs} + +\pgfqkeys{/codeexample}{% + every codeexample/.style={ + width=4cm, + /pgfplots/every axis/.append style={legend style={fill=graphicbackground}} + }, + tabsize=4, +} + +%\pgfplotstableset{debug=true} + +\title{% + Manual for Package \PGFPlotstable\\ + {\small Component of \PGFPlots, Version \pgfplotsversion}\\ + {\small\href{http://sourceforge.net/projects/pgfplots}{http://sourceforge.net/projects/pgfplots}}} + +\begin{document} +\maketitle +\begin{abstract}% + This package reads tab-separated numerical tables from input and generates code for pretty-printed \LaTeX-tabulars. It rounds to the desired precision and prints it in different number formatting styles. +\end{abstract} +\tableofcontents +\section{Introduction} +\PGFPlotstable\ is a lightweight sub-package of \PGFPlots\ which employs its table input methods and the number formatting techniques to convert tab-separated tables into tabulars. + +It's input is a text file containing space separated rows, possibly starting with column names. Its output is a \LaTeX\ tabular which contains selected columns of the text table, rounded to the desired precision, printed in the desired number format (fixed point, integer, scientific etc). + +It is used with +\begin{codeexample}[code only] +\usepackage{pgfplots} +\end{codeexample} +\noindent and requires \PGFPlots\ and \PGF\ installed. + +\section{Text table input format} +\PGFPlotstable\ works with plain text file tables in which entries (``cells'') are separated by a separation character. The initial separation character is ``white space'' which means ``at least one space or tab''. Those tables can have a header line which contains column names and most other columns typically contain numerical data. + +\noindent The following listing shows |pgfplotstable.example1.dat| and is used often throughout this documentation. +\begin{codeexample}[code only] +# Convergence results +# fictional source, generated 2008 +level dof error1 error2 info grad(log(dof),log(error1)) quot(error1) +1 9 2.50000000e-01 7.57858283e-01 48 0 0 +2 25 6.25000000e-02 5.00000000e-01 25 -1.35691545e+00 4 +3 81 1.56250000e-02 2.87174589e-01 41 -1.17924958e+00 4 +4 289 3.90625000e-03 1.43587294e-01 8 -1.08987331e+00 4 +5 1089 9.76562500e-04 4.41941738e-02 22 -1.04500712e+00 4 +6 4225 2.44140625e-04 1.69802322e-02 46 -1.02252239e+00 4 +7 16641 6.10351562e-05 8.20091159e-03 40 -1.01126607e+00 4 +8 66049 1.52587891e-05 3.90625000e-03 48 -1.00563427e+00 3.99999999e+00 +9 263169 3.81469727e-06 1.95312500e-03 33 -1.00281745e+00 4.00000001e+00 +10 1050625 9.53674316e-07 9.76562500e-04 2 -1.00140880e+00 4.00000001e+00 +\end{codeexample} +Lines starting with `|%|' or `|#|' are considered to be comment lines and are ignored. + +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{key}{/pgfplots/table/col sep=\mchoice{space,comma,semicolon,colon,braces} (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. +\begin{codeexample}[code only] +# Convergence results +# fictional source generated 2008 +level,dof,error1,error2,info,{grad(log(dof),log(error1))},quot(error1) +1,9,2.50000000e-01,7.57858283e-01,48,0,0 +2,25,6.25000000e-02,5.00000000e-01,25,-1.35691545e+00,4 +3,81,1.56250000e-02,2.87174589e-01,41,-1.17924958e+00,4 +4,289,3.90625000e-03,1.43587294e-01,8,-1.08987331e+00,4 +5,1089,9.76562500e-04,4.41941738e-02,22,-1.04500712e+00,4 +6,4225,2.44140625e-04,1.69802322e-02,46,-1.02252239e+00,4 +7,16641,6.10351562e-05,8.20091159e-03,40,-1.01126607e+00,4 +8,66049,1.52587891e-05,3.90625000e-03,48,-1.00563427e+00,3.99999999e+00 +9,263169,3.81469727e-06,1.95312500e-03,33,-1.00281745e+00,4.00000001e+00 +10,1050625,9.53674316e-07,9.76562500e-04,2,-1.00140880e+00,4.00000001e+00 +\end{codeexample} + Thus, we need to specify |col sep=comma| when we read it. +\begin{codeexample}[] +\pgfplotstabletypesetfile[col sep=comma]{pgfplotstable.example1.csv} +\end{codeexample} + You may call |\pgfplotstableset{col sep=comma}| once in your preamble if all your tables uses commas as column separator. + + Please note that if cell entries (for example column names) contain the separation character, you need to enclose the column entry in \emph{braces}: |{grad(log(dof),log(error1)}|. If you want to use unmatched braces, you need to write a backslash before the brace. For example the name `|column{withbrace|' needs to be written as `|column\{withbrace|'. + + Furthermore, if you need empty cells in case |col sep=space|, you have to provide |{}| to delimit such a cell since |col sep=space| uses \emph{at least} one white space (consuming all following ones). + + 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 wite spaces (spaces and tabs) between cell entries are \emph{skipped} in case |braces| until the next \marg{entry} is found. +\end{key} + +\begin{command}{\pgfplotstabletypesetfile[\meta{optional arguments}]\marg{file name}} + This command loads the table file \marg{file name} and typesets it using the current configuration of number formats and table options. +\begin{codeexample}[] +\pgfplotstabletypesetfile{pgfplotstable.example1.dat} +\end{codeexample} + + \noindent The configuration can be customized with \meta{optional arguments}. + +\begin{codeexample}[] +\pgfplotstabletypesetfile[sci subscript,sci zerofill]{pgfplotstable.example1.dat} +\end{codeexample} +\end{command} + +% FIXME : 'header' option! +\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 than be used several times. +\begin{codeexample}[] +\pgfplotstableread{pgfplotstable.example1.dat}\table +\pgfplotstabletypeset[columns={dof,error1}]\table +\hspace{2cm} +\pgfplotstabletypeset[columns={dof,error2}]\table +\end{codeexample} +\end{command} + +\begin{command}{\pgfplotstabletypeset[\meta{optional arguments}]\marg{\textbackslash macro}} + Works in the same way as |\pgfplotstabletypesetfile|, but it accepts an already loaded table. +\end{command} + +\section{Selecting columns} +\begin{key}{/pgfplots/table/columns=\marg{comma-separated-list} (initially all available ones)} + Selects particular columns the table. If this option is missing, all available columns will be selected. + + Inside of \marg{comma-separated-list}, column names as they appear in the table's header are expected. If there is no header, simply use column names. If there are column names, the special syntax |[index]|\meta{integer} can be used to select columns by index. The first column has index~$0$. +\begin{codeexample}[] +\pgfplotstabletypesetfile[columns={dof,level,[index]4}]{pgfplotstable.example1.dat} +\end{codeexample} +\end{key} + +\begin{pgfplotstablecolumnkey} + Sets all options in \marg{key-value-list} exclusively for \marg{column name}. + +\begin{codeexample}[] +\pgfplotstabletypesetfile[ + columns/error1/.style={ + column name=$L_2$, + sci,sci zerofill,sci subscript, + precision=3}, + columns/error2/.style={ + column name=$A$, + sci,sci zerofill,sci subscript, + precision=2}, + columns/dof/.style={ + int detect, + column name=\textsc{Dof} + } +] + {pgfplotstable.example1.dat} +\end{codeexample} + If your column name contains commas `|,|', slashes `|/|' or equal signs `|=|', you need to enclose the column name in braces. +\begin{codeexample}[width=7cm] +\pgfplotstabletypesetfile[ + columns={dof,error1,{grad(log(dof),log(error1))}}, + columns/error1/.style={ + column name=$L_2$, + sci,sci zerofill,sci subscript, + precision=3}, + columns/dof/.style={ + int detect, + column name=\textsc{Dof}}, + columns/{grad(log(dof),log(error1))}/.style={ + column name=slopes $L_2$, + fixed,fixed zerofill, + precision=1} +] + {pgfplotstable.example1.dat} +\end{codeexample} +\end{pgfplotstablecolumnkey} + +\begin{key}{/pgfplots/table/column type=\marg{tabular column type} (initially c)} + Contains the column type for |tabular|. + + If all column types are empty, the complete argument is skipped (assuming that no |tabular| environment is generated). + + Use |\pgfplotstableset{column type/.add=|\marg{before}\marg{after}|}| to \emph{modify} a value instead of overwriting it. The |.add| key handler works for other options as well. +\begin{codeexample}[width=7cm] +\pgfplotstabletypesetfile[ + columns={dof,error1,info}, + column type/.add={|}{}% results in '|c' +] + {pgfplotstable.example1.dat} +\end{codeexample} +\end{key} + + +\begin{codekey}{/pgfplots/table/assign column name} + Allows to \emph{modify} the value of |column name|. + + Argument |#1| is the current column name, that means after + evaluation of |column name|. After |assign column| name, a new (possibly modified) value for |column name| should be set. + + That means you can use |column name| to assign the name as such + and |assign column name| to generate final \TeX\ code (for example to insert |\multicolumn{1}{c}{#1}|). + + Default is empty which means no change. +\end{codekey} + +\begin{stylekey}{/pgfplots/table/multicolumn names=\marg{tabular column type} (initially c)} + A style which typesets each column name using a |\multicolumn{1}|\marg{tabular column type}\marg{the column name} statement. +\end{stylekey} + +\begin{stylekey}{/pgfplots/table/dec sep align=\marg{header column type} (initially c)} + A style which employs the current decimal separator as alignment character. + + The first argument determines the alignment of the header column. + + The style |dec sep align| actually introduces two new |tabular| columns, namely |r@{}l|. It introduces multicolumns for column names accordingly and handles numbers which do not have a decimal separator. + +\begin{codeexample}[] +\pgfplotstabletypesetfile[ + columns={dof,error1,error2,info,{grad(log(dof),log(error1))}}, + columns/error1/.style={dec sep align}, + columns/error2/.style={sci,sci subscript,sci zerofill,dec sep align}, + columns/info/.style={fixed,dec sep align}, + columns/{grad(log(dof),log(error1))}/.style={fixed,dec sep align} +] + {pgfplotstable.example1.dat} +\end{codeexample} + + Or with comma as decimal separator: +\begin{codeexample}[] +\pgfplotstabletypesetfile[ + use comma, + columns={dof,error1,error2,info,{grad(log(dof),log(error1))}}, + columns/error1/.style={dec sep align}, + columns/error2/.style={sci,sci subscript,sci zerofill,dec sep align}, + columns/info/.style={fixed,dec sep align}, + columns/{grad(log(dof),log(error1))}/.style={fixed,dec sep align} +] + {pgfplotstable.example1.dat} +\end{codeexample} + It may be advisable to use the |zerofill| variants to force at least one digit after the decimal separator. +\end{stylekey} + +\begin{stylekey}{/pgfplots/table/dcolumn=\marg{tabular column type}\marg{type for column name} (initially \{D\{.\}\{.\}\{2\}\}\{c\})} + 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{stylekey}{/pgfplots/table/every first column} +A style which is installed for every first column only. +\begin{codeexample}[width=7cm] +\pgfplotstabletypesetfile[ + every head row/.style={before row=\hline,after row=\hline\hline}, + every last row/.style={after row=\hline}, + every first column/.style={ + column type/.add={|}{} + }, + every last column/.style={ + column type/.add={}{|} + }] + {pgfplotstable.example1.dat} +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/pgfplots/table/every last column} +A style which is installed for every last column only. +\end{stylekey} + +\begin{stylekey}{/pgfplots/table/every even column} +A style which is installed for every column with even column index (starting with~$0$). +{ +\pgfplotstableset{ + columns={dof,error1,{grad(log(dof),log(error1))},info}, + columns/error1/.style={ + column name=$L_2$, + sci,sci zerofill,sci subscript, + precision=3}, + columns/dof/.style={ + int detect, + column name=\textsc{Dof}}, + columns/{grad(log(dof),log(error1))}/.style={ + column name=slopes $L_2$, + fixed,fixed zerofill, + precision=1}} + +\begin{codeexample}[code only] +\pgfplotstableset{ + columns={dof,error1,{grad(log(dof),log(error1))},info}, + columns/error1/.style={ + column name=$L_2$, + sci,sci zerofill,sci subscript, + precision=3}, + columns/dof/.style={ + int detect, + column name=\textsc{Dof}}, + columns/{grad(log(dof),log(error1))}/.style={ + column name=slopes $L_2$, + fixed,fixed zerofill, + precision=1}} +\end{codeexample} + +\begin{codeexample}[width=7cm,graphic=white] +% \usepackage{colortbl} +\pgfplotstabletypesetfile[ + every even column/.style={ + column type/.add={>{\columncolor[gray]{.8}}}{} +}] + {pgfplotstable.example1.dat} +\end{codeexample} +} +\end{stylekey} + +\begin{stylekey}{/pgfplots/table/every odd column} +A style which is installed for every column with odd column index (starting with~$0$). +\end{stylekey} + +\begin{command}{\pgfplotstablecol} + During the evaluation of row or column options, this command expands to the current columns' index. +\end{command} +\begin{command}{\pgfplotstablerow} + During the evaluation of row or column options, this command expands to the current rows' index. +\end{command} + + +\section{Configuring row appearance} +\begin{key}{/pgfplots/before row=\marg{\TeX\ code}} + Contains \TeX\ code which will be installed before the first cell in a row. +\end{key} + +\begin{key}{/pgfplots/after row=\marg{\TeX\ code}} + Contains \TeX\ code which will be installed after the last cell in a row (i.e. after |\\|). +\end{key} + +\begin{stylekey}{/pgfplots/every even row} + A style which is installed for each row with even row index. The first row is supposed to be a ``head'' row and does not count. Indexing starts with~$0$. +{ +\pgfplotstableset{ + columns={dof,error1,{grad(log(dof),log(error1))}}, + columns/error1/.style={ + column name=$L_2$, + sci,sci zerofill,sci subscript, + precision=3}, + columns/dof/.style={ + int detect, + column name=\textsc{Dof}}, + columns/{grad(log(dof),log(error1))}/.style={ + column name=slopes $L_2$, + fixed,fixed zerofill, + precision=1}} + +\begin{codeexample}[code only] +\pgfplotstableset{ + columns={dof,error1,{grad(log(dof),log(error1))}}, + columns/error1/.style={ + column name=$L_2$, + sci,sci zerofill,sci subscript, + precision=3}, + columns/dof/.style={ + int detect, + column name=\textsc{Dof}}, + columns/{grad(log(dof),log(error1))}/.style={ + column name=slopes $L_2$, + fixed,fixed zerofill, + precision=1}} +\end{codeexample} + +\begin{codeexample}[width=7cm,graphic=white] +% \usepackage{booktabs} +\pgfplotstabletypesetfile[ + every head row/.style={ + before row=\toprule,after row=\midrule}, + every last row/.style={ + after row=\bottomrule}, +] + {pgfplotstable.example1.dat} +\end{codeexample} + +\begin{codeexample}[width=7cm,graphic=white] +% \usepackage{booktabs,colortbl} +\pgfplotstabletypesetfile[ + every even row/.style={ + before row={\rowcolor[gray]{0.9}}}, + every head row/.style={ + before row=\toprule,after row=\midrule}, + every last row/.style={ + after row=\bottomrule}, +] + {pgfplotstable.example1.dat} +\end{codeexample} + +} +\end{stylekey} + +\begin{stylekey}{/pgfplots/every odd row} + A style which is installed for each row with odd row index. The first row is supposed to be a ``head'' row and does not count. Indexing starts with~$0$. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every head row} + A style which is installed for each first row in the tabular. This can be used to adjust options for column names or to add extra lines/colours. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every first row} + A style which is installed for each first \emph{data} row, i.e. after the head row. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every last row} + A style which is installed for each last \emph{data} row. +\end{stylekey} + +\begin{codekey}{/pgfplots/table/row predicate} + A boolean predicate which allows to select particular rows of the input table. The argument |#1| contains the current row's index (starting with~$0$, not counting comment lines or column names). + + The return value is assigned to the \TeX-if |\ifpgfplotstableuserow|. If the boolean is not changed, the return value is true. +\begin{codeexample}[width=7cm] +% \usepackage{booktabs} +\pgfplotstabletypesetfile[ + every head row/.style={ + before row=\toprule,after row=\midrule}, + every last row/.style={ + after row=\bottomrule}, + row predicate/.code={% + \ifnum#1>4\relax + \ifnum#1<8\relax + \pgfplotstableuserowfalse + \fi + \fi} +] + {pgfplotstable.example1.dat} +\end{codeexample} + Please note that |row predicate| is applied \emph{before} any other option which affects row appearance. For example, the even/odd styles refer to those rows which are selected. + + Furthermore, |row predicate| applies only to the typeset routines, not the read methods. If you want to plot only selected table entries with |\addplot table|, use the \PGFPlots\ coordinate filter options. +\end{codekey} + +\begin{stylekey}{/pgfplots/table/skip rows between index=\marg{begin}\marg{end}} + A style which appends an |row predicate| which discards selected rows. The selection is done by index where indexing starts with~$0$. Every row with index $\meta{begin} \le i < \meta{end}$ will be skipped. +\begin{codeexample}[width=7cm] +% \usepackage{booktabs} +\pgfplotstabletypesetfile[ + every head row/.style={ + before row=\toprule,after row=\midrule}, + every last row/.style={ + after row=\bottomrule}, + skip rows between index={2}{4}, + skip rows between index={7}{9} +] + {pgfplotstable.example1.dat} +\end{codeexample} +\end{stylekey} + + +\section{Determining cell contents} +\begin{codekey}{/pgfplots/table/assign cell content} + 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|. +\end{codekey} + +\begin{key}{/pgfplots/table/assign cell content as number} + This here is the default implementation of |assign cell contents|. +\end{key} + +\begin{stylekey}{/pgfplots/table/string type} + A style which redefines |assign cell contents| to allow (a) text column(s). +\end{stylekey} + +\section{Customizing and getting the tabular code} +\begin{stylekey}{/pgfplots/table/every table} + A style which is installed at the beginning of every |\pgfplotstabletypeset| command. +\end{stylekey} + +\begin{key}{/pgfplots/table/font=\marg{font name} (initially empty)} + Assigns a font used for the complete table. +\end{key} + +\begin{key}{/pgfplots/table/begin table=\marg{code} (initially \textbackslash begin\{tabular\})} + Contains \marg{code} which is generated as table start. +\end{key} +\begin{key}{/pgfplots/table/end table=\marg{code} (initially \textbackslash end\{tabular\})} + Contains \marg{code} which is generated as table end. +\end{key} + +\begin{key}{/pgfplots/table/outfile=\marg{file name} (initially empty)} + Writes the generated tabular code into \marg{file name}. It can then be used with |\input|\marg{file name}, \PGFPlotstable\ is no longer required since it contains a completely normal |tabular|. +\begin{codeexample}[] +\pgfplotstabletypesetfile[ + columns={dof,error1}, + outfile=pgfplotstable.example1.out.tex] + {pgfplotstable.example1.dat} +\end{codeexample} +and |pgfplotstable.example1.out.tex| contains +\lstdefineformat{inp}{\\\\=\string\newline}% +\lstinputlisting[basicstyle=\ttfamily\footnotesize,format=inp]{pgfplotstable.example1.out.tex} + +The command |\pgfutilensuremath| checks whether math mode is active and switches to math mode if necessary\footnote{Please note that \lstinline{\\pgfutilensuremath} needs to be replaced by \lstinline{\\ensuremath} if you want to use the output file independent of \PGF. That can be done by \lstinline{\\let\\pgfutilensuremath=\\ensuremath} which enables the \LaTeX-command \lstinline{\\ensuremath}.}. +\end{key} + +\begin{key}{/pgfplots/table/debug=\marg{boolean} (initially false)} + If enabled, will write every final tabular code to you log file. +\end{key} + +\section{Defining column types for \texttt{tabular}} +Besides input of text files, it is sometimes desireable to define column types for existing \texttt{tabular} environments. + +\begin{command}{\newcolumntype\marg{letter}[\meta{number of arguments}]$>$\marg{before column}\meta{column type}$<$\marg{after column}} +The command |\newcolumntype| is part of the |array| package and it defines a new column type \marg{letter} for use in \LaTeX\ tabular environments. +\begin{codeexample}[code only] +\usepackage{array} +\end{codeexample} + +\begin{codeexample}[] +\newcolumntype{d}{>{-}c<{+}} +\begin{tabular}{dl} +a & b \\ +c & d \\ +\end{tabular} +\end{codeexample} + +Now, the environment |pgfplotstablecoltype| can be used in \marg{before column} and \marg{after column} to define numerical columns: +\begin{codeexample}[] +\newcolumntype{L}[1] + {>{\begin{pgfplotstablecoltype}[#1]}r<{\end{pgfplotstablecoltype}}} + +\begin{tabular}{L{int detect}L{sci,sci subscript,sci zerofill}} +9 & 2.50000000e-01\\ +25 & 6.25000000e-02\\ +81 & 1.56250000e-02\\ +289 & 3.90625000e-03\\ +1089 & 9.76562500e-04\\ +4225 & 2.44140625e-04\\ +16641 & 6.10351562e-05\\ +66049 & 1.52587891e-05\\ +263169 & 3.81469727e-06\\ +1050625& 9.53674316e-07\\ +\end{tabular} +\end{codeexample} +\noindent The environment |pgfplotstablecoltype| accepts an optional argument which may contain any number formatting options. It is an error if numerical columns contain non-numerical data, so it may be necessary to use |\multicolumn| for column names. + +\begin{codeexample}[] +\newcolumntype{L}[1] + {>{\begin{pgfplotstablecoltype}[#1]}r<{\end{pgfplotstablecoltype}}} + +\begin{tabular}{L{int detect}L{sci,sci subscript,sci zerofill}} +\multicolumn{1}{r}{Dof} & \multicolumn{1}{r}{Error}\\ +9 & 2.50000000e-01\\ +25 & 6.25000000e-02\\ +81 & 1.56250000e-02\\ +289 & 3.90625000e-03\\ +1089 & 9.76562500e-04\\ +4225 & 2.44140625e-04\\ +16641 & 6.10351562e-05\\ +66049 & 1.52587891e-05\\ +263169 & 3.81469727e-06\\ +1050625& 9.53674316e-07\\ +\end{tabular} +\end{codeexample} +\end{command} + +\section{Number formatting options} +\label{sec:number:printing}% +The following extract of \cite{tikz} explains how to configure number formats. +\begin{command}{\pgfmathprintnumber\marg{x}} +Generates pretty-printed output for the (real) number \marg{x}. The input number \marg{x} is parsed using |\pgfmathfloatparsenumber| which allows arbitrary precision. + +Numbers are typeset in math mode using the current set of number printing options, see below. Optional arguments can also be provided using |\pgfmathprintnumber[|\meta{options}|]|\marg{x}. +\end{command} + +\begin{command}{\pgfmathprintnumberto\marg{x}\marg{\textbackslash macro}} + Returns the resulting number into \marg{\textbackslash macro} instead of typesetting it directly. +\end{command} + +\begin{key}{/pgf/number format/fixed} +Configures |\pgfmathprintnumber| to round the number to a fixed number of digits after the period, discarding any trailing zeros. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed,precision=2} +\pgfmathprintnumber{4.568}\hspace{1em} +\pgfmathprintnumber{5e-04}\hspace{1em} +\pgfmathprintnumber{0.1}\hspace{1em} +\pgfmathprintnumber{24415.98123}\hspace{1em} +\pgfmathprintnumber{123456.12345} +\end{codeexample} + +See section~\ref{sec:number:styles} for how to change the appearance. +\end{key} + +\begin{key}{/pgf/number format/fixed zerofill=\marg{boolean} (default true)} +Enables or disables zero filling for any number drawn in fixed point format. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=2} +\pgfmathprintnumber{4.568}\hspace{1em} +\pgfmathprintnumber{5e-04}\hspace{1em} +\pgfmathprintnumber{0.1}\hspace{1em} +\pgfmathprintnumber{24415.98123}\hspace{1em} +\pgfmathprintnumber{123456.12345} +\end{codeexample} +This key affects numbers drawn with |fixed| or |std| styles (the latter only if no scientific format is choosen). +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,std,fixed zerofill,precision=2} +\pgfmathprintnumber{4.568}\hspace{1em} +\pgfmathprintnumber{5e-05}\hspace{1em} +\pgfmathprintnumber{1}\hspace{1em} +\pgfmathprintnumber{123456.12345} +\end{codeexample} + +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. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,sci,precision=2} +\pgfmathprintnumber{4.568}\hspace{1em} +\pgfmathprintnumber{5e-04}\hspace{1em} +\pgfmathprintnumber{0.1}\hspace{1em} +\pgfmathprintnumber{24415.98123}\hspace{1em} +\pgfmathprintnumber{123456.12345} +\end{codeexample} + +See section~\ref{sec:number:styles} for how to change the exponential display style. +\end{key} + +\begin{key}{/pgf/number format/sci zerofill=\marg{boolean} (default true)} +Enables or disables zero filling for any number drawn in scientific format. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,sci,sci zerofill,precision=2} +\pgfmathprintnumber{4.568}\hspace{1em} +\pgfmathprintnumber{5e-04}\hspace{1em} +\pgfmathprintnumber{0.1}\hspace{1em} +\pgfmathprintnumber{24415.98123}\hspace{1em} +\pgfmathprintnumber{123456.12345} +\end{codeexample} +As with |fixed zerofill|, this option does only affect numbers drawn in |sci| format (or |std| if the scientific format is chosen). + +See section~\ref{sec:number:styles} for how to change the exponential display style. +\end{key} + +\begin{stylekey}{/pgf/number format/zerofill=\marg{boolean} (default true)} + Sets both, |fixed zerofill| and |sci zerofill| at once. +\end{stylekey} + +\begin{key}{/pgf/number format/std} +Configures |\pgfmathprintnumber| to a standard algorithm. It chooses either \texttt{fixed} or \texttt{sci}, depending on the order of magnitude. Let $n=s \cdot m \cdot 10^e$ be the input number and $p$ the current precision. If $-p/2 \le e \le 4$, the number is displayed using the fixed format. Otherwise, it is displayed using the scientific format. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,std,precision=2} +\pgfmathprintnumber{4.568}\hspace{1em} +\pgfmathprintnumber{5e-04}\hspace{1em} +\pgfmathprintnumber{0.1}\hspace{1em} +\pgfmathprintnumber{24415.98123}\hspace{1em} +\pgfmathprintnumber{123456.12345} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/int detect} +Configures |\pgfmathprintnumber| to detect integers automatically. If the input number is an integer, no period is displayed at all. If not, the scientific format is chosen. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,int detect,precision=2} +\pgfmathprintnumber{15}\hspace{1em} +\pgfmathprintnumber{20}\hspace{1em} +\pgfmathprintnumber{20.4}\hspace{1em} +\pgfmathprintnumber{0.01}\hspace{1em} +\pgfmathprintnumber{0} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/int trunc} +Truncates every number to integers (discards any digit after the period). + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,int trunc} +\pgfmathprintnumber{4.568}\hspace{1em} +\pgfmathprintnumber{5e-04}\hspace{1em} +\pgfmathprintnumber{0.1}\hspace{1em} +\pgfmathprintnumber{24415.98123}\hspace{1em} +\pgfmathprintnumber{123456.12345} +\end{codeexample} +\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} + +\subsection{Changing display styles}% +\label{sec:number:styles}% +You can change the way how numbers are displayed. For example, if you use the `\texttt{fixed}' style, the input number is rounded to the desired precision and the current fixed point display style is used to typeset the number. The same is applied to any other format: first, rounding routines are used to get the correct digits, afterwards a display style generates proper \TeX-code. + +\begin{key}{/pgf/number format/set decimal separator=\marg{text}} +Assigns \marg{text} as decimal separator for any fixed point numbers (including the mantisse in sci format). +\end{key} +\begin{key}{/pgf/number format/dec sep=\marg{text}} + Just another name for |set decimal separator|. +\end{key} + + +\begin{key}{/pgf/number format/set thousands separator=\marg{text}} +Assigns \marg{text} as thousands separator for any fixed point numbers (including the mantisse in sci format). + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={}} +\pgfmathprintnumber{1234.56} +\end{codeexample} +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={}} +\pgfmathprintnumber{1234567890} +\end{codeexample} + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={.}} +\pgfmathprintnumber{1234567890} +\end{codeexample} +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={,}} +\pgfmathprintnumber{1234567890} +\end{codeexample} +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={{{{,}}}}} +\pgfmathprintnumber{1234567890} +\end{codeexample} +The last example employs commas and disables the default comma-spacing. +\end{key} +\begin{key}{/pgf/number format/1000 sep=\marg{text}} + Just another name for |set thousands separator|. +\end{key} + + +\begin{key}{/pgf/number format/use period} +A predefined style which installs periods `\texttt{.}' as decimal separators and commas `\texttt{,}' as thousands separators. This style is the default. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period} +\pgfmathprintnumber{12.3456} +\end{codeexample} +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period} +\pgfmathprintnumber{1234.56} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/use comma} +A predefined style which installs commas `\texttt{,}' as decimal separators and periods `\texttt{.}' as thousands separators. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma} +\pgfmathprintnumber{12.3456} +\end{codeexample} +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma} +\pgfmathprintnumber{1234.56} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/skip 0.=\marg{boolean}} + Configures whether numbers like $0.1$ shall be typeset as $.1$ or not. +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill,precision=2, + skip 0.} +\pgfmathprintnumber{0.56} +\end{codeexample} +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill,precision=2, + skip 0.=false} +\pgfmathprintnumber{0.56} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/sci 10e} +Uses $m \cdot 10^e$ for any number displayed in scientific format. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,sci,sci 10e} +\pgfmathprintnumber{12.345} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/sci 10\textasciicircum e} +The same as `|sci 10e|'. +\end{key} + +\begin{key}{/pgf/number format/sci e} +Uses the `$1e{+}0$' format which is generated by common scientific tools for any number displayed in scientific format. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,sci,sci e} +\pgfmathprintnumber{12.345} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/sci E} +The same with an uppercase `\texttt{E}'. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,sci,sci E} +\pgfmathprintnumber{12.345} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/sci subscript} +Typesets the exponent as subscript for any number displayed in scientific format. This style requires very few space. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,sci,sci subscript} +\pgfmathprintnumber{12.345} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/number format/assume math mode=\marg{boolean} (default true)} + Set this to |true| if you don't want any checks for math mode. + + The initial setting installs a |\pgfutilensuremath| around each final number to change to math mode if necessary. Use |assume math mode=true| if you know that math mode is active and you don't want |\pgfutilensuremath|. +\end{key} + +\section{Plain \TeX\ and Con\TeX t support} +The table code generator is initialised to produce \LaTeX\ |tabular| environments. However, it only relies on~`|&|' being the column separator and~`|\\|' the row terminator. The |column type| feature is more or less specific to |tabular|, but you can disable it completely. Replace |begin table| and |end table| with appropriate \TeX- or Con\TeX t commands to change it. If you have useful default styles (or bug reports), let me know. + +\printindex + +\bibliographystyle{abbrv} %gerapali} %gerabbrv} %gerunsrt.bst} %gerabbrv}% gerplain} +\bibliography{pgfplots.bib} +\end{document} |