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

\addplot[options] input data trailing path commands; ¶

This is the main plotting command, available within each axis environment. It can be used one or more times within an axis to add plots to the current axis. There is also an \addplot3 command which is described in Section 4.6.

It reads point coordinates from one of the available input sources specified by input data, updates limits, remembers options for use in a legend (if any) and applies any necessary coordinate transformations (or logarithms).

The options can be omitted in which case the next entry from the cycle list will be inserted as options. These keys characterize the plot’s type like linear interpolation with sharp plot, smooth plot, constant interpolation with const plot, bar plot, mesh plots, surface plots or whatever and define colors, markers and line specifications.² Plot variants like error bars, the number of samples or a sample domain can also be configured in options.

The input data is one of several coordinate input tools which are described in more detail below. Finally, if \addplot successfully processed all coordinates from input data, it generates TikZ paths to realize the drawing operations. Any trailing path commands are appended to the final drawing command, allowing to continue the TikZ path (from the last plot coordinate).

Some more details:

• • The style /pgfplots/every axis plot will be installed at the beginning of options. That means you can use

  copy \pgfplotsset{every axis plot/.append style={...}}

  to add options to all your plots – maybe to set line widths to thick. Furthermore, if you have more than one plot inside of an axis, you can also use

  copy \pgfplotsset{every axis plot no 3/.append style={...}}

  to modify options for the plot with number \(3\) only. The first plot in an axis has number \(0\).

• • The options are remembered for the legend. They are available as ‘current plot style’ as long as the path is not yet finished or in associated error bars.

• • See Section 4.7 for a list of available markers and line styles.

• • For log plots, pgfplots will compute the natural logarithm \(\log (\cdot )\) numerically using a floating point unit developed for this purpose.³ For example, the following numbers are valid input to \addplot.

  

  copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{loglogaxis} \addplot coordinates { (769, 1.6227e-04) (1793, 4.4425e-05) (4097, 1.2071e-05) (9217, 3.2610e-06) (2.2e5, 2.1E-6) (1e6, 0.00003341) (2.3e7, 0.00131415) }; \end{loglogaxis} \end{tikzpicture}

  You can represent arbitrarily small or very large numbers as long as its logarithm can be represented as a TeX length (up to about \(16384\)). Of course, any coordinate \(x\le 0\) is not possible since the logarithm of a non-positive number is not defined. Such coordinates will be skipped automatically (using the initial configuration unbounded coords=discard).

• • For normal (non-logarithmic) axes, pgfplots applies floating point arithmetics to support large or small numbers like \(0.00000001234\) or \(1.234\cdot 10^{24}\). Its number range is much larger than TeX’s native support for numbers. The relative precision is between \(4\) and \(7\) significant decimal digits for the mantissa.

  As soon as the axes limits are completely known, pgfplots applies a transformation which maps these floating point numbers into TeX precision using transformations

  \[ T_x(x) = 10^{s_x} \cdot x - a_x \text { and } T_y(y) = 10^{s_y} \cdot y - a_y \text { and (for 3D plots) } T_z(y) = 10^{s_z} \cdot z - a_z \]

  with properly chosen integers \(s_x, s_y, s_z \in \mathbb {Z}\) and shifts \(a_x,a_y, a_z\in \mathbb {R}\). Page (page for section 4.25) contains a description of disabledatascaling and provides more details about the transformation.

• • Some of the coordinate input routines use the powerful \pgfmathparse feature of pgf to read their coordinates, among them \addplot coordinates, \addplot expression and \addplot table. This allows to use mathematical expressions as coordinates which will be evaluated using the floating point routines (this applies to logarithmic and linear scales).

• • pgfplots automatically computes missing axis limits. The automatic computation of axis limits works as follows:

  • 1. Every coordinate will be checked. Care has been taken to avoid TeX’s limited numerical capabilities.

  • 2. Since more than one \addplot command may be used inside of \begin{axis}...\end{axis}, all drawing commands will be postponed until \end{axis}.

\addplot+[options] …; ¶

Does the same like \addplot[options] ...; except that options are appended to the arguments which would have been taken for \addplot ... (the element of the default list).

Thus, you can combine cycle list and options.





copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot {sin(deg(x))}; \end{axis} \end{tikzpicture} \begin{tikzpicture} \begin{axis} \addplot+ [only marks] {sin(deg(x))}; \end{axis} \end{tikzpicture}

The distinction is as follows: \addplot ... (without options) lets pgfplots select colors, markers and linestyles automatically (using cycle list). The variant \addplot+[option] ... will use the same automatically determined styles, but in addition it uses options. Finally, \addplot[options] (without the +) uses only the manually provided options.

/pgfplots/empty line=auto|none|scanline|jump (initially auto) ¶

Controls how empty lines in the input coordinate stream are to be interpreted. You should ensure that you have \pgfplotsset{compat=1.4} or newer in your preamble and leave this key at its default empty line=auto.

Empty lines can occur between the coordinates of \addplot coordinates or successive rows of the data file input routines \addplot table (and \addplot file).

The choice auto checks if the current plot type is mesh or surf. If so, it uses scanline. If the current plot type is some other plot type (like a standard line plot), it uses jump. Note that the value auto for non-mesh plots results in none if compat=1.3 or older is used. In other words: you have to write \pgfplotsset{compat=1.4} or newer to let pgfplots interpret empty lines as jump in standard line plots:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[tiny, title={Ignored: compat=1.3}, compat=1.3, ] \addplot table { A B 0 0 1 1 1 2 2 2 }; \end{axis} \end{tikzpicture} \begin{tikzpicture} \begin{axis}[tiny, title={Jump: compat=1.4}, compat=1.4, ] \addplot table { A B 0 0 1 1 1 2 2 2 }; \end{axis} \end{tikzpicture}

The choice scanline is only useful for mesh and surf: it is used to decode a matrix from a coordinate stream. If an empty line occurs once every \(N\) data points, the “scanline” length is \(N\). This information, together with mesh/ordering and the total number of points, allows to deduce the matrix size. However, the distance between empty lines has to be consistent: if the first two empty lines have a distance of \(2\) and the next comes after \(5\), pgfplots will ignore the information and will expect explicit matrix sizes using mesh/rows and/or mesh/cols. The choice scanline is ignored if mesh input=patches. It has no effect for other plot types.

The choice none will silently discard any empty line in the input stream.

