tikz.dev / PGFplots Manual

Manual for Package pgfplots
2D/3D Plots in LA, Version 1.18.1
http://sourceforge.net/projects/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.4Miscellaneous

6.4.1Writing (Modified) Tables To Disk
  • /pgfplots/table/outfile={(math image)file name(math image)} (initially empty)

  • Writes the completely processed table as file to (math image)file name(math image). This key is described in all detail on page (page for section 6.1.5).

  • \pgfplotstablesave[(math image)options(math image)]{(math image)\macro or input file name(math image)}{(math image)output file name(math image)}

  • This command takes a table and writes it to a new data file (without performing any typesetting).

    If the first argument is a file name, that file is loaded first.

    This command simply invokes \pgfplotstabletypeset with cleared output parameters. That means any of the column creation methods apply here as well, including any postprocessing steps (without the final typesetting).

    \pgfplotstablesave uses the keys reset styles and disable rowcol styles to clear any typesetting related options.

    Furthermore, it sets string type to allow verbatim output. You may want to use numeric as string type instead in case you only have numerical data – this will display integers resulting from arithmetics not in scientific notation.109

    \pgfplotstablesave[ create on use/postproc1/.style={create col/dyadic refinement rate=error1}, columns={dof,error1,postproc1} ] {pgfplotstable.example1.dat} {pgfplotstable.example1.out.dat}

    Now, pgfplotstable.example1.out.dat is

    dof error1 postproc1
    4 2.50000000e-01 {}
    16 6.25000000e-02 1.99998
    64 1.56250000e-02 1.99998
    256 3.90625000e-03 1.99998
    1024 9.76562500e-04 1.99998
    4096 2.44140625e-04 1.99998
    16384 6.10351562e-05 1.99998
    65536 1.52587891e-05 1.99998
    262144 3.81469727e-06 1.99998
    1048576 9.53674316e-07 1.99998
    

    You can use the col sep key inside of (math image)options(math image) to define a column separator for the output file. In case you need a different input column separator, use in col sep instead of col sep.

Remarks

109 Note however, that string type does not round or truncate integers either, even though they are displayed as floats.

6.4.2Miscellaneous Keys
  • /pgfplots/table/disable rowcol styles=true|false (initially false)

  • Set this to true if \pgfplotstabletypeset shall not set any styles which apply only to specific columns or only to specific rows.

    This disables the styles

    • columns/(math image)column name(math image),

    • display columns/(math image)column index(math image),

    • every col no (math image)column index(math image),

    • every row no (math image)row index(math image).

6.4.3A summary of how to define and use styles and keys

