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} (initially empty)

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

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

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.¹⁰⁹

\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 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

• Empty cells will be filled with {} if col sep=space. Use the empty cells with style to change that.
• Use disable rowcol styles=false inside of options if you need to change column/row based styles.

¹⁰⁹ 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/column name,
• display columns/column index,
• every col no column index,
• every row no row index.

/pgfplots/table/reset styles(no value) ¶

Resets all table typesetting styles which do not explicitly depend on column or row names and indices. The affected styles are

• every table,
• every even row, every odd row, every column, every even column, every odd column,
• every first column, every last column, every first row, every last row,
• every head row,
• postproc cell content, preproc cell content.

In case you want to reset all, you should also consider the key disable rowcol styles.

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/.style={key-value-list}

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

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

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

Appends (math image) key-value-list to an already existing style key. 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/.append style={key-value-list}} to append key-value-list to the style key. This will assume the prefix /pgfplots/table.

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

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

Key handler (math image) key/.add={before}{after} ¶

Changes (math image) key by prepending before and appending after.

This can be used inside of \pgfplotsinvokeforeach or similar (ungrouped!) loop constructs.

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

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) TeX code. Inside of TeX code, any command can be used. Furthermore, the #1 pattern will be the argument provided to the key.

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/.append code={TeX code} ¶

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

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

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 TeX and ConTeXt support¶

The table code generator is initialized 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 ConTeXt 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.¹¹⁰ This is completely acceptable for tables with few rows because TeX 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\as{\macro}{code} ¶

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

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

\pgfplotstableforeachcolumnelement (math image) column name\oftable\as\cellcontent{code} ¶

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, code will be executed. During this invocation, the macro \cellcontent will contain the cell’s content and \pgfplotstablerow will contain the current row’s index.

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

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

\pgfplotstablemodifyeachcolumnelement (math image) column name\oftable\as\cellcontent{code} ¶

A routine which is similar to \pgfplotstableforeachcolumnelement, but any changes of (math image) \cellcontent which might occur during code will be written back into the respective cell.

If (math image) column name is a column alias or has been created on the fly, a new column named column name will be created.

\pgfplotstablegetelem{ (math image) row}{col}\oftable ¶

Selects a single table element at row (math image) row and column col. 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]number).

The return value will be written to \pgfplotsretval.

Attention:

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

\pgfplotstablegetcolumnnamebyindex{ (math image) col index}\oftable\tomacro ¶

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

Note that (math image) table 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} ¶

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

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

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

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

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

See Section 6.3 for details about this command.

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

See Section 6.3 for details about this command.

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

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

Defines (math image) \outtable to be the transposed of \table of filename. 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.

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

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

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

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

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

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

/pgfplots/table/input colnames to={ (math image) name} (initially colnames) ¶

Inside of \pgfplotstabletranspose, this key handles what to do with input column names.

This key will create a further column named (math image) name which will be filled with the input column names (as string type).

Set (math image) name to the empty string to disable this column.

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

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

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

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

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]\resulttable\table or filename ¶

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

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

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

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

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

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

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

/pgfplots/table/sort cmp={ (math image) less than routine} (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.¹¹²

The argument (math image) less than routine 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}{...} ¶

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:

\pgfplotsset{


                                sort cmp={

iflessthan/.code args={#1#2#3#4}{%


                                        % here comes your code

}% }, }

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

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

¹¹² As long as they haven’t been consumed by TeX’s preprocessing.

6.4.6Repeating Things: Loops¶

\foreach (math image) variables in list {commands} ¶

A powerful loop command provided by TikZ, see the PGF/TikZ manual, Section “Utilities”.

A pgfplots related example could be


                    \foreach \i in {1,2,...,10} {\addplot table {datafile\i}; }%

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 in list {command} ¶

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

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=\(x_0\),\(x_1\),...,\(x_n\), 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 TeX groups.

\pgfplotsinvokeforeach{ (math image) list} {command} ¶

A variant of \pgfplotsforeachungrouped (and such also of \foreach) which replaces any occurrence of #1 inside of (math image) command once for every element in list. Thus, it actually assumes that command is like a \newcommand body.

In other words, (math image) command is invoked for every element of list. The actual element of list is available as #1.

As \pgfplotsforeachungrouped, this command does not introduce extra scopes (i.e. it is ungrouped as well).

The difference to \foreach \x in (math image) list{command} is subtle: the \x would not be expanded whereas #1 is.

The counterexample would use a macro (here \x) as loop argument:

Restrictions:

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

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