The choice jump tells pgfplots to generate a jump.

\addplot coordinates {coordinate list}; ¶

\addplot[options] coordinates {coordinate list} trailing path commands; ¶

\addplot3 … ¶

The ‘\addplot coordinates’ command is like that provided by TikZ and reads its input data from a sequence of point coordinates, encapsulated in round braces.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot coordinates { (0,0) (0.5,1) (1,2) }; \end{axis} \end{tikzpicture}

You should only use this input format if you have short diagrams and you want to provide mathematical expressions for each of the involved coordinates. Any data plots are typically easier to handle using a table format and \addplot table.

The coordinates can be numbers, but they can also contain mathematical expressions like sin(0.5) or \h*8 (assuming you defined \h somewhere). However, expressions which involve round braces need to be encapsulated in a further set of curly braces, for example ({sin(0.5)},{cos(0.1)}).

You can also supply error coordinates (reliability bounds) if you are interested in error bars. Simply append the error coordinates with ‘+- (ex,ey)’ (or +- (ex,ey,ez)) to the associated coordinate:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot+ [ error bars/.cd, x dir=both, x explicit, ] coordinates { (0,0) +- (0.1,0) (0.5,1) +- (0.4,0.2) (1,2) (2,5) +- (1,0.1) }; \end{axis} \end{tikzpicture}

or

copy \addplot coordinates { (900,1e-6) +- (0.1,0.2) (2600,5e-7) +- (0.2,0.5) (4000,7e-8) +- (0.1,0.01) };

These error coordinates are only used in case of error bars, see Section 4.12. You will also need to configure whether these values denote absolute or relative errors.

The coordinates as such can be numbers as +5, -1.2345e3, 35.0e2, 0.00000123 or 1e2345e-8. They are not limited to TeX’s precision.

Furthermore, coordinates allows to define “meta data” for each coordinate. The interpretation of meta data depends on the visualization technique: for scatter plots, meta data can be used to define colors or style associations for every point (see 4.5.12 for an example). Meta data (if any) must be provided after the coordinates and after error bar bounds (if any) in square brackets:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot+ [ scatter, scatter src=explicit, ] coordinates { (900,1e-6) [1] (2600,5e-7) [2] (4000,7e-8) [3] }; \end{axis} \end{tikzpicture}

Please refer to the documentation of point meta at 4.8 for more information about per point meta data.

The coordinate stream can contain empty lines to tell pgfplots that the function has jumps. To use it, simply insert an empty line (and ensure that you have \pgfplotsset{compat=1.4} or newer in your preamble). See the documentation of empty line for details.

/pgfplots/plot coordinates/math parser=true|false (initially true) ¶

Allows to turn off support for mathematical expressions in every coordinate inside of \addplot coordinates. This might be necessary if coordinates are not in numerical form (or if you’d like to improve speed).

It is necessary to disable plot coordinates/math parser if you use some sort of symbolic transformations (i.e. text coordinates).

\addplot table [column selection]{file or inline table}; ¶

\addplot[options] table [column selection]{file or inline table} trailing path commands; ¶

\addplot3 … ¶

This input method is the main input format for any data-based function. It accepts either a file containing data or an inline table provided in curly braces.

Given a data file like

copy dof L2 Lmax maxlevel 5 8.31160034e-02 1.80007647e-01 2 17 2.54685628e-02 3.75580565e-02 3 49 7.40715288e-03 1.49212716e-02 4 129 2.10192154e-03 4.23330523e-03 5 321 5.87352989e-04 1.30668515e-03 6 769 1.62269942e-04 3.88658098e-04 7 1793 4.44248889e-05 1.12651668e-04 8 4097 1.20714122e-05 3.20339285e-05 9 9217 3.26101452e-06 8.97617707e-06 10

one may want to plot ‘dof’ versus ‘L2’ or ‘dof’ versus ‘Lmax’. This can be done by

copy \begin{tikzpicture} \begin{loglogaxis}[ xlabel=Dof, ylabel=$L_2$ error, ] \addplot table [x=dof,y=L2] {datafile.dat}; \end{loglogaxis} \end{tikzpicture}

or, for the Lmax column, using

copy \begin{tikzpicture} \begin{loglogaxis}[ xlabel=Dof, ylabel=$L_\infty$ error, ] \addplot table [x=dof,y=Lmax] {datafile.dat}; \end{loglogaxis} \end{tikzpicture}

It is also possible to provide the data inline, i.e. directly as argument in curly braces:

copy \begin{tikzpicture} \begin{loglogaxis}[ xlabel=Dof, ylabel=$L_\infty$ error, ] \addplot table [x=dof,y=Lmax] { dof L2 Lmax maxlevel 5 8.31160034e-02 1.80007647e-01 2 17 2.54685628e-02 3.75580565e-02 3 49 7.40715288e-03 1.49212716e-02 4 129 2.10192154e-03 4.23330523e-03 5 321 5.87352989e-04 1.30668515e-03 6 769 1.62269942e-04 3.88658098e-04 7 1793 4.44248889e-05 1.12651668e-04 8 4097 1.20714122e-05 3.20339285e-05 9 9217 3.26101452e-06 8.97617707e-06 10 }; \end{loglogaxis} \end{tikzpicture}

Inline table may be convenient together with ‘\\’ and row sep=\\, see below for more information.

Alternatively, you can load the table once into an internal structure and use it multiple times:⁴

