%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% 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}
