pgfplots

PGFplotsTable

$\newcommand{\footnotename}{footnote}$ $\def \LWRfootnote {1}$ $\newcommand {\footnote }[2][\LWRfootnote ]{{}^{\mathrm {#1}}}$ $\newcommand {\footnotemark }[1][\LWRfootnote ]{{}^{\mathrm {#1}}}$ $\let \LWRorighspace \hspace $ $\renewcommand {\hspace }{\ifstar \LWRorighspace \LWRorighspace }$ $\newcommand {\mathnormal }[1]{{#1}}$ $\newcommand \ensuremath [1]{#1}$ $\newcommand {\LWRframebox }[2][]{\fbox {#2}} \newcommand {\framebox }[1][]{\LWRframebox } $ $\newcommand {\setlength }[2]{}$ $\newcommand {\addtolength }[2]{}$ $\newcommand {\setcounter }[2]{}$ $\newcommand {\addtocounter }[2]{}$ $\newcommand {\arabic }[1]{}$ $\newcommand {\number }[1]{}$ $\newcommand {\noalign }[1]{\text {#1}\notag \\}$ $\newcommand {\cline }[1]{}$ $\newcommand {\directlua }[1]{\text {(directlua)}}$ $\newcommand {\luatexdirectlua }[1]{\text {(directlua)}}$ $\newcommand {\protect }{}$ $\def \LWRabsorbnumber #1 {}$ $\def \LWRabsorbquotenumber "#1 {}$ $\newcommand {\LWRabsorboption }[1][]{}$ $\newcommand {\LWRabsorbtwooptions }[1][]{\LWRabsorboption }$ $\def \mathchar {\ifnextchar "\LWRabsorbquotenumber \LWRabsorbnumber }$ $\def \mathcode #1={\mathchar }$ $\let \delcode \mathcode $ $\let \delimiter \mathchar $ $\def \oe {\unicode {x0153}}$ $\def \OE {\unicode {x0152}}$ $\def \ae {\unicode {x00E6}}$ $\def \AE {\unicode {x00C6}}$ $\def \aa {\unicode {x00E5}}$ $\def \AA {\unicode {x00C5}}$ $\def \o {\unicode {x00F8}}$ $\def \O {\unicode {x00D8}}$ $\def \l {\unicode {x0142}}$ $\def \L {\unicode {x0141}}$ $\def \ss {\unicode {x00DF}}$ $\def \SS {\unicode {x1E9E}}$ $\def \dag {\unicode {x2020}}$ $\def \ddag {\unicode {x2021}}$ $\def \P {\unicode {x00B6}}$ $\def \copyright {\unicode {x00A9}}$ $\def \pounds {\unicode {x00A3}}$ $\let \LWRref \ref $ $\renewcommand {\ref }{\ifstar \LWRref \LWRref }$ $ \newcommand {\multicolumn }[3]{#3}$ $\require {textcomp}$ $ \newcommand {\meta }[1]{\langle \textit {#1}\rangle } $ $\newcommand {\toprule }[1][]{\hline }$ $\let \midrule \toprule $ $\let \bottomrule \toprule $ $\def \LWRbooktabscmidruleparen (#1)#2{}$ $\newcommand {\LWRbooktabscmidrulenoparen }[1]{}$ $\newcommand {\cmidrule }[1][]{\ifnextchar (\LWRbooktabscmidruleparen \LWRbooktabscmidrulenoparen }$ $\newcommand {\morecmidrules }{}$ $\newcommand {\specialrule }[3]{\hline }$ $\newcommand {\addlinespace }[1][]{}$ $\require {colortbl}$ $\let \LWRorigcolumncolor \columncolor $ $\renewcommand {\columncolor }[2][named]{\LWRorigcolumncolor [#1]{#2}\LWRabsorbtwooptions }$ $\let \LWRorigrowcolor \rowcolor $ $\renewcommand {\rowcolor }[2][named]{\LWRorigrowcolor [#1]{#2}\LWRabsorbtwooptions }$ $\let \LWRorigcellcolor \cellcolor $ $\renewcommand {\cellcolor }[2][named]{\LWRorigcellcolor [#1]{#2}\LWRabsorbtwooptions }$ $\newcommand {\intertext }[1]{\text {#1}\notag \\}$ $\let \Hat \hat $ $\let \Check \check $ $\let \Tilde \tilde $ $\let \Acute \acute $ $\let \Grave \grave $ $\let \Dot \dot $ $\let \Ddot \ddot $ $\let \Breve \breve $ $\let \Bar \bar $ $\let \Vec \vec $ $\newcommand {\nicefrac }[3][]{\mathinner {{}^{#2}\!/\!_{#3}}}$

6.1Loading and Displaying data

6.1.1Text 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” (see option col sep below). Those tables can have a header line which contains column names and most other columns typically contain numerical data.

The following listing shows pgfplotstable.example1.dat and is used often throughout this documentation.

# Convergence results # fictional source, generated 2008


                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

Lines starting with ‘%’ or ‘#’ are considered to be comment lines and are ignored.

\pgfplotstabletypeset[ (math image) optional arguments]{file name or \macro 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. 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 was found in a file (see \pgfplotstableread).

The configuration can be customized with (math image) optional arguments. Configuration can be done for the complete table or for particular columns (or rows).

All of these options are explained in all detail in the following sections.

You may also use an input format similar to the tabular environment:

Technical note: every opened file will be protocolled into your logfile.

\pgfplotstabletypesetfile[ (math image) optional arguments]{file name} ¶

Loads the table (math image) file name and typesets it. As of PgfplotsTable 1.2, this command is an alias to \pgfplotstabletypeset, that means the first argument can be either a file name or an already loaded table.

\pgfplotstableread{ (math image) file name}{\macro} ¶

\pgfplotstableread{ (math image) inline table}{\macro}

Loads a table into the TeX macro (math image) \macro. This macro will store the table as internal structure and can be used multiple times.

The first argument can be a (math image) file name as in the example here. It is also possible to provide the table data directly:

% 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

It is checked automatically whether the first argument contains inline data or a file name.

This 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.

Special cases and more details:

• 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).
• There are variants of this command which do not really build 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.
• Technical note: every opened file will be protocolled into your logfile.
• Note: avoid using ‘\table’ as name, it conflicts with \begin{table} of LaTeX.

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 characters always delimit lines).

For example, the file pgfplotstable.example1.csv uses commas as separation characters.

# Convergence results # fictional source generated 2008


                    level,dof,error1,error2,info,{grad(log(dof),log(error2))},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

Thus, we need to specify col sep=comma when we read it.

You may call \pgfplotstableset{col sep=comma} once in your preamble if all your tables use 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 braces: {grad(log(dof),log(error2)}. 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’.

For col sep$\neq $space, spaces will be considered to be part of the argument (there is no trimming). However, (as usual in TeX), multiple successive spaces and tabs are replace by a single white space. Of course, if col sep=tab, tabs are the column separators and will be treated specially.

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 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, (math image) entry, for this choice. Furthermore, any white space (spaces and tabs) between cell entries are skipped in case braces until the next entry is found.

A further specialty of col sep=braces is that it has support for multi-line cells: everything within balanced braces is considered to be part of a cell. This includes newlines:¹⁰⁰

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.

/pgfplots/table/trim cells=true|false (initially false) ¶

If enabled, leading and trailing white space 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=&.

/pgfplots/table/header=true|false|has colnames (initially true)

Configures if column names shall be identified automatically during input operations.

The first non-comment line can be a header which contains column names. The header key configures how to detect if that is really the case.

The choice true enables auto detection of column names: If the first non-comment line contains at least one non-numerical entry (for example ‘a name’), each entry in this line is supposed to be a column name. If the first non-comment line contains only numerical data, it is used as data row. In this case, column indices will be assigned as column “names”.

The choice false is identical to this last case, i.e. even if the first line contains strings, they won’t be recognised as column names.

Finally, the choice has colnames is the opposite of false: it assumes that the first non-comment line contains column names. In other words: even if only numbers are contained in the first line, they are considered to be column names.

Note that this key only configures headers in input tables. To configure output headers, you may want to look at every head row.

/pgfplots/table/format=auto|inline|file (initially auto) ¶

Configures the format expected as first argument for \pgfplotstableread{ (math image) input}.

The choice 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 file expects a file name.

The choice 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.

/pgfplots/table/row sep=newline|\\ (initially newline)

Configures the character to separate rows of the inline table data format (see format=inline).

The choice 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 \\ uses ‘\\’ to indicate the end of a row.

Note that 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:

1. First possibility: call \pgfplotstableread{data}\yourmacro outside of any macro declaration.
2. Use row sep=\\.

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 space. It does other substitutions of this sort as well, and these substitutions can’t be undone (maybe not even found).

/pgfplots/table/ignore chars={ (math image) 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 (math image) 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

first,second
(1)(0),2 1#2)
(3)(0),4 1#3)
(5)(0),6 1#3)

then, we can ignore several of the characters by writing

The (math image) 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 space, 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


                    \pgfplotstableset{ignore chars={\^^01}}

to eliminate them silently. The ^^ (math image) digitdigit notation is a TeX feature to provide characters in hexadecimal encoding where 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 (math image) newline and \^^I is tab. Refer to [4] 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.¹⁰¹

/pgfplots/table/white space chars={ (math image) comma-separated-list} (initially empty)

Allows to define a list of single characters which are actually treated like white space (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.

/pgfplots/table/text special chars={ (math image) comma-separated-list} (initially empty) ¶

Allows to define a list of single characters which are actually treated like normal text (like any characters with category code $12$).

The text special chars list is used in exactly the same way as ignore chars, and the same remarks as above apply as well.

Note that some (selected) special characters are installed by verb string type.

/pgfplots/table/comment chars={ (math image) comma-separated-list} (initially empty)

Allows to add one or more additional comment characters. Each of these characters has a similar effect as the # character, i.e. all following characters of that particular input line are skipped.

The example above uses ‘!’ as additional comment character (which allows to parse Touchstone files).

/pgfplots/table/percent is letter=true|false (initially false) ¶

Allows to control how to treat percent characters in input files. PgfplotsTable used to keep the TeX special meaning as comment character which means that all characters following percent where ignored.

The value true means that a percent is just a normal letter without special meaning. The value false means that percent is special as it used to be.

/pgfplots/table/text indicator={ (math image) char} (initially empty) ¶

Allows to define a text indicator character. If this is defined, it can be used to enclose delimiters in a cell’s body:

If the text indicator also occurs within the cell, it has to be doubled:

Cells which do not start with the text indicator are handled normally. Note that text indicator does not support multi-line cells.

/pgfplots/table/skip first n={ (math image) integer} (initially 0)

Allows to skip the first (math image) integer lines of an input file. The lines will not be processed.

/pgfplots/table/search path={ (math image) comma-separated-list} (initially .)

Allows to provide a search path for input tables. This variable is evaluated whenever pgfplots attempts to read a data file. This includes both \pgfplotstableread and \addplot table; its value resembles a comma-separated list of path names. The requested file will be read from the first matching location in that list.

Use ‘.’ to search using the normal TeX file searching procedure (i.e. typically in the current working directory).

An entry in (math image) comma-separated-list can be relative to the current working directory, i.e. something like search path={.,../datafiles} is accepted.

/pgfplots/table/search path/implicit .=true|false (initially true)

PgfplotsTable allows to add ‘.’ to the value of search path implicitly as this is typically assumed in many applications of search paths.

The initial configuration search path/implicit .=true will ensure that ‘.’ is added in front of the search path if the user value does not contain a ‘.’.

The value search path/implicit .=false will not add ‘.’.

Keep in mind that ‘.’ means “let TeX search for the file on its own”. This will typically find files in the current working directory, but it will also include processing of TEXINPUTS.

¹⁰⁰ 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 can have multi-line cells for every column separator if you enclose them in balanced curly braces. However, col sep=braces has the special treatment that end-of-line counts as white space character; for every other col sep value, this white space is suppressed to remove spurious spaces.

¹⁰¹ See also row sep for more information about dealing with fragile inline table formats.

6.1.2Selecting Columns and their Appearance Styles¶

/pgfplots/table/columns={ (math image) comma-separated-list} ¶

Selects particular columns of the table. If this option is empty (has not been provided), all available columns will be selected.

Inside of (math image) comma-separated-list, column names as they appear in the table’s header are expected. If there is no header, simply use column indices. If there are column names, the special syntax [index]integer can be used to select columns by index. The first column has index $0$.

The special pgfkeys feature \pgfplotstableset{columns/.add={}{,a further col}} allows to append a value, in this case ‘,a further col’ to the actual value. See /.add for details.

/pgfplots/table/alias/col name/.initial={real col name} ¶

Assigns the new name (math image) col name for the column denoted by real col name. Afterwards, accessing col name will use the data associated with column real col name.

You can use columns/ (math image) 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.

In case (math image) col name contains characters which are required for key settings, you need to use braces around it: “alias/{name=wi/th,special}/.initial={othername}”.

This key is used whenever columns are queried, it applies also to the \addplot table statement of pgfplots.

/pgfplots/table/columns/column name/.style={key-value-list}

Sets all options in (math image) key-value-list exclusively for column name.

If your column name contains commas ‘,’, slashes ‘/’ or equal signs ‘=’, you need to enclose the column name in braces.

If your tables don’t have column names, you can simply use integer indices instead of (math image) column name to refer to columns. If you have column names, you can’t set column styles using indices.

/pgfplots/table/display columns/index/.style={key-value-list} ¶

Applies all options in (math image) key-value-list exclusively to the column which will appear at position index in the output table.

In contrast to the table/columns/ (math image) name styles, this option refers to the output table instead of the input table. Since the output table has no unique column name, you can only access columns by index.

Indexing starts with $\meta {index}=0$.

Display column styles override input column styles.

/pgfplots/table/every col no index(style, no value) ¶

A style which is identical with display columns/ (math image) index: it applies exclusively to the column at position index in the output table.

See display columns/ (math image) index for details.

/pgfplots/table/column type={ (math image) 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={ (math image) before}{after}} to modify a value instead of overwriting it. The /.add key handler works for other options as well.

/pgfplots/table/column name={ (math image) TeX display column name} (initially \pgfkeysnovalue) ¶

Sets the column’s display name in the current context.

It is advisable to provide this option inside of a column-specific style, i.e. using

columns/{ (math image) lowlevel colname}/.style={column name={TeX display column name}} .

Here, “lowlevel colname” refers to the column name that is present in your input table. This lowlevel column name has a couple of restrictions (it has to be expandable, for example – that means many control sequences are forbidden). The value of column name is only used within \pgfplotstabletypeset in order to generate a display name for the column in question.

Note that you are allowed to provide an empty display name using column name={}. This results in an empty string above the column when used in \pgfplotstabletypeset.

The initial configuration is column name=\pgfkeysnovalue. This constitutes a special “null” value which tells \pgfplotstabletypeset that it should fall back to the column’s name (i.e. the lowlevel name).

/pgfplots/table/assign column name/.code={...} ¶

Allows to 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}).

Note that the PgfplotsTable provides limited postprocessing capabilities for headers, in particular, postproc cell content and its friends merely apply to “normal” cells. If you want to modify the appearance of header cells, you should consider using assign column name.

Default is empty which means no change.

/pgfplots/table/multicolumn names={ (math image) tabular column type} (style, initially c) ¶

A style which typesets each column name in the current context using a \multicolumn{1}{ (math image) tabular column type}{the column name} statement.

Here, (math image) the column name is set with column name as usual.

/pgfplots/table/dec sep align={ (math image) header column type} (style, initially c) ¶

A style which aligns numerical columns at the decimal separator.

The first argument determines the alignment of the header column.

Please note that you need \usepackage{array} for this style.

Or with comma as decimal separator:

It may be advisable to use fixed zerofill and/or sci zerofill to force at least one digit after the decimal separator to improve placement of exponents:

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.

Note that for fixed point numbers, it might be an alternative to use fixed zerofill combined with column type=r to get a similar effect.

Please note that this style overwrites column type, assign cell content and some number formatting settings.

/pgfplots/table/sci sep align={ (math image) header column type} (style, initially c) ¶

A style which aligns numerical columns at the exponent in scientific representation.

The first argument determines the alignment of the header column.

It works similarly to dec sep align, namely by introducing two artificial columns r@{}l for alignment.

Please note that you need \usepackage{array} for this style.

Please note that this style overwrites column type, assign cell content and some number formatting settings.

/pgfplots/table/dcolumn={ (math image) tabular column type}{type for column name} (style, 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).

/pgfplots/table/sort={ (math image) 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.

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 respecting the include outfiles caching mechanism). Any create on use specifications are resolved before calling the sort key.

/pgfplots/table/every first column(style, no value) ¶

A style which is installed for every first column only.

/pgfplots/table/every last column(style, no value) ¶

A style which is installed for every last column only.

/pgfplots/table/every even column(style, no value) ¶

A style which is installed for every column with even column index (starting with $0$).


                    \pgfplotstableset{


                        columns={dof,error1,{grad(log(dof),log(error2))},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(error2))}/.style={


                            column name=slopes $L_2$,


                            fixed,fixed
                    zerofill,


                            precision=1}}

/pgfplots/table/every column(style, no value) ¶

A style which is applied to every column.

/pgfplots/table/every odd column(style, no value) ¶

A style which is installed for every column with odd column index (starting with $0$).

\pgfplotstablecol ¶

During the evaluation of row or column options, this command expands to the current column’s index.

\pgfplotstablecolname ¶

During the evaluation of column options, this command expands to the current column’s name. It is valid while \pgfplotstabletypeset processes the column styles (including the preprocessing step explained in Section 6.2.3), prepares the output cell content and checks row predicates.

\pgfplotstablerow ¶

During the evaluation of row or column options, this command expands to the current row’s index.

“Evaluation of column options” applies to any of the styles in Section 6.2, i.e. preprocessing, typesetting, and postprocessing.

The macro \pgfplotstablerow can take any of the values $0,1,2,\dotsc ,n-1$ where $n$ is the value of \pgfplotstablerows.

“Evaluation of row options” applies to stuff like every last row.

Note that it will have the special value $-1$ for the header row.

\pgfplotstablecols ¶

During the evaluation of row or column options, this command expands to the total number of columns in the output table.

\pgfplotstablerows ¶

During evaluation of columns, this command expands to the total number of input rows. You can use it inside of row predicate.

During evaluation of rows, this command expands to the total number of output rows.

\pgfplotstablename ¶

During \pgfplotstabletypeset, this macro contains the table’s macro name as top-level expansion. If you are unfamiliar with “top-level-expansions” and ‘\expandafter’, you will probably never need this macro.

Advances users may benefit from expressions like

\expandafter\pgfplotstabletypeset\pgfplotstablename.

For tables which have been loaded from disk (and have no explicitly assigned macro name), this expands to a temporary macro.

¹⁰² Unfortunately, dec sep align is currently not very flexible when it comes to column type modifications. In particular, it is not possible to use colored columns or cells in conjunction with dec sep align. The \rowcolor command works properly; the color hangover introduced by colortbl is adjusted automatically.

6.1.3Configuring Row Appearance: Styles¶

The following styles allow to configure the final table code after any cell contents have been assigned.

/pgfplots/table/before row={ (math image) TeX code} ¶

Contains TeX code which will be installed before the first cell in a row.

Keep in mind that PgfplotsTable does no magic – it is simply a code generator which produces tabular environments. Consequently, you can add any TeX code which you would normally write into your tabular environment here.

An example could be a multicolumn heading for which PgfplotsTable has no own solution:

The example declares a lot of options and is finally followed by a short inline table. The every head row style configures \multicolumn headings by means of verbatim tabular code, together with booktabs rules. It might be helpful to consider the debug or outfile keys during experiments. The columns/... styles are necessary to change the column headings.

Sometimes, one wants to combine \multicolumn and \rowcolor. From what I know about LaTeX, this is a little bit complicated: it requires the use of \columncolor inside of the \multicolumn. As in the example above, it is necessary to modify the code generated by PgfplotsTable a little bit. Keep in mind that PgfplotsTable is just a code generator for tabular environments – modify whatever you want. The following example demonstrates the combination of \multicolumn and \rowcolor. It has been taken out of an – admittedly advanced – application:

Up to the number formatting (which actually invokes \pgfmathprintnumber), the code above is equivalent to the listing


                    \newcolumntype{C}{>{\centering\arraybackslash}p{6mm}}% a centered
                    fixed-width-column

\begin{tabular}{|C|C|C|c|} \hline


                    \rowcolor{lightgray} \multicolumn{3}{|>{\columncolor{lightgray}}c|}{Quantenzahlen} & Term-\\


                    \rowcolor{lightgray} $n$ & $\ell$ & $\lambda$ &
                    bezeichnung\\

\hline $1$ & $0$ & $0$ & $1 s\sigma$ \\ $2$ & $0$ & $0$ & $2 s\sigma$ \\ $2$ & $1$ & $0$ & $2 p\sigma$ \\ $2$ & $1$ & $1$ & $2 p \pi$ \\ $3$ & $2$ & $0$ & $3 d\sigma$ \\ $3$ & $2$ & $2$ & $3 d\delta$ \\ \hline \end{tabular}

Clearly, the overhead introduced by defining a lot of styles is only worth the effort if you require number printing, automated processing, or have a huge bulk of similar tables.

/pgfplots/table/after row={ (math image) TeX code} ¶

Contains TeX code which will be installed after the last cell in a row (i.e. after \\).

/pgfplots/table/every even row(style, no value) ¶

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(error2))}},


                        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(error2))}/.style={


                            column name=slopes $L_2$,


                            fixed,fixed
                    zerofill,


                            precision=1}}