copy \pgfplotstableread{datafile.dat}\loadedtable % use any custom name in place of `\loadedtable' ... \addplot table [x=dof,y=L2] {\loadedtable}; ... \addplot table [x=dof,y=Lmax] {\loadedtable}; ...

I am not really sure how much time can be saved, but it works anyway. The \pgfplotstableread command is documented in all detail in the manual for PgfplotsTable. As a rule of thumb, decide as follows:

• 1. If tables contain few rows and many columns, the \macro framework will be more efficient.

• 2. If tables contain more than \(200\) data points (rows), you should always use file input (and reload if necessary).

Occasionally, it might be handy to load a table, apply manual preparation steps (for example \pgfplotstabletranspose) and plot the result tables afterwards.

If you do prefer to access columns by column indices instead of column names (or your tables do not have column names), you can also use

copy \addplot table [x index=2,y index=3] {datafile.dat}; \addplot table [x=dof,y index=2] {datafile.dat};

Summary and remarks:

• • Use \addplot table [x={column name},y={column name}] to access column names. Those names are case sensitive and need to exist.

• • Use \addplot table [x index={column index},y index={column index}] to access column indices. Indexing starts with \(0\). You may also use an index for \(x\) and a column name for \(y\).

• • Use \addplot table [x expr=\coordindex,y={column name}] to plot the coordinate index versus some \(y\) data.

• • Use \addplot table [header=false] {file name} if your input file has no column names. Otherwise, the first non-comment line is checked for column names: if all entries are numbers, they are treated as numerical data; if one of them is not a number, all are treated as column names.

• • It is possible to read error coordinates from tables as well. Simply add options ‘x error’, ‘y error’ or ‘x error index’/‘y error index’ to source columns. See Section 4.12 for details about error bars.

• • It is possible to read per point meta data (usable in scatter src, see page (page for section 4.5.12)) as has been discussed for \addplot coordinates and \addplot file above. The meta data column can be provided using the meta key (or the meta index key).

• • Use \addplot table [source columns] {\macro} to use a pre-read table. Tables can be read using

  copy \pgfplotstableread{datafile.dat}\macroname.

  If you like, you can insert the optional keyword ‘from’ before \macroname.

• • The accepted input format of tables is as follows:

  • – Rows are separated by new line characters.

    Alternatively, you can use row sep=\\ which enables ‘\\’ as row separator. This might become necessary for inline table data, more precisely: if newline characters have been converted to white spaces by TeX’s character processing before pgfplots had a chance to see them. This happens if inline tables are provided inside of macros. Use row sep=\\ and separate the rows by ‘\\’ if you experience such problems.

  • – Columns are usually separated by white spaces (at least one tab or space).

    If you need other column separation characters, you can use the

    col sep=space|tab|comma|colon|semicolon|braces|&|ampersand

    option documented in all detail in the manual for PgfplotsTable which is part of pgfplots.

  • – Any line starting with ‘#’ or ‘%’ is ignored.

  • – The first line will be checked if it contains numerical data. If there is a column in the first line which is no number, the complete line is considered to be a header which contains column names. Otherwise it belongs to the numerical data and you need to access column indices instead of names.

  • – The accepted number format is the same as for ‘\addplot coordinates’, see above.

  • – If you omit column selectors, the default is to plot the first column against the second. That means \addplot table does exactly the same job as \addplot file for this case.

  • – If you need unbalanced columns, simply use nan as “empty cell” placeholder. These coordinates will be skipped in plots.

• • It is also possible to use mathematical expressions together with ‘\addplot table’. This is documented in all detail in Section 4.3.4, but the key idea is to use one of x expr, y expr, z expr or meta expr as in ‘\addplot table[x expr=\thisrow{maxlevel}+3,y=L2]’.

• • The PgfplotsTable package coming with pgfplots has a the feature “Postprocessing Data in New Columns” (see its manual).

  This allows to compute new columns based on existing data. One of these features is create col/linear regression (described in Section 4.24).

  You can invoke all the create col/key name features directly in \addplot table using

  \addplot table [x={create col/key name=arguments}].

  In this case, a new column will be created using the functionality of key name. This column generation is described in all detail in PgfplotsTable. Finally, the resulting data is available as \(x\) coordinate (the same holds for y= or z=).

  One application (with several examples how to use this syntax) is line fitting with create col/linear regression, see Section 4.24 for details.

• • The table can contain empty lines to tell pgfplots that the function has jumps. To use it, simply insert an empty line (and ensure that you have \pgfplotsset{compat=1.4} or newer in your preamble). See the documentation of empty line for details.

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

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

Allows to disable header identification for \addplot table. See above.

/pgfplots/table/x={column name} ¶

/pgfplots/table/y={column name} ¶

/pgfplots/table/z={column name} ¶

/pgfplots/table/x index={column index} ¶

/pgfplots/table/y index={column index} ¶

/pgfplots/table/z index={column index} ¶

These keys define the sources for \addplot table. If both column names and column indices are given, column names are preferred. Column indexing starts with \(0\). The initial setting is to use x index=0 and y index=1.

Please note that column aliases will be considered if unknown column names are used. Please refer to the manual of PgfplotsTable which comes with this package.

/pgfplots/table/x expr={expression} ¶

/pgfplots/table/y expr={expression} ¶

/pgfplots/table/z expr={expression} ¶

These keys allow to combine the mathematical expression parser with file input. They are listed here to complete the list of table keys, but they are described in all detail in Section 4.3.4.

The key idea is to provide an expression which depends on table data (possibly on all columns in one row). Only data within the same row can be used where columns are referenced with \thisrow{column name} or \thisrowno{column index}.

Please refer to Section 4.3.4 for details.

/pgfplots/table/x error={column name} ¶

/pgfplots/table/y error={column name} ¶

/pgfplots/table/z error={column name} ¶

/pgfplots/table/x error index={column index} ¶

/pgfplots/table/y error index={column index} ¶

/pgfplots/table/z error index={column index} ¶

/pgfplots/table/x error expr={math expression} ¶

/pgfplots/table/y error expr={math expression} ¶

/pgfplots/table/z error expr={math expression} ¶

These keys define input sources for error bars with explicit error values.

The x error method provides an input column name (or alias), the x error index method provides input column indices and x error expr works just as table/x expr: it allows arbitrary mathematical expressions which may depend on any number of table columns using \thisrow{col name}.

Please see Section 4.12 for details about the usage of error bars.

/pgfplots/table/x error plus={column name} ¶

/pgfplots/table/y error plus={column name} ¶

/pgfplots/table/z error plus={column name} ¶

/pgfplots/table/x error plus index={column index} ¶

/pgfplots/table/y error plus index={column index} ¶

/pgfplots/table/z error plus index={column index} ¶

/pgfplots/table/x error plus expr={math expression} ¶

/pgfplots/table/y error plus expr={math expression} ¶

/pgfplots/table/z error plus expr={math expression} ¶

/pgfplots/table/x error minus={column name} ¶

/pgfplots/table/y error minus={column name} ¶

/pgfplots/table/z error minus={column name} ¶

/pgfplots/table/x error minus index={column index} ¶

/pgfplots/table/y error minus index={column index} ¶

/pgfplots/table/z error minus index={column index} ¶

/pgfplots/table/x error minus expr={math expression} ¶

/pgfplots/table/y error minus expr={math expression} ¶

/pgfplots/table/z error minus expr={math expression} ¶

These keys define input sources for error bars with asymmetric error values, i.e. different values for upper and lower bounds.

They are to be used in the same way as x error. In fact, x error is just a style which sets both x error plus and x error minus to the same value.

Please see Section 4.12 for details about the usage of error bars.

/pgfplots/table/meta={column name} ¶

/pgfplots/table/meta index={column index} ¶

/pgfplots/table/meta expr={expression} ¶

These keys define input sources for per point meta data. Please see page (page for section 4.5.12) for details about meta data or the documentation for \addplot coordinates and \addplot file for further information.

These keys are only useful in conjunction with point meta=explicit or point meta=explicit symbolic. Note that

copy \addplot [point meta=explicit] table [meta=colname] ... ;

is equivalent to

copy \addplot [point meta=\thisrow{colname}] table [] ... ;

If the value of point meta is neither explicit nor explicit symbolic, the choice table/meta (and its friends) are ignored.

However, if point meta is one of explicit or explicit symbolic, the choice table/meta (or one of its friends) is mandatory.

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

Configures the character to separate rows.

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

/pgfplots/table/col sep=space|tab|comma|semicolon|colon|braces|&|ampersand (initially space)

Allows to choose column separators for \addplot table. Please refer to the manual of PgfplotsTable which comes with this package for details about col sep.

/pgfplots/table/read completely={auto,true,false} (initially auto) ¶

Allows to customize \addplot table{file name} such that it always reads the entire table into memory.

This key has just one purpose, namely to create postprocessing columns on the fly and to plot those columns afterwards. This “lazy evaluation” which creates missing columns on the fly is documented in the PgfplotsTable manual (in section “Postprocessing Data in New Columns”).

The initial configuration auto checks whether one of the keys table/x, table/y, table/z or table/meta contains a create on use column. If so, it enables read completely, otherwise it prefers to load the file in the normal way.

Attention:

Usually, \addplot table only picks required entries, requiring linear runtime complexity. As soon as read completely is activated, tables are loaded completely into memory. Due to data structures issues (“macro append runtime”), the runtime complexity for read completely is \(O(N^2)\) where \(N\) is the number of rows. Thus: use this feature only for “small” tables.⁵

/pgfplots/table/ignore chars={comma-separated-list} (initially empty) ¶

Allows to silently remove a set of single characters from input files. The characters are separated by commas. The documentation for this command, including cases like ‘\%,\#,\ ’ or binary character codes like ‘\^^ff’ can be found in the manual for PgfplotsTable.

This setting applies to \addplot file as well.

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

Allows to define a list of single characters which are actually treated like white spaces (in addition to tabs and spaces). Please refer to the manual of PgfplotsTable for details.

This setting applies to \addplot file as well.

/pgfplots/table/comment chars={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.

For example, comment chars=! uses ‘!’ as additional comment character (which allows to parse Touchstone files).

Please refer to the manual of PgfplotsTable for details.

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

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

Please refer to the manual of PgfplotsTable for details.

/pgfplots/table/search path={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. This standard search procedure will typically use the current working directory and the environment variable TEXINPUTS as for any other \input or \include statements.

An entry in 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 the environment variable TEXINPUTS.

\addplot {math expression} ; ¶

\addplot[options] {math expression} trailing path commands; ¶

\addplot3 … ¶

This input method allows to provide mathematical expressions which will be sampled. But unlike \addplot gnuplot, the expressions are evaluated using the math parser of pgf, no external program is required.

Plot expression samples x from the interval \([a,b]\) where \(a\) and \(b\) are specified with the domain key. The number of samples can be configured with samples=N as for plot gnuplot.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot {x^2 + 4}; \addplot {-5*x^3 - x^2}; \end{axis} \end{tikzpicture}

Please note that pgf’s math parser is configured to use trig format=degrees by default whenever trigonometric functions are involved:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot+ [ domain=0:360, ] {sin(x)}; \end{axis} \end{tikzpicture}

If you want to use radians, use



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot+ [ domain=-pi:pi, ] {sin(deg(x))}; \end{axis} \end{tikzpicture}

to convert the radians to degrees (also see trig format and trig format plots).

The plot expression parser also accepts some more options like samples at={coordinate list} or domain=first:last which are described below.

Remarks

• 1. What really goes on is a loop which assigns the current sample coordinate to the macro \x. pgfplots defines a math constant x which always has the same value as \x.

  In short: it is the same whether you write \x or just x inside of math expressions.

  The variable name can be customized using variable=t. Then, t will be the same as \t.

• 2. The complete set of math expressions can be found in the pgf manual. The most important mathematical operations are +, -, *, /, abs, round, floor, mod, <, >, max, min, sin, cos, tan, deg (conversion from radians to degrees), rad (conversion from degrees to radians), atan, asin, acos, cot, sec, cosec, exp, ln, sqrt, the constants pi and e, ^ (power operation), factorial,⁶ rand (random between \(-1\) and \(1\)), rnd (random between \(0\) and \(1\)), number format conversions hex, Hex, oct, bin and some more. The math parser has been written by Mark Wibrow and Till Tantau, the FPU routines have been developed as part of pgfplots. The documentation for both parts can be found in the PGF/TikZ manual.

  Please note, however, that trigonometric functions are defined in degrees (see trig format). The character ‘^’ is used for exponentiation (not ‘**’ as in gnuplot).

• 3. If the \(x\)-axis is logarithmic, samples will be drawn logarithmically.

• 4. Plot expression also allows to define per point meta data (color data) using point meta=math expression.

About the precision and number range:

Starting with version 1.2, \addplot expression uses a floating point unit. The FPU provides the full data range of scientific computing with a relative precision between \(10^{-4}\) and \(10^{-6}\). The /pgf/fpu key provides some more details.

Note that pgfplots makes use of lualatex’s features: if you use lualatex instead of pdflatex, pgfplots will use lua’s math engine which is both faster and more accurate (compat=1.12 or higher).



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{loglogaxis}[ title={$\frac{1}{x^2}$}, ] \addplot [ blue, domain=1:1e30, ] {x^-2}; \end{loglogaxis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{semilogyaxis}[ title={$e^x$ logarithmically plotted}, ] \addplot [ blue, domain=1:700, ] {exp(x)}; \end{semilogyaxis} \end{tikzpicture}

\addplot expression {math expr};

\addplot[options] expression {math expr} trailing path commands;

\addplot3 …

The syntax

\addplot {math expression};

as short-hand equivalent for

\addplot expression {math expression};

\addplot (x expression,y expression) ; ¶

\addplot[options] (x expression,y expression) trailing path commands; ¶

\addplot3 … ¶

A variant of \addplot expression which allows to provide different coordinate expressions for the \(x\)- and \(y\)-coordinates. This can be used to generate parameterized plots.

Please note that \addplot (x,x^2) is equivalent to \addplot expression {x^2}.

Note further that since the complete point expression is surrounded by round braces, round braces for either \(x\) expression or \(y\) expression need special attention. You will need to introduce curly braces additionally to allow round braces:

\addplot ({\(x\) expr}, {\(y\) expr}, {\(z\) expr});

/pgfplots/domain=\(x_1\):\(x_2\) (initially [-5:5]) ¶

/pgfplots/y domain=\(y_1\):\(y_2\) ¶

/pgfplots/domain y=\(y_1\):\(y_2\) ¶

Sets the function’s domain(s) for \addplot expression and \addplot gnuplot. Two dimensional plot expressions are defined as functions \(f\colon [x_1,x_2] \to \mathbb {R}\) and \(x_1\) and \(x_2\) are set with domain. Three dimensional plot expressions use functions \(f\colon [x_1,x_2] \times [y_1,y_2] \to \mathbb {R}\) and \(y_1\) and \(y_2\) are set with y domain. If y domain is empty, \([y_1,y_2] = [x_1,x_2]\) is assumed for three dimensional plots (see page (??) for details about three dimensional plot expressions).

The keys y domain and domain y are the same.

The domain key will be ignored if samples at is specified; samples at has higher precedence.

Please note that domain is not necessarily the same as the axis limits (which are configured with the xmin/xmax options).

The domain keys are only relevant for gnuplot and \addplot expression. In case you’d like to plot only a subset of other coordinate input routines, consider using the coordinate filter restrict x to domain.

Remark for TikZ users:

/pgfplots/domain and /tikz/domain are independent options. Please prefer the pgfplots variant (i.e. provide domain to an axis, \pgfplotsset or a plot command). Since older versions also accepted something like \begin{tikzpicture}[domain=\(\dotsc \)], this syntax is also accepted as long as no pgfplots domain key is set.

/pgfplots/samples={number} (initially 25) ¶

/pgfplots/samples y={number} ¶

Sets the number of sample points for \addplot expression and plot gnuplot. The samples key defines the number of samples used for line plots while the samples y key is used for mesh plots (three dimensional visualization, see page (??) for details). If samples y is not set explicitly, it uses the value of samples.

The samples key won’t be used if samples at is specified; samples at has higher precedence.

The same special treatment of /tikz/samples and /pgfplots/samples as for the domain key applies here. See above for details.

/pgfplots/samples at={coordinate list} ¶

Sets the \(x\)-coordinates for \addplot expression explicitly. This overrides domain and samples.

The coordinate list is a \foreach expression, that means it can contain a simple list of coordinates (comma-separated), but also complex ... expressions like⁷

copy \pgfplotsset{samples at={5e-5,7e-5,10e-5,12e-5}} \pgfplotsset{samples at={-5,-4.5,...,5}} \pgfplotsset{samples at={-5,-3,-1,-0.5,0,...,5}}

The same special treatment of /tikz/samples at and /pgfplots/samples at as for the domain key applies here. See above for details.

Attention:

samples at overrides domain, even if domain has been set after samples at! Use samples at={} to clear coordinate list and re-activate domain.

/pgfplots/variable={variable name} (initially x) ¶

/pgfplots/variable y={variable name} (initially y) ¶

Defines the variables names which will be sampled in domain (with variable) and in domain y (with variable y).

The same variables are used for parametric and for non-parametric plots. Use variable=t to change them if you like (for gnuplot, there is such a distinction; see parametric/var 1d).

Technical remark: TikZ also uses the variable key. However, it expects a macro name, i.e. \x instead of just x. Both possibilities are accepted here.

/pgfplots/trig format plots=default|deg|rad (initially default) ¶

Allows to reconfigure the input format for trigonometric functions like sin, cos, tan, and their friends.

This key reconfigures trigonometric functions inside of plot expressions, point meta arguments, and other items which are directly related to the evaluation of plot coordinates.

Note that this does not apply to TikZ drawing instructions like \node, \draw, \fill, etc.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={60}{30},trig format plots=rad, title=plots in radians, ] \addplot3+ [domain=0:4*pi,samples=19,samples y=1] ({sin(x)}, {cos(x)}, {2*x/(4*pi)}); % drawing instructions still use PGF's default \node [fill=white,draw=black,anchor=center] at ({sin(90)},{cos(90)},1) {X}; \end{axis} \end{tikzpicture}

Limitations:

this feature is currently unavailable for polaraxis and smithchart.

/pgf/trig format=deg|rad (initially deg) ¶

Allows to reconfigure the trigonometric format for all user arguments.

This affects all user arguments including view, TikZ polar coordinates, pins of \nodes, start/end angles for edges, etc.

At the time of this writing, this feature is in experimental state: it can happen that it breaks TikZ internals. Please handle with care and report any bugs.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={rad(60)}{rad(30)}, trig format=rad, title=all in radians, ] \addplot3+ [domain=0:4*pi,samples=19,samples y=1] ({sin(x)}, {cos(x)}, {2*x/(4*pi)}); % drawing instructions now also use radians \node [fill=white,draw=black,anchor=center] at ({sin(pi/2)},{cos(pi/2)},1) {X}; \end{axis} \end{tikzpicture}

\addplot table [column selection and expressions]{file};

\addplot[options] table [column selection and expressions]{file} trailing path commands;

\addplot3 …

Besides the already discussed possibility to provide a column selection by means of column names (x=name or x index=index, see Section 4.3.2), it is also possible to provide mathematical expressions as arguments.

Mathematical expressions are specified with x expr=expression inside of column selection and expressions. They can depend on zero, one or more columns of the input file. A column is referenced using the special command ‘\thisrow{column name}’ within expression (or \thisrownocolumn index).



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \pgfplotstabletypeset[columns={maxlevel,L2}]{plotdata/newexperiment1.dat} \begin{tikzpicture} \begin{semilogyaxis}[ xlabel=\texttt{maxlevel}$ + 10$, ] \addplot table [ x expr=\thisrow{maxlevel}+10, y=L2, ] {plotdata/newexperiment1.dat}; \end{semilogyaxis} \end{tikzpicture}

Besides x expr, there are keys y expr, z expr and meta expr where the latter allows to provide point meta data (which is used as scatter src or color data for surface plots etc.).

Inside of expression, the following macros can be used to access numerical data cells inside of the input file:

\thisrow{column name} ¶

Yields the value of the column designated by column name. There is no limit on the number of columns which can be part of a mathematical expression, but only values inside of the currently processed table row can be used.

It is possible to provide column aliases for column name as described in the manual of PgfplotsTable.

The argument column name has to denote either an existing column or one for which a column alias exists (see the manual of PgfplotsTable). If it can’t be resolved, the math parser yields an “Unknown function” error message.

Limitations:

this macro is currently unavailable if you use something of like \addplot table {\loadedtable} and the expression occurs outside of the normal plot coordinates. You have hit the limitation if and only if you encounter an error of sorts

! Package PGF Math Error: Unknown function `thisrow_unavailable_load_table_directly'.

