☰
tikz.dev / PGFplots Manual

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

The Reference

\(\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}}}\)

4.14Specifying the Plotted Range

4.14.1Configuration of Limits Ranges

  • /pgfplots/xmin={(math image)coord(math image)}

  • /pgfplots/ymin={(math image)coord(math image)}

  • /pgfplots/zmin={(math image)coord(math image)}

  • /pgfplots/xmax={(math image)coord(math image)}

  • /pgfplots/ymax={(math image)coord(math image)}

  • /pgfplots/zmax={(math image)coord(math image)}

  • /pgfplots/min={(math image)coord(math image)}

  • /pgfplots/max={(math image)coord(math image)}

    • These options allow to define the axis limits, i.e. the lower left and the upper right corner. Everything outside of the axis limits will be clipped away.

Attention:

these values (and other related keys in this section) merely affect how pgfplots determines the axis’ range. The values are unrelated to function sampling. Please refer to domain in order to define the sampling range for plot expressions. It is valid to sample a larger or smaller range than the displayed portion of the axis. Use xmin and its friends to specify which portion of the axis is to be displayed.

Each of these keys is optional, and missing limits will be determined automatically from input data. Here, the min and max keys set limits for \(x\), \(y\) and \(z\) to the same (math image)coord(math image).

If \(x\) limits have been specified explicitly and \(y\) limits are computed automatically, the automatic computation of \(y\) limits will only considers points which fall into the specified \(x\)-range (and vice versa). The same holds true if, for example, only xmin has been provided explicitly: in that case, xmax will be updated only for points for which \(x \ge \;\)xmin holds. This feature can be disabled using clip limits=false.

Axis limits can be increased automatically using the enlargelimits option.

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title=Auto Limits, ] \addplot {x^2}; \end{axis} \end{tikzpicture}

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title={\texttt{xmin=0}}, xmin=0, ] \addplot {x^2}; \end{axis} \end{tikzpicture}

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title={\texttt{ymax=10}}, ymax=10, ] \addplot {x^2}; \end{axis} \end{tikzpicture}

Note that even if you provide ymax=10, data points with \(y>10\) will still be visualized – producing a line which leaves the plotted range.

See also the restrict x to domain and restrict x to domain* keys – they allow to discard or clip input coordinates which are outside of some domain, respectively.

During the visualization phase, i.e. during \end{axis}, these keys will be set to the final axis limits. You can access the values by means of \pgfkeysvalueof{/pgfplots/xmin}, for example:

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ % Show (automatically) computed limits: title={ Axis limits are $ [\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/xmin}} :\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/xmax}} ] \times [\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/ymin}} :\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/ymax}} ]$ }, ] \addplot {x^2}; \end{axis} \end{tikzpicture}

This access is possible inside of any axis description (like xlabel, title, legend entries, etc.) or any annotation (i.e. inside of \node, \draw or \path and coordinates in ((math image)x(math image),(math image)y(math image))), but not inside of \addplot (limits may not be complete at this stage).

  • /pgfplots/xmode=normal|linear|log (initially normal)

  • /pgfplots/ymode=normal|linear|log (initially normal)

  • /pgfplots/zmode=normal|linear|log (initially normal)

    • Allows to choose between linear (= normal) or logarithmic axis scaling or log plots for each \(x,y,z\)-combination.

    Logarithmic plots use the current setting of log basis x and its variants to determine the basis (default is \(e\)).

  • /pgfplots/clip xlimits=true|false (initially true)

  • /pgfplots/clip ylimits=true|false (initially true)

  • /pgfplots/clip zlimits=true|false (initially true)

  • /pgfplots/clip limits=true|false

    • Configures what to do if some, but not all axis limits have been specified explicitly. In case clip limits=true, the automatic limit computation will only consider points which do not contradict the explicitly set limits.

    The effect of clip xlimits=true is that if the \(x\)-coordinate of some point \((x,y)\) falls outside of the limits specified by xmin and xmax, neither \(x\) nor \(y\) will contribute to the automatically computed axis limits. The key clip limits is an alias which sets all the other options at once.

    This option has nothing to do with path clipping, it only affects how the axis limits are computed.

  • /pgfplots/enlarge x limits=auto|true|false|upper|lower|(math image)val(math image)|value=(math image)val(math image)|abs value=(math image)val(math image)|
    abs=(math image)val(math image)    |rel=(math image)val(math image)     (initially auto)

  • /pgfplots/enlarge y limits=auto|true|false|upper|lower|(math image)val(math image)|value=(math image)val(math image)|abs value=(math image)val(math image)|
    abs=(math image)val(math image)    |rel=(math image)val(math image)     (initially auto)

  • /pgfplots/enlarge z limits=auto|true|false|upper|lower|(math image)val(math image)|value=(math image)val(math image)|abs value=(math image)val(math image)|
    abs=(math image)val(math image)    |rel=(math image)val(math image)     (initially auto)

  • /pgfplots/enlargelimits=(math image)common value(math image)

    • Enlarges the axis size for one axis (or all of them for enlargelimits) somewhat if enabled.

    You can set xmin, xmax and ymin, ymax to the minimum/maximum values of your data and enlarge x limits will enlarge the canvas such that the axis doesn’t touch the plots.

    The value true enlarges the lower and upper limit.

    The value false uses tight axis limits as specified by the user (or read from input coordinates).

    The value auto will enlarge limits only for axis for which axis limits have been determined automatically. For three-dimensional figures, the auto mechanism applies only for the \(z\)-axis. The \(x\)- and \(y\)-axis won’t be enlarged.

    (-tikz- diagram)

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

    Specifying a number value like ‘enlarge x limits=0.2’ will enlarge lower and upper axis limit relatively. The following example adds \(20\%\) of the axis limits on both sides:

    (-tikz- diagram)

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

    The choice rel={(math image)value(math image)} is the same as true,value={(math image)value(math image)}, i.e. it activates relative enlargement for both upper and lower limit.

    The value upper enlarges only the upper axis limit while lower enlarges only the lower axis limit. In this case, the amount added to the respective limit can be specified using the value={(math image)val(math image)} key. It can be combined with any of the other possible values. For example,

    \pgfplotsset{enlarge x limits={value=0.2,upper}}

    will enlarge (only) the upper axis limit by \(20\%\) of the axis range. Another example is

    \pgfplotsset{enlarge x limits={value=0.2,auto}}

    which changes the default threshold of the auto value to \(20\%\).

    (-tikz- diagram)

    % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ small, minor x tick num=1, enlarge x limits={rel=0.5,upper}, ] \addplot {5 * x^3 - x^2 + 4*x -2}; \end{axis} \end{tikzpicture}

    While value uses relative thresholds, abs value accepts absolute values: it adds an absolute value to the selected axis. The choice abs={(math image)value(math image)} is the same as true,abs value={(math image)value(math image)}, i.e. it adds an absolute value to both upper and lower limit:

    (-tikz- diagram)

    % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ small, minor x tick num=1, enlarge x limits={abs=3}, ] \addplot {5 * x^3 - x^2 + 4*x -2}; \end{axis} \end{tikzpicture}

    Here, we enlarged by \(3\) units of the \(x\)-axis. Note that you can also specify dimensions like 1cm:

    (-tikz- diagram)

    % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[small,minor x tick num=1, enlarge x limits={abs=1cm}, ] \addplot {5 * x^3 - x^2 + 4*x -2} coordinate [pos=0] (first) coordinate [pos=1] (last); \draw [red,->] (first) -- ++(-1cm,0pt); \draw [red,->] (last) -- ++( 1cm,0pt); \end{axis} \end{tikzpicture}

    Technically, the use of absolute dimensions is a little bit different. For example, it allows to enlarge by more than width which is impossible for all other choices. pgfplots will try to fulfill both the provided width/height and the absolute axis enlargements. If it fails to do so, it will give up on width/height constraints and print a warning message to your logfile. See also the key enlargelimits respects figure size.