/pgfplots/table/every odd row(style, no value) ¶

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$.

/pgfplots/table/every head row(style, no value) ¶

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/colors.

/pgfplots/table/every first row(style, no value) ¶

A style which is installed for each first data row, i.e. after the head row.

/pgfplots/table/every last row(style, no value) ¶

A style which is installed for each last row.

/pgfplots/table/every row no index(style, no value) ¶

A style which is installed for the row with index (math image) index.

/pgfplots/table/every nth row={ (math image) integer}{options} ¶

/pgfplots/table/every nth row={ (math image) integer[shift]}{options}

This allows to install (math image) options for every $n$th row with $n=$integer.

Only data rows are considered for every nth row; it will never apply to column names and data rows are numbered like $i=0,1,2,\dotsc $ (the example above applies it to the rows with $a = 3,6$). Since the case $i=0$ can be handled by every first row, it is not considered for every nth row.

The second syntax allows to provide an additional (math image) shift:

Here, the style is applied to rows $i=1,4,7,10$ (mathematically, it is applied if $(i \mod n) = $ (math image) shift). The shift can be negative.

You can define many every nth row styles, they are processed in the order of occurrence (consider using before row/.add={ (math image) before existing}{after existing} to modify an existing value).

Note that every nth row/.style 2 args=... is the same as every nth row=....