The only alternative is to load the table directly from a file name, i.e. using \addplot table {filename.txt}. Also see \pgfplotstablesave.

\thisrowno{column index} ¶

Similar to \thisrow, this command yields the value of the column with index column index (starting with \(0\)).

Limitations:

see limitations for \thisrow.

\coordindex ¶

Yields the current index of the table row (starting with \(0\)). This does not count header or comment lines.

\lineno ¶

Yields the current line number (starting with \(0\)). This does also count header and comment lines.

If x index, x and x expr (or the corresponding keys for y, z or meta) are combined, this is how they interact:

• 1. Column access via x has higher precedence than index access via x index.

• 2. Even if x expr is provided, the values of x index and x are still checked. Any value found using column name access or column index access is made available as \columnx (or \columny, \columnz, \columnmeta, resp.). However, the result of x expr is used as plot coordinate.

  This allows to access the cell values identified by x or x index using the “pointer” \columnx. I am not sure if this yields any advantage, but it is possible nevertheless. If in doubt, prefer using \thisrow{column name}.

Attention:

If your table has less than two rows, you may need to set x index={},y index={} explicitly. This is a consequence of the fact that column name/index access is still applied even if an expression is provided.

\addplot gnuplot [further options]{gnuplot code}; ¶

\addplot[options] gnuplot [further options]{gnuplot code} trailing path commands; ¶

\addplot3 … ¶

In contrast to \addplot expression, the plot gnuplot command⁸ employs the external program gnuplot to compute coordinates. The resulting coordinates are written to a text file which will be plotted with \addplot file. pgf checks whether coordinates need to be regenerated and calls gnuplot whenever necessary (this is usually the case if you change the number of samples, the argument to \addplot gnuplot or the plotted domain).⁹

The differences between \addplot expression and plot gnuplot are:

• • \addplot expression does not require any external programs and requires no additional command line options.

• • \addplot expression does not produce a lot of temporary files.

• • \addplot gnuplot uses radians for trigonometric functions while \addplot expression has degrees (unless pgf is configured for trig format=rad).

• • \addplot gnuplot is faster than pdflatex. Using lualatex and compat=1.12 (or higher) can reach a similar speed.

• • \addplot gnuplot has a larger mathematical library.

• • \addplot gnuplot has a higher accuracy. Note that lualatex and compat=1.12 (or higher) come with the same precision.

Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example

copy pdflatex -shell-escape filename.tex.

Sometimes it is called shell-escape or enable-write18. Sometimes one needs two hyphens – that all depends on your TeX distribution.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot gnuplot [ id=sin, ] {sin(x)}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{semilogyaxis} \addplot gnuplot [ id=exp, domain=0:10, ] {exp(x)}; \end{semilogyaxis} \end{tikzpicture}