This section summarizes features of pgfkeys. The complete documentation can be found in the PGF/TikZ manual.

  • Key handler (math image)key(math image)/.style={(math image)key-value-list(math image)}

  • Defines or redefines a style (math image)key(math image). A style is a normal key which will set all options in (math image)key-value-list(math image) when it is set.

    Use \pgfplotstableset{(math image)key(math image)/.style={(math image)key-value-list(math image)}} to (re)define a style (math image)key(math image) in the namespace /pgfplots/table.

  • Key handler (math image)key(math image)/.append style={(math image)key-value-list(math image)}

  • Appends (math image)key-value-list(math image) to an already existing style (math image)key(math image). This is the preferred method to change the predefined styles: if you only append, you maintain compatibility with future versions.

    Use \pgfplotstableset{(math image)key(math image)/.append style={(math image)key-value-list(math image)}} to append (math image)key-value-list(math image) to the style (math image)key(math image). This will assume the prefix /pgfplots/table.

  • Key handler (math image)key(math image)/.initial={(math image)value(math image)}

  • Defines a new (math image)key(math image) and assigns (math image)value(math image).

  • Key handler (math image)key(math image)/.code={(math image) code(math image)}

  • Occasionally, the pgfplots user interface offers to replace parts of its routines. This is accomplished using so called “code keys”. What it means is to replace the original key and its behavior with new (math image) code(math image). Inside of (math image) code(math image), any command can be used. Furthermore, the #1 pattern will be the argument provided to the key.

    (image)

    \pgfplotsset{ My Code/.code={This is a pgfkeys feature. Argument=`#1'}} \pgfplotsset{My Code={is here}}

    The example defines a (new) key named My Code. Essentially, it is nothing else but a \newcommand, plugged into the key–value interface. The second statement “invokes” the code key.

  • Key handler (math image)key(math image)/.append code={(math image) code(math image)}

  • Appends (math image) code(math image) to an already existing /.code key named (math image)key(math image).

  • Key handler (math image)key(math image)/.code 2 args={(math image) code(math image)}

  • As /.code, but this handler defines a key which accepts two arguments. When the so defined key is used, the two arguments are available as #1 and #2.

6.4.4Plain and Cont support

The table code generator is initialized to produce 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 or Cont commands to change it. If you have useful default styles (or bug reports), let me know.

6.4.5Basic Level Table Access and Modification

PgfplotsTable provides several methods to access and manipulate tables at an elementary level.

Please keep in mind that PgfplotsTable has been written as a tool for table visualization. As such, it has been optimized for the case of relatively few rows (although it may have a lot of columns). The runtime for table creation and modification is currently \(O(N^2)\) where \(N\) is the number of rows.110 This is completely acceptable for tables with few rows because can process those structures relatively fast. Keep your tables small! PgfplotsTable is not a tool for large-scale matrix operations.

Tables are always stored as a sequence of column vectors. Therefore, iteration over all values in one column is simple whereas iteration over all values in one row is complicated and expensive.

  • \pgfplotstableforeachcolumn(math image)table(math image)\as{(math image)\macro(math image)}{(math image)code(math image)}

  • Iterates over every column name of (math image)table(math image). The (math image)\macro(math image) will be set to the currently visited column name. Then, (math image)code(math image) will be executed. During (math image)code(math image), \pgfplotstablecol denotes the current column index (starting with 0).

    (image)

    \begin{minipage}{0.8\linewidth} \pgfplotstableread{pgfplotstable.example1.dat}\loadedtable \pgfplotstableforeachcolumn\loadedtable\as\col{% column name is `\col'; index is \pgfplotstablecol;\par } \end{minipage}

    This routine does not introduce groups, variables inside of (math image)code(math image) are not scoped.

  • \pgfplotstableforeachcolumnelement(math image)column name(math image)\of(math image)table(math image)\as(math image)\cellcontent(math image){(math image)code(math image)}

  • Reports every table cell \(t_{ij}\) for a fixed column \(j\) in read-only mode.

    For every cell in the column named (math image)column name(math image), (math image)code(math image) will be executed. During this invocation, the macro (math image)\cellcontent(math image) will contain the cell’s content and \pgfplotstablerow will contain the current row’s index.

    (image)

    \begin{minipage}{0.8\linewidth} \pgfplotstableread{pgfplotstable.example1.dat}\loadedtable \pgfplotstableforeachcolumnelement{error1}\of\loadedtable\as\cell{% I have now cell element `\cell' at row index `\pgfplotstablerow';\par } \end{minipage}

    The argument (math image)column name(math image) can also be a column index. In that case, it should contain [index](math image)integer(math image), for example [index]4. Furthermore, column aliases and columns which should be generated on the fly (see create on use) can be used for (math image)column name(math image).

    This routine does not introduce groups, variables inside of (math image)code(math image) are not scoped.

  • \pgfplotstablegetelem{(math image)row(math image)}{(math image)col(math image)}\of(math image)table(math image)

  • Selects a single table element at row (math image)row(math image) and column (math image)col(math image). The second argument has the same format as that described in the last paragraph: it should be a column name or a column index (in which case it needs to be written as [index](math image)number(math image)).

    The return value will be written to \pgfplotsretval.

    (image)

    \pgfplotstableread{pgfplotstable.example1.dat}{\loadedtable} \pgfplotstablegetelem{4}{error1}\of{\loadedtable} The value (4,error1) is `\pgfplotsretval'. \pgfplotstablegetelem{2}{[index]0}\of{\loadedtable} The value (2,0) is `\pgfplotsretval'.

Attention:

If possible, avoid using this command inside of loops. It is quite slow.

  • \pgfplotstablegetcolumnnamebyindex{(math image)col index(math image)}\of(math image)table(math image)\to(math image)macro(math image)

  • Retrieves the column name at (math image)col index(math image) from a (math image)table(math image) and stores it into a (math image)macro(math image).

    (image)

    \pgfplotstableread{pgfplotstable.example1.dat}{\loadedtable} \pgfplotstablegetcolumnnamebyindex{4}\of{\loadedtable}\to\pgfplotsretval The name of column 4 `\pgfplotsretval'.

    Note that (math image)table(math image) must be a loaded table, i.e. it must be a macro resulting from \pgfplotstableread. Column indices start at \(0\).

  • \pgfplotstablegetrowsof{(math image)file name or \loadedtable(math image)}

  • \pgfplotstablegetcolsof{(math image)file name or \loadedtable(math image)}

  • Defines \pgfplotsretval to be the number of rows or columns respectively in a table.111 The argument may be either a file name or an already loaded table (the (math image)\macro(math image) of \pgfplotstableread).

  • \pgfplotstablevertcat{(math image)\table1(math image)}{(math image)\table2 or filename(math image)}

  • See page (page for section 6.3.1) for details about this command.

  • \pgfplotstablenew[(math image)options(math image)]{(math image)row count(math image)}{(math image)\table(math image)}

  • See Section 6.3 for details about this command.

  • \pgfplotstablecreatecol[(math image)options(math image)]{(math image)row count(math image)}{(math image)\table(math image)}

  • See Section 6.3 for details about this command.

  • \pgfplotstabletranspose[(math image)options(math image)]{(math image)\outtable(math image)}{(math image)\table or filename(math image)}

  • \pgfplotstabletranspose*[(math image)options(math image)]{(math image)\outtable(math image)}{(math image)\table or filename(math image)}

  • Defines (math image)\outtable(math image) to be the transposed of (math image)\table of filename(math image). The input argument can be either a file name or an already loaded table.

    The version with ‘*’ is only interesting in conjunction with the columns option, see below.

    (image)

    \pgfplotstabletypeset[string type]{pgfplotstable.example3.dat}

    (image)

    \pgfplotstabletranspose\loadedtable{pgfplotstable.example3.dat} \pgfplotstabletypeset[string type]\loadedtable

    The optional argument (math image)options(math image) can contain options which influence the transposition:

    • /pgfplots/table/colnames from={(math image)colname(math image)} (initially empty)

    • Inside of \pgfplotstabletranspose, this key handles how to define output column names.

      If (math image)colname(math image) is empty (the initial value), the output column names will simply be the old row indices, starting with \(0\).

      If (math image)colname(math image) is not empty, it denotes an input column name whose cell values will make up the output column names:

      (image)

      \pgfplotstabletranspose[colnames from=c]\loadedtable{pgfplotstable.example3.dat} \pgfplotstabletypeset[string type]\loadedtable

      The argument (math image)colname(math image) won’t appear as cell contents. It is an error if the cells in (math image)colname(math image) don’t yield unique column names.

    • /pgfplots/table/columns={(math image)list(math image)} (initially empty)

    • Inside of \pgfplotstabletranspose, this key handles which input columns shall be considered for the transposition.

      If (math image)list(math image) is empty, all columns of the input table will be used (which is the initial configuration).

      If (math image)list(math image) is not empty, it is expected to be a list of column names. Only these columns will be used as input for the transposition, just as if the remaining ones weren’t there. It is acceptable to provide column aliases or create on use arguments inside of (math image)list(math image).

      (image)

      \pgfplotstabletranspose[columns={a,b}]\loadedtable{pgfplotstable.example3.dat} \pgfplotstabletypeset[string type]\loadedtable

      Here is the only difference between \pgfplotstabletranspose and \pgfplotstabletranspose*: the version without ‘*resets the columns key before it starts whereas the version with ‘*’ simply uses the actual content of columns.

  • \pgfplotstablesort[(math image)options(math image)](math image)\resulttable(math image)(math image)\table or filename(math image)

  • Sorts (math image)\table or filename(math image) according to (math image)options(math image) and writes the sorted table to (math image)\resulttable(math image).

    Use the high level sort key to enable sorting automatically during \pgfplotstabletypeset.

    (image)

    \pgfplotstablesort\result{% a b c 19 2 [a] -6 -14 [b] 4 -14 [c] -11 -9 [d] 11 14 [e] -9 -9 [f] 1 13 [g] 8 -10 [h] 16 18 [i] 19 -6 [j] } \pgfplotstabletypeset[columns/c/.style={string type}]{\result}%

    The sort key and comparison function can be customized using the following keys:

    • /pgfplots/table/sort key={(math image)column(math image)} (initially [index]0)

    • Specifies the column which contains the sort key. The argument (math image)column(math image) can be any of the columns of the input table, including create on use, alias or [index](math image)integer(math image) specifications. The initial setting uses the first available column.

    • /pgfplots/table/sort key from={(math image)table(math image)} (initially empty)

    • Allows to load the sort key from a different (math image)table(math image), which can be either a (math image)\macro(math image) or a (math image)file name(math image).

    • /pgfplots/table/sort cmp={(math image)less than routine(math image)} (initially float <)

    • Allows to use a different comparison function.

      • /pgfplots/fixed <(no value)

      • /pgfplots/fixed >(no value)

      • /pgfplots/int <(no value)

      • /pgfplots/int >(no value)

      • /pgfplots/float <(no value)

      • /pgfplots/float >(no value)

      • /pgfplots/date <(no value)

      • /pgfplots/date >(no value)

      • /pgfplots/string <(no value)

      • /pgfplots/string >(no value)

      • These styles constitute the predefined comparison functions. The fixed <, int < and float < routines operate on numerical data where int < expects positive or negative integers and the other two expect real numbers. The fixed < has a considerably smaller number range, but is slightly faster than float <.

        The date < compares dates of the form YYYY-MM-DD. The string < uses lexicographical string comparison based on the ASCII character codes of the sort keys. The string < routine also evaluates ASCII codes of control sequences or active characters.112

        (image)

        \pgfplotstablesort[sort cmp=string <]\result{% 'Header' is the column name: Header the quick brown fox jumps over the lazy dog } \pgfplotstabletypeset[string type]{\result}%

      The argument (math image)less than routine(math image) is actually a style: it is supposed to be one or more keys with /pgfplots/ key prefix. Consequently, all these predefined sort comparisons are actually keys which define iflessthan. For example, we have the definition of string < as follows:

      \makeatletter \pgfplotsset{ string </.style={% iflessthan/.code args={##1##2##3##4}{% \t@pgfplots@toka=\expandafter{##1}% \t@pgfplots@tokb=\expandafter{##2}% \edef\pgfplots@loc@TMPa{{\the\t@pgfplots@toka}{\the\t@pgfplots@tokb}}% \expandafter\pgfplotsutilstrcmp\pgfplots@loc@TMPa \if1\pgfplotsretval ##3\else ##4\fi }% },% }
      • /pgfplots/iflessthan/.code args={##1##2##3##4}{(math image)...(math image)}

      • Allows to define custom comparison functions (a strict ordering). It compares #1 < #2 and invokes #3 in case the comparison is true and #4 if not. The comparison will be evaluated in local scopes (local variables are freed afterwards).

        In order to be used as value for sort cmp, the iflessthan routine needs to be defined inside of the value sort cmp=(math image)less than routine(math image):

        \pgfplotsset{ sort cmp={ iflessthan/.code args={#1#2#3#4}{% % here comes your code }% }, }

110 The runtime for plot table is linear in the number of rows using a special routine.

111 It will also assign \pgfmathresult to the same value.

112 As long as they haven’t been consumed by ’s preprocessing.

6.4.6Repeating Things: Loops

The following loop commands come with pgfplots. They are similar to the powerful TikZ \foreach loop command, which, however, is not always useful for table processing: the effect of its loop body end after each iteration.

The following pgfplots looping macros are an alternative.

  • \pgfplotsforeachungrouped(math image)variable(math image) in (math image)list(math image) {(math image)command(math image)}

  • A specialized variant of \foreach which can do two things: it does not introduce extra groups while executing (math image)command(math image) and it allows to invoke the math parser for (simple!) (math image)\(x_0\)(math image),(math image)\(x_1\)(math image),...,(math image)\(x_n\)(math image) expressions.

    (image)

    \def\allcollected{} \pgfplotsforeachungrouped \x in {1,2,...,4} {Iterating \x. \edef\allcollected{\allcollected, \x}}% All collected = \allcollected.

    A more useful example might be to work with tables:

    \pgfplotsforeachungrouped \i in {1,2,...,10} {% \pgfplotstablevertcat{\output}{datafile\i} % appends `datafile\i' -> `\output' }% % since it was ungrouped, \output is still defined (would not work % with \foreach)

Remark:

The special syntax (math image)list(math image)=(math image)\(x_0\)(math image),(math image)\(x_1\)(math image),...,(math image)\(x_n\)(math image), i.e. with two leading elements, followed by dots and a final element, invokes the math parser for the loop. Thus, it allows larger number ranges than any other syntax if /pgf/fpu is active. In all other cases, \pgfplotsforeachungrouped invokes \foreach and provides the results without groups.

Restrictions:

You cannot nest this command yet (since it does not introduce protection by scopes).