/pgfplots/table/output empty row(style, no value) ¶

A style which suppresses output for the current row.

This style is evaluated very late, after all column-specific content modifications have been applied. It is equivalent to


                    \pgfplotstableset{


                        output empty row/.style={


                            typeset cell/.style={@cell content={}}

}, }

See every head row for an application.

6.1.4Configuring Single Cell Appearance: Styles¶

Besides the possibilities to change column styles and row styles, there are also a couple of styles to change single cells.

/pgfplots/table/every row rowindex column colindex(style, no value) ¶

A style which applies to at most one cell: the one with row index (math image) rowindex and column index colindex. Each of these indices starts with $0$.

The style is evaluated in the same context as the preproc cell content, assign cell content, and postproc cell content keys and it is a legitimate possibility to modify any of these parameters. It is also possible to replace the initial cell value by assigning something to @cell content.

For example, consider this unmodified table:

Now, we change the number format of one of its cells, and at the same time we change the formatting of another (single) cell:

Note that this style is (only) applied to input row/column values.

/pgfplots/table/every row no rowindex column no colindex(style, no value) ¶

This is actually the same – row no and row are both supported, the same for column and column no.

/pgfplots/table/every row rowindex column colname(style, no value) ¶

A similar style as above, but it allows column names rather than column indices. Column names need to be provided in the same way as for other column-specific styles (including the extra curly braces in case (math image) colname contains special characters).