The options determine the appearance of the plotted function; these parameters also affect the legend. There is also a set of options which are specific to the gnuplot interface. These options are described in all detail in the PGF/TikZ manual, Section 22.6. A short summary is shown below. Some remarks:

• • The independent variable for one-dimensional plots can be changed with the variable option, just as for \addplot expression. Similarly, the second variable for two dimensional plots can be changed with variable y.

  For parametric plots, the variable names need to be adjusted with parametric/var 1d and parametric/var 2d (since gnuplot uses t and u,v as initial values for parametric plots).

• • Please note that \addplot gnuplot does not allow separate per point meta data (color data for each coordinate). You can, however, use point meta=f(x) or point meta=x.

• • The generated output file name can be customized with id, see below.

Please refer to the PGF/TikZ manual, Section 22.6 for more details about \addplot function and the gnuplot interaction.

\addplot function {gnuplot code}; ¶

\addplot[options] function {gnuplot code} trailing path commands; ¶

\addplot3 … ¶

Use

\addplot function {gnuplot code};

as alias for

\addplot gnuplot {gnuplot code};

/pgfplots/translate gnuplot=true|false (initially true) ¶

Enables or disables automatic translation of the exponentiation operator ‘^’ to ‘**’.

This features allows to use ^ in \addplot gnuplot instead of gnuplot’s **.

/pgfplots/parametric=true|false (initially false) ¶

Set this to true if you’d like to use parametric plots with gnuplot. Parametric plots use a comma separated list of expressions to make up \(x(t),\, y(t)\) for a line plot or \(x(u,v), \, y(u,v)\, z(u,v)\) for a mesh plot (refer to the gnuplot manual for more information about its input methods for parametric plots).

/pgfplots/parametric/var 1d={variable name} (initially t) ¶

/pgfplots/parametric/var 2d={variable name,variable name} (initially u,v) ¶

Allows to change the dummy variables used by parametric gnuplot plots. The initial setting is the one of gnuplot: to use the dummy variable ‘t’ for parametric line plots and ‘u,v’ for parametric mesh plots.

These keys are quite the same as variable and variable y, only for parametric plots. If you like to change variables for non-parametric plots, use variable and/or variable y.

In case you don’t want the distinction between parametric and non-parametric plots, use

\pgfplotsset{parametric/var 1d=,parametric/var 2d=}.

/tikz/id={unique string identifier} ¶

A unique identifier for the current plot. It is used to generate temporary filenames for gnuplot output.

/tikz/prefix={file name prefix} ¶

A common path prefix for temporary filenames (see the PGF/TikZ manual, Section 22.6 for details).

/tikz/raw gnuplot(no value) ¶

Disables the use of samples and domain.

\addplot shell [further options]{shell commands}; ¶

\addplot[options] shell [further options]{shell commands} trailing path commands; ¶

\addplot3 … ¶

An extension by Stefan Tibus

In contrast to \addplot gnuplot, the plot shell command allows execution of arbitrary shell commands to compute coordinates. The resulting coordinates are written to a text file which will be plotted with \addplot file. pgf checks whether coordinates need to be regenerated and executes the shell commands whenever necessary.

Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example

copy pdflatex -shell-escape filename.tex.

Sometimes it is called shell-escape or enable-write18. Sometimes one needs two slashes – that all depends on your TeX distribution.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot shell [ prefix=pgfshell_, id=cos ] { awk 'BEGIN{ pi=3.14159; N=10; for(i=0;i<=N;i++) print i,cos(i/N*pi); }' }; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} % just reprint the result from above \addplot+ [ prefix=pgfshell_, id=replot, ] shell {cat pgfshell_cos.out}; \end{axis} \end{tikzpicture}

The options determine the appearance of the plotted function; these parameters also affect the legend. There is also a set of options which are specific to the gnuplot and the shell interface. These options are described in all detail in the PGF/TikZ manual, Section 22.6. A short summary is shown below.

/tikz/id={unique string identifier}

A unique identifier for the current plot. It is used to generate temporary filenames for shell output.

/tikz/prefix={file name prefix}

A common path prefix for temporary filenames (see the PGF/TikZ manual, Section 22.6 for details).

\addplot graphics {file name}; ¶

\addplot[options] graphics {file name} trailing path commands; ¶

\addplot3 … ¶

This plot type allows to extend the plotting capabilities of pgfplots beyond its own limitations. The idea is to generate the graphics as such (for example, a contour plot, a complicated shaded surface¹⁰ or a large point cluster) with an external program like Matlab® or gnuplot. The graphics, however, should not contain an axis or descriptions. Then, we use \includegraphics and a pgfplots axis which fits exactly on top of the imported graphics.

Of course, one could do this manually by providing proper scales and such. The operation \addplot graphics is intended so simplify this process. However the main difficulty is to get images with correct bounding box. Typically, you will have to adjust bounding boxes manually.

Let’s start with an example: Suppose we use, for example, Matlab to generate a surface plot like

copy [X,Y] = meshgrid( linspace(-3,3,500) ); surf( X,Y, exp(-(X - Y).^2 - X.^2 ) ); shading flat; view(0,90); axis off; print -dpng external1

which is then found in external1.png. The surf command of Matlab generates the surface, the following commands disable the axis descriptions, initialise the desired view and export it. Viewing the image in any image tool, we see a lot of white space around the surface – Matlab has a particular weakness in producing tight bounding boxes, as far as I know. Well, no problem: use your favorite image editor and crop the image (most image editors can do this automatically). We could use the free ImageMagick command

convert -trim external1.png external1.png

to get a tight bounding box. Then, we use



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ enlargelimits=false, axis on top, ] \addplot graphics [ xmin=-3,xmax=3, ymin=-3,ymax=3, ] {external1}; \end{axis} \end{tikzpicture}

to load the graphics¹¹ just as if we would have drawn it with pgfplots. The axis on top simply tells pgfplots to draw the axis on top of any plots (see its description).

Please note that pgfplots offers support for smaller surface plots as well which might be an option – unless the number of samples is too large. See Section 4.6.6 for details.

However, external programs have the following advantages here: they are faster, allow more complexity and provide real \(z\) buffering which is currently only simulated by pgfplots. Thus, it may help to consider \addplot graphics for complicated surface plots.

Our first test was successful – and not difficult at all because graphics programs can automatically compute the bounding box. There are a couple of free tools available which can compute tight bounding boxes for .eps or .pdf graphics:

• 1. The free vector graphics program inkscape can help here. Its feature “File \(\gg \) Document Properties: Fit page to selection” computes a tight bounding box around every picture element.

  However, some images may contain a rectangular path which is as large as the bounding box (Matlab® computes such .eps images). In this case, use the “Ungroup” method (context menu of inkscape) as often as necessary and remove such a path.

  Finally, save as .eps.

  However, inkscape appears to have problems with postscript fonts – it substitutes them. This doesn’t pose problems in this application because fonts shouldn’t be part of such images – the descriptions will be drawn by pgfplots.

• 2. The tool pdfcrop removes surrounding whitespace in .pdf images and produces quite good bounding boxes.

¹⁰ See also Section 4.6.6 for an overview of pgfplots methods to draw shaded surfaces.

¹¹ Please note that I had no Matlab license at hand, so I used gnuplot to produce an equivalent replacement graphics. The principles hold for gnuplot, Matlab, and Octave, however.

4.3.7.1Adjusting bounding boxes manually¶

In case you don’t have tools at hand to provide correct bounding boxes, you can still use TeX to set the bounding box manually. Some viewers like gv provide access to low-level image coordinates. The idea is to determine the number of units which need to be removed and communicate these units to \includegraphics.

I am aware of the following methods to determine bounding boxes manually:

inkscape

I am pretty sure that inkscape can do it.

gv

The ghost script viewer gv always shows the postscript units under the mouse cursor.

gimp

The graphics program gimp usually shows the cursor position in pixels, but it can be configured to display postscript points (pt) instead.

Let’s follow this approach in a further example.

We use gnuplot to draw a (relatively stupid) example data set. The gnuplot script

generates external2.eps with a uniform random sample of size \(30000\). As before, we import this scatter plot into pgfplots using \addplot graphics. Again, the bounding box is too large, so we need to adjust it (gnuplot can do this automatically, but we do it anyway to explain the mechanisms):

Using gv, I determined that the bounding box needs to be shifted 12 units to the left and 9 down. Furthermore, the right end is 12 units too far off and the top area has about 8 units space wasted. This can be provided to the trim option of \includegraphics, and we use clip to clip the rest away:

/pgfplots/plot graphics/xmin={coordinate} ¶

/pgfplots/plot graphics/ymin={coordinate} ¶

/pgfplots/plot graphics/zmin={coordinate} ¶

/pgfplots/plot graphics/xmax={coordinate} ¶

/pgfplots/plot graphics/ymax={coordinate} ¶

/pgfplots/plot graphics/zmax={coordinate} ¶

These keys are required for \addplot graphics and provide information about the external data range. The graphics will be squeezed between these coordinates. The arguments are axis coordinates; they are only useful if you provide each of them.

Alternatively, you can also use the plot graphics/points feature to provide the external data range, see below.

/pgfplots/plot graphics/points={list of coordinates} (initially empty) ¶

This key also allows to provide the external data range. It constitutes an alternative to plot graphics/xmin (and its variants): simply provide at least two coordinates in list of coordinates. Their bounding box is used to determine the external data range, and the graphics is squeezed between these coordinates.

The example from above can be written equivalently as



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ axis on top, title=Graphics Import, ] \addplot graphics [ % instead of the min/max things: points={(0,1) (1,0)}, % trim=left bottom right top includegraphics={trim=12 9 12 8,clip}, ] {external2}; \addplot coordinates {(0,0) (1,1)}; \end{axis} \end{tikzpicture}

The list of coordinates is a sequence of the form (x,y) for two-dimensional plots and (x,y,z) for three-dimensional ones, the ordering is irrelevant. The single elements are separated by white space.

It is possible to mix plot graphics/xmin and variants with plot graphics/points.

The plot graphics/points key has further functionality for inclusion of three-dimensional graphics which is discussed at the end of this section (on page (page for section 4.3.8)). Here is a short reference on the accepted syntax for three-dimensional plot graphics: in addition to the (x,y,z) syntax, you can provide arguments of the form (x,y,z) => (X,Y). Here, the first (three-dimensional) coordinate is a logical coordinate and the second (two-dimensional) coordinate denotes the coordinates of the very same point, but inside of the included image (relative to the lower left corner of the image). Applications and examples for this syntax can be found in the section for three-dimensional plot graphics (see page (page for section 4.3.8)).

/pgfplots/plot graphics/includegraphics={options} ¶

A list of options which will be passed as is to \includegraphics. Interesting options include the trim=left bottom right top key which reduces the bounding box and clip which discards everything outside of the bounding box. The scaling options won’t have any effect, they will be overwritten by pgfplots.

/pgfplots/plot graphics/includegraphics cmd={\macro} (initially \includegraphics) ¶

Allows to use a different graphics routine. A possible choice could be \pgfimage. The macro should accept the width and height arguments (in brackets) and the file name as first argument.

/pgfplots/plot graphics/node(style, no value) ¶

A predefined style used for the TikZ node containing the graphics. The predefined value is

copy \pgfplotsset{ plot graphics/node/.style={ transform shape, inner sep=0pt, outer sep=0pt, every node/.style={}, anchor=south west, at={(0pt,0pt)}, rectangle } }

/pgfplots/plot graphics(no value) ¶

This key belongs to the public low-level plotting interface. You won’t need it in most cases.

This key is similar to sharp plot or smooth or const plot: it installs a low-level plot handler which expects exactly two points: the lower left corner and the upper right one. The graphics will be drawn between them. The graphics file name is expected as value of the /pgfplots/plot graphics/src key. The other keys described above need to be set correctly (excluding the limits, these are ignored at this level of abstraction). This key can be used independently of an axis.

/pgfplots/plot graphics/lowlevel draw={width}{height} ¶

A low-level interface for \addplot graphics which actually invokes \includegraphics. But there is no magic involved: the command is simply expected to draw a box of dimensions width \(\times \) height. The coordinate system has already been shifted correctly.

The initial configuration is

\includegraphics[value of “plot graphics/includegraphics”,width=#1,height=#2]

{value of “plot graphics/src”}.

Thus, you can tweak \addplot graphics to place any TeX box of the desired dimensions into an axis between the provided minimum and maximum coordinates. It is not necessary to make use of the graphics file name or the options in the ‘includegraphics’ key if you overwrite this low-level interface with

plot graphics/lowlevel draw/.code 2 args={code which depends on #1 and #2}.

\addplot file {name}; ¶

\addplot[options] file {name} trailing path commands; ¶

\addplot3 … ¶

Deprecation note:

If you have data files, you should generally use \addplot table. The input type \addplot file is almost the same, but considerably less powerful. It is only kept for backwards compatibility.

The \addplot file input mechanism is similar to the TikZ command ‘\addplot file’. It is to be used like

copy \addplot file {datafile.dat};

where name is a text file with at least two columns which will be used as \(x\)- and \(y\)-coordinates. Lines starting with ‘%’ or ‘#’ are ignored. Such files are often generated by gnuplot:

copy #Curve 0, 20 points #x y type 0.00000 0.00000 i 0.52632 0.50235 i 1.05263 0.86873 i 1.57895 0.99997 i ... 9.47368 -0.04889 i 10.00000 -0.54402 i

This listing has been copied from the PGF/TikZ manual, Section 22.4.

Plot file accepts one optional argument,

copy \addplot file [skip first] {datafile.dat};

which allows to skip over a non-comment header line. This allows to read the same input files as \addplot table by skipping over column names. Please note that comment lines do not count as lines here.

The input method \addplot file can also read meta data for every coordinate. As already explained for \addplot coordinates (see above), meta data can be used to change colors or other style parameters for every marker separately. Now, if point meta is set to explicit or to explicit symbolic and the input method is \addplot file, one further element will be read from disk – for every line. Meta data is always the last element which is read. See page (page for section 4.5.12) for information and examples about per point meta data and page (page for section 4.5.12) for an application example using scatter/classes.

Plot file is very similar to \addplot table: you can achieve the same effect with

copy \addplot table [x index=0,y index=1,header=false] {datafile.dat};

Due to its simplicity, \addplot file is slightly faster while \addplot table allows higher flexibility.

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

The file can contain empty lines to tell pgfplots that the function has jumps. To use it, simply insert an empty line (and ensure that you have \pgfplotsset{compat=1.4} or newer in your preamble). See the documentation of empty line for details.

/pgfplots/plot file/skip first=true|false (initially false) ¶

/pgfplots/plot file/ignore first=true|false (initially false) ¶

The two keys can be provided as arguments to \addplot file[options] {filename}; to skip the first non-comment entry in the file. They are equivalent. If you provide them in this context, the prefix /pgfplots/plot file can be omitted.