Attention:

abs value is applied multiplicatively for logarithmic axes! That means abs value=10 for a logarithmic axis adds \(\log 10\) to upper and/or lower axis limits.

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{loglogaxis}[ small, enlarge x limits={abs=11}, ] \addplot+ [domain=1:100000] {x^-2}; \end{loglogaxis} \end{tikzpicture}

Note that enlargelimits is applied before any changes to axis limits are considered as part of scale mode: enlargelimits will always be applied. Afterwards, the choice scale mode=scale uniformly will enlarge limits once more in order to satisfy all scaling constraints. The two limit enlargements are independent of each other, i.e. even if you say enlargelimits=false, scale mode will still increase axis limits if this seems to be necessary. An exception for this rule is enlarge-by-dimension, i.e. something like abs=1cm (see enlargelimits respects figure size for this case). See scale mode (especially scale mode=units only) and unit rescale keep size for detail on how to disable limit enlargement caused by scale mode.

  • /pgfplots/enlargelimits respects figure size=true|false (initially true)

    • A key which is only used for something like enlarge x limits={abs=1cm}, i.e. for enlarge-by-dimension. It controls if pgfplots will try to respect width/height. You should probably always leave it as its default unless you run into problems.

    If pgfplots fails to respect the figure size, it will print a warning message of sorts “enlargelimits respects figure size=true: could not respect the prescribed width/height” to your logfile.

  • /pgfplots/log origin x=0|infty (initially infty)

  • /pgfplots/log origin y=0|infty (initially infty)

  • /pgfplots/log origin z=0|infty (initially infty)

  • /pgfplots/log origin=0|infty (initially infty)

    • Allows to choose which coordinate is the logical “origin” of a logarithmic plot (either for a particular axis or for all of them).

    The choice log origin=infty is probably useful for stacked plots: it defines the “origin” in log coordinates to be \(-\infty \). To be compatibly with older versions, this is the default. Note that \(-\infty \) is clipped to be the lowest displayed value on the axis in question.

    The choice log origin=0 defines the logarithmic origin to be the natural choice \(\log (1)=0\). This is particularly useful for ycomb plots.

  • /pgfplots/update limits=true|false (initially true)

    • Can be used to interrupt updates of the data limits (for example, for single \addplot commands).

    This has the same effect as \pgfplotsinterruptdatabb ... \endpgfplotsinterruptdatabb.

  • \begin{pgfplotsinterruptdatabb}

  • (math image)environment contents(math image)

  • \end{pgfplotsinterruptdatabb}

    • Everything in (math image)environment contents(math image) will not contribute to the data bounding box.

    The same effect can be achieved with update limits=false inside curly braces.

4.14.2Accessing Computed Limit Ranges

This section is for those who want or need to access the computed limits programmatically. It lists how to access computed values.

  • /pgfplots/xmin(no value)

  • /pgfplots/ymin(no value)

  • /pgfplots/zmin(no value)

  • /pgfplots/xmax(no value)

  • /pgfplots/ymax(no value)

  • /pgfplots/zmax(no value)

    • These values are not only the input: after the survey phase, their values will be overwritten with the resulting computed values. These may differ according to enlargelimits or scale mode.

    If you need to access them, you can write \pgfkeysvalueof{/pgfplots/xmin} somewhere in your code.