Our example from above can thus become:

The example employs the string replace* preprocessor style and the preproc/expr style. All preprocessor or postprocessor styles can be used.

Please refer to Section 6.2 for predefined choices.

6.1.5Customizing 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 outfiles (see also write to macro). Furthermore, the generated code can be fine–tuned to provide other sorts of table output, beyond LaTeX.

/pgfplots/table/every table={ (math image) file name} ¶

A style which is installed at the beginning of every \pgfplotstabletypeset command.¹⁰³

The table file name is given as first argument.

/pgfplots/table/font={ (math image) font name} (initially empty) ¶

Assigns a font used for the complete table.

/pgfplots/table/begin table={ (math image) code} (initially \begin{tabular}) ¶

Contains { (math image) code} which is generated as table start.

The following example uses a longtable instead of tabular:


                    \pgfplotstableset{


                        begin table=\begin{longtable},


                        end table=\end{longtable},

}

Note that longtable allows the use of replicated headers for multi-page tables by means of its \endhead macro:


                    % replicate column names on top of every page of a
                    multi-page table:


                    \pgfplotstableset{


                        row sep=\\,


                        begin table=\begin{longtable},


                        end table=\end{longtable},


                        every head row/.append style={after row=\endhead},

}

If the first page should have a different header, you can use \endfirsthead provided by the longtable package:


                    % replicate column names on top of every page of a
                    multi-page table,

% but with different values for first page:


                    \pgfplotstableset{


                        row sep=\\,


                        begin table=\begin{longtable},


                        end table=\end{longtable},


                        every head row/.append style={after row={%


                                \caption{The
                    caption}%


                                \endfirsthead


                                \multicolumn{3}{c}{{\bfseries \tablename\ \thetable{} --
                    continued from previous page}} \\


                                \endhead

},

}, }

The preceding example uses the longtable macros \caption, \endfirsthead, \thetable, and \endhead. In addition, it requires to provide the number of columns ({3} in this case) explicitly.

It is also possible to change the value of begin table. For example,


                    \pgfplotstableset{


                        begin table/.add={}{[t]},

}

prepends the empty string {} and appends the prefix [t]. Thus, ‘\begin{tabular}’ becomes ‘\begin{tabular}[t]’.

/pgfplots/table/end table={ (math image) code} (initially \end{tabular}) ¶

Contains (math image) code which is generated as table end.

/pgfplots/table/typeset cell/.code={...} ¶

A code key which assigns /pgfplots/table/@cell content to the final output of the current cell.

The first argument, #1, is the final cell’s value. After this macro, the value of @cell content will be written to the output.

The default implementation is


                    /pgfplots/table/typeset
                    cell/.code={%


                        \ifnum\c@pgfplotstable@colindex=\c@pgfplotstable@numcols\relax


                            \pgfkeyssetvalue{/pgfplots/table/@cell
                    content}{#1\\}%

\else


                            \pgfkeyssetvalue{/pgfplots/table/@cell
                    content}{#1&}%

\fi },

Attention:

The value of \pgfplotstablecol starts with $1$ in this context, i.e. it is in the range $1,\dotsc ,n$ where $n=$ \pgfplotstablecols. This simplifies checks whether we have the last column.

/pgfplots/table/outfile={ (math image) file name} (initially empty) ¶

Writes the generated tabular code into (math image) file name. It can then be used with \input{file name}, PgfplotsTable is no longer required since it contains a completely normal tabular.

and pgfplotstable.example1.out.tex contains

\begin {tabular}{cc}%
dof&error1\\%
\pgfutilensuremath {4}&\pgfutilensuremath {0.25}\\%
\pgfutilensuremath {16}&\pgfutilensuremath {6.25\cdot 10^{-2}}\\%
\pgfutilensuremath {64}&\pgfutilensuremath {1.56\cdot 10^{-2}}\\%
\pgfutilensuremath {256}&\pgfutilensuremath {3.91\cdot 10^{-3}}\\%
\pgfutilensuremath {1{,}024}&\pgfutilensuremath {9.77\cdot 10^{-4}}\\%
\pgfutilensuremath {4{,}096}&\pgfutilensuremath {2.44\cdot 10^{-4}}\\%
\pgfutilensuremath {16{,}384}&\pgfutilensuremath {6.1\cdot 10^{-5}}\\%
\pgfutilensuremath {65{,}536}&\pgfutilensuremath {1.53\cdot 10^{-5}}\\%
\pgfutilensuremath {2.62\cdot 10^{5}}&\pgfutilensuremath {3.81\cdot 10^{-6}}\\%
\pgfutilensuremath {1.05\cdot 10^{6}}&\pgfutilensuremath {9.54\cdot 10^{-7}}\\%
\end {tabular}%

The command \pgfutilensuremath checks whether math mode is active and switches to math mode if necessary.¹⁰⁴

/pgfplots/table/include outfiles={ (math image) boolean} (initially false) ¶

If enabled, any already existing outfile will be \input instead of overwritten.


                    \pgfplotstableset{include outfiles} % for example in the document's preamble

This allows to place any corrections manually into generated output files since PgfplotsTable won’t overwrite the resulting tables automatically.

This will affect tables for which the outfile option is set. If you wish to apply it to every table, consider


                    \pgfplotstableset{every table/.append style={outfile={#1.out}}}

which will generate an outfile name for every table.

/pgfplots/table/force remake={ (math image) boolean} (initially false) ¶

If enabled, the effect of include outfiles is disabled. As all key settings only last until the next brace (or \end (math image) ), this key can be used to regenerate some output files while others are still included.

/pgfplots/table/write to macro={ (math image) \macroname} ¶

If the value of write to macro is not empty, the completely generated (tabular) code will be written into the macro (math image) \macroname.

See the typeset=false key in case you need only the resulting macro.

/pgfplots/table/skip coltypes=true|false (initially false) ¶

Allows to skip the (math image) coltypes in \begin{tabular}{coltypes}. This allows simplifications for other table types which don’t have LaTeX’s table format.

/pgfplots/table/typeset=true|false (initially true) ¶

A boolean which disables the final typesetting stage. Use typeset=false in conjunction with write to macro if only the generated code is of interest and TeX should not attempt to produce any content in the output pdf.

/pgfplots/table/debug={ (math image) boolean} (initially false) ¶

If enabled, it will write every final tabular code to your logfile.

/pgfplots/table/TeX comment={ (math image) comment sign} (initially %) ¶

The comment sign which is inserted into outfiles to suppress trailing white space.

As a last example, we use PgfplotsTable to write an .html file (including number formatting and rounding!):

¹⁰³ The every table style is installed after options provided to \pgfplotstabletypeset; it has higher precedence.

¹⁰⁴ Please note that \pgfutilensuremath needs to be replaced by \ensuremath if you want to use the output file independent of pgf. That can be done by \let\pgfutilensuremath=\ensuremath which enables the LaTeX command \ensuremath.

6.1.6Defining Column Types for `tabular`¶

Besides input of text files, it is sometimes desirable to define column types for existing tabular environments.

\newcolumntype{ (math image) letter}[number of arguments]$>${before column}column type$<${after column} ¶

The command \newcolumntype is part of the array package and it defines a new column type (math image) letter for use in LaTeX tabular environments.

\usepackage{array}

Now, the environment pgfplotstablecoltype can be used in (math image) before column and after column to define numerical columns:

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.

6.1.7Number Formatting Options¶

The following extract of the PGF/TikZ manual explains how to configure number formats. The common option prefix /pgf/number format can be omitted; it will be recognized automatically.

All these number formatting options can also be applied to pgfplots.

\pgfmathprintnumber{ (math image) x}

Generates pretty-printed output for the (real) number (math image) x. The input number 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[ (math image) options]{x}.

\pgfmathprintnumberto{ (math image) x}{\macro} ¶

Returns the resulting number into (math image) \macro instead of typesetting it directly.

/pgf/number format/fixed(no value) ¶

Configures \pgfmathprintnumber to round the number to a fixed number of digits after the period, discarding any trailing zeros.

See Section 6.1.7.1 for how to change the appearance.

/pgf/number format/fixed zerofill={ (math image) boolean} (default true) ¶

Enables or disables zero filling for any number drawn in fixed point format.

This key affects numbers drawn with fixed or std styles (the latter only if no scientific format is chosen).

See Section 6.1.7.1 for how to change the appearance.

/pgf/number format/sci(no value) ¶

Configures \pgfmathprintnumber to display numbers in scientific format, that means sign, mantissa and exponent (base $10$). The mantissa is rounded to the desired precision (or sci precision, see below).

See Section 6.1.7.1 for how to change the exponential display style.

/pgf/number format/sci zerofill={ (math image) boolean} (default true) ¶

Enables or disables zero filling for any number drawn in scientific format.

As with fixed zerofill, this option does only affect numbers drawn in sci format (or std if the scientific format is chosen).

See Section 6.1.7.1 for how to change the exponential display style.

/pgf/number format/zerofill={ (math image) boolean} (style, default true) ¶

Sets both fixed zerofill and sci zerofill at once.

/pgf/number format/std(no value) ¶

/pgf/number format/std= (math image) lower e

/pgf/number format/std= (math image) lower e:upper e

Configures \pgfmathprintnumber to a standard algorithm. It chooses either fixed or 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 fixed format. Otherwise, it is displayed using sci format.

The parameters can be customized using the optional integer argument(s): if $\text {\meta {lower e}} \le e \le \text {\meta {upper e}}$, the number is displayed in fixed format, otherwise in sci format. Note that (math image) lower e should be negative for useful results. The precision used for scientific format can be adjusted with sci precision if necessary.

/pgf/number format/relative*= (math image) exponent base 10 ¶

Configures \pgfmathprintnumber to format numbers relative to an order of magnitude, $10^r$, where $r$ is an integer number.

This key addresses different use-cases.

First use-case:

provide a unified format for a sequence of numbers. Consider the following test:

With any other style, the 6.42e-16 would have been formatted as an isolated number. Here, it is rounded to 0 because when viewed relative to $10^1$ (the exponent $1$ is the argument for relative), it has no significant digits.

The example above applies the initial precision=2 to 123.345 – relative to $100$. Two significant digits of 123.345 relative to $100$ are 123. Note that the “$2$ significant digits of 123.345” translates to “round 1.2345 to $2$ digits”, which would yield 1.2300. Similarly, the other two numbers are 0 compared to $100$ using the given precision.

Second use-case:

improve rounding in the presence of inaccurate numbers. Let us suppose that some limited-precision arithmetics resulted in the result 123456999 (like the fpu of pgf). You know that its precision is about five or six significant digits. And you want to provide a fixed point output. In this case, the trailing digits ....999 are a numerical artifact due to the limited precision. Use relative*=3,precision=0 to eliminate the artifacts:

Here, precision=0 means that we inspect 123456.999 and round that number to $0$ digits. Finally, we move the period back to its initial position. Adding relative style=fixed results in fixed point output format:

Note that there is another alternative for this use-case which is discussed later: the fixed relative style.

You might wonder why there is an asterisk in the key’s name. The short answer is: there is also a /pgf/number format/relative number printer which does unexpected things. The key relative* repairs this. Existing code will still use the old behavior.

Technically, the key works as follows: as already explained above, relative*=3 key applied to 123456999.12 moves the period by three positions and analyzes 123456.99912. Mathematically speaking, we are given a number $x = \pm m \cdot 10^e$ and we attempt to apply relative*=$r$. The method then rounds $x / 10^r$ to precision digits. Afterwards, it multiplies the result by $10^r$ and typesets it.

/pgf/number format/every relative(style, no value) ¶

A style which configures how the relative method finally displays its results.

The initial configuration is


                    \pgfkeys{/pgf/number format/every relative/.style=std}

Note that rounding is turned off when the resulting style is being evaluated (since relative already rounded the number).

Although supported, I discourage from using fixed zerofill or sci zerofill in this context – it may lead to a suggestion of higher precision than is actually used (because fixed zerofill might simply add .00 although there was a different information before relative rounded the result).

/pgf/number format/relative style={ (math image) options} ¶

The same as every relative/.append style={ (math image) options}.

/pgf/number format/fixed relative(no value) ¶

Configures \pgfmathprintnumber to format numbers in a similar way to the fixed style, but the precision is interpreted relatively to the number’s exponent.

The motivation is to get the same rounding effect as for sci, but to display the number in the fixed style:

The effect of fixed relative is that the number is rounded to exactly the first (math image) precision non-zero digits, no matter how many leading zeros the number might have.

Use fixed relative if you want fixed and if you know that only the first $n$ digits are correct. Use sci if you need a scientific display style and only the first $n$ digits are correct.

Note that fixed relative ignores the fixed zerofill flag.

See also the relative* key. Note that the relative={ (math image) exponent} key explicitly moves the period to some designated position before it attempts to round the number. Afterwards, it “rounds from the right”, i.e. it rounds to that explicitly chosen digit position. In contrast to that, fixed relative “rounds from the left”: it takes the first non-zero digit, temporarily places the period after this digit, and rounds that number. The rounding style fixed leaves the period where it is, and rounds everything behind that digit. The sci style is similar to fixed relative.

/pgf/number format/int detect(no value) ¶

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.

\pgfmathifisint{ (math image) number constant}{true code}{false code} ¶

A command which does the same check as int detect, but it invokes (math image) true code if the number constant actually is an integer and the false code if not.

As a side-effect, \pgfretval will contain the parsed number, either in integer format or as parsed floating point number.

The argument (math image) number constant will be parsed with \pgfmathfloatparsenumber.

/pgf/number format/int trunc(no value) ¶

Truncates every number to integers (discards any digit after the period).

/pgf/number format/frac(no value) ¶

Displays numbers as fractionals.

/pgf/number format/frac TeX={ (math image) \macro} (initially \frac) ¶

Allows to use a different implementation for \frac inside of the frac display type.

/pgf/number format/frac denom= (math image) int (initially empty) ¶

Allows to provide a custom denominator for frac.

/pgf/number format/frac whole=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.

/pgf/number format/frac shift={ (math image) integer} (initially 4) ¶

In case you experience 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$.

/pgf/number format/precision={ (math image) number} ¶

Sets the desired rounding precision for any display operation. For scientific format, this affects the mantissa.

/pgf/number format/sci precision= (math image) number or empty (initially empty) ¶

Sets the desired rounding precision only for sci styles.

Use sci precision={} to restore the initial configuration (which uses the argument provided to precision for all number styles).

/pgf/number format/read comma as period=true|false (initially false) ¶

This is one of the few keys which allows to customize the number parser. If this switch is turned on, a comma is read just as a period.

This is typically undesired as it can cause side-effects with math parsing instructions. However, it is supported to format input numbers or input tables. Consider use comma to typeset the result with a comma as well.

Note:

this key requires a pgf version which is more recent than pgf 3.0.0.

6.1.7.1Changing Number Format Display Styles¶

You can change the way how numbers are displayed. For example, if you use the ‘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.

/pgf/number format/set decimal separator={ (math image) text} ¶

Assigns (math image) text as decimal separator for any fixed point number (including the mantissa in sci format).

/pgf/number format/dec sep={ (math image) text} ¶

Just another name for set decimal separator.

/pgf/number format/set thousands separator={ (math image) text} ¶

Assigns (math image) text as thousands separator for any fixed point number (including the mantissa in sci format).

The last example employs commas and disables the default comma-spacing.

/pgf/number format/1000 sep={ (math image) text} ¶

Just another name for set thousands separator.

/pgf/number format/1000 sep in fractionals={ (math image) boolean} (initially false) ¶

Configures whether the fractional part should also be grouped into groups of three digits.

The value true will activate the 1000 sep for both integer and fractional parts. The value false will activate 1000 sep only for the integer part.

/pgf/number format/min exponent for 1000 sep={ (math image) number} (initially 0) ¶

Defines the smallest exponent in scientific notation which is required to draw thousand separators. The exponent is the number of digits minus one, so $\meta {number}=4$ will use thousand separators starting with $1e4 = 10000$.

A value of 0 disables this feature (negative values are ignored).

/pgf/number format/use period(no value) ¶

A predefined style which installs periods ‘.’ as decimal separators and commas ‘,’ as thousands separators. This style is the default.

/pgf/number format/use comma(no value) ¶

A predefined style which installs commas ‘,’ as decimal separators and periods ‘.’ as thousands separators.

/pgf/number format/skip 0.={ (math image) boolean} (initially false) ¶

Configures whether numbers like $0.1$ shall be typeset as $.1$ or not.

/pgf/number format/showpos={ (math image) boolean} (initially false) ¶

Enables or disables display of plus signs for non-negative numbers.

/pgf/number format/print sign={ (math image) boolean} ¶

A style which is simply an alias for showpos= (math image) boolean.

/pgf/number format/sci 10e(no value) ¶

Uses $m \cdot 10^e$ for any number displayed in scientific format.

/pgf/number format/sci 10^e(no value) ¶

The same as ‘sci 10e’.

/pgf/number format/sci e(no value) ¶

Uses the ‘$1e{+}0$’ format which is generated by common scientific tools for any number displayed in scientific format.

/pgf/number format/sci E(no value) ¶

The same with an uppercase ‘E’.

/pgf/number format/sci subscript(no value) ¶

Typesets the exponent as subscript for any number displayed in scientific format. This style requires very little space.

/pgf/number format/sci superscript(no value) ¶

Typesets the exponent as superscript for any number displayed in scientific format. This style requires very little space.

/pgf/number format/sci generic={ (math image) keys} ¶

Allows to define a custom number style for the scientific format. Here, (math image) keys can be one of the following choices (omit the long key prefix):

/pgf/number format/sci generic/mantissa sep={ (math image) text} (initially empty) ¶

Provides the separator between the mantissa and the exponent. It might be \cdot, for example,

/pgf/number format/sci generic/exponent={ (math image) text} (initially empty) ¶

Provides text to format the exponent. The actual exponent is available as argument #1 (see below).

The (math image) keys can depend on three parameters, namely on #1 which is the exponent, #2 containing the flags entity of the floating point number and #3 is the (unprocessed and unformatted) mantissa.

Note that sci generic is not suitable to modify the appearance of fixed point numbers, nor can it be used to format the mantissa (which is typeset like fixed point numbers). Use dec sep, 1000 sep and print sign to customize the mantissa.

/pgf/number format/retain unit mantissa=true|false (initially true) ¶

Allows to omit a unit mantissa.

The feature is applied after rounding to the desired precision: if the remaining mantissa is equal to $1$, it will be omitted. It applies to all styles involving the scientific format (including std).

/pgf/number format/@dec sep mark={ (math image) text} ¶

Will be placed right before the place where a decimal separator belongs to. However, (math image) text will be inserted even if there is no decimal separator. It is intended as place-holder for auxiliary routines to find alignment positions.

This key should never be used to change the decimal separator! Use dec sep instead.

/pgf/number format/@sci exponent mark={ (math image) text} ¶

Will be placed right before exponents in scientific notation. It is intended as place-holder for auxiliary routines to find alignment positions.

This key should never be used to change the exponent!

/pgf/number format/assume math mode={ (math image) 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.

/pgf/number format/verbatim(style, no value) ¶

A style which configures the number printer to produce verbatim text output, i.e. it doesn’t contain TeX macros.

The style resets 1000 sep, dec sep, print sign, skip 0. and sets assume math mode. Furthermore, it installs a sci generic format for verbatim output of scientific numbers.

However, it will still respect precision, fixed zerofill, sci zerofill and the overall styles fixed, sci, int detect (and their variants). It might be useful if you intend to write output files.

Manual for Package pgfplots 2D/3D Plots in LATeX, Version 1.18.1 http://sourceforge.net/projects/pgfplots