Debian Codegraph @

texmf-dist/doc/generic/pgfplots/README

raw
1 pgfplots - Create normal/logarithmic plots in two and three dimensions for LaTeX/TeX/ConTeXt.
2
3 pgfplotstable - Loads, rounds, formats and postprocesses numerical tables.
4
5 PGFPlots draws high--quality function plots in normal or logarithmic scaling
6 with a user-friendly interface directly in TeX. The user supplies axis labels,
7 legend entries and the plot coordinates for one or more plots and PGFPlots
8 applies axis scaling, computes any logarithms and axis ticks and draws the
9 plots. It supports line plots, scatter plots, piecewise constant plots, bar
10 plots, area plots, mesh and surface plots, patch plots, contour plots, quiver
11 plots, histogram plots, polar axes, ternary diagrams, smith charts and some
12 more.
13
14 Pgfplots is based on Till Tantau's package PGF/TikZ (pgf).
15
16 Pgfplotstable displays numerical tables rounded to desired precision in various
17 display formats, for example scientific format, fixed point format or integer,
18 using TeX's math facilities for pretty printing. Furthermore, it provides
19 methods for table postprocessing.
20
21 Please take a look at
22 doc/latex/pgfplots/pgfplots.pdf
23 and
24 doc/latex/pgfplots/pgfplotstable.pdf.
25
26 Copyright 2007-2021 by Christian Feuersaenger.
27
28 This program is free software: you can redistribute it and/or modify
29 it under the terms of the GNU General Public License as published by
30 the Free Software Foundation, either version 3 of the License, or
31 (at your option) any later version.
32
33 This program is distributed in the hope that it will be useful,
34 but WITHOUT ANY WARRANTY; without even the implied warranty of
35 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
36 GNU General Public License for more details.
37
38 You should have received a copy of the GNU General Public License
39 along with this program. If not, see <http://www.gnu.org/licenses/>.
40
41
42 HISTORY:
43 UNSTABLE:
44 - repaired linux file permissions in release artifact
45
46 1.18
47 - new feature: 'contour lua', implemented and contributed by Francesco Poli
48 - new feature: ignore empty coordinates when computing regression lines
49 - new feature: improve log-regression fitting of exponential functions (using variance format=linear)
50 - fixed bug #390: image plots in log mode failed to work. Also fixed issues with mesh/ordering=y varies
51 - fixed bug #219: handle NaN in stacked plots
52
53 1.17
54 - fixed bug: restore compatibility with pgf/tikz circle syntax inside of pgfplots
55 - new feature #62: 'coordinate style' which allows to associate options with individual coordinates.
56 - new feature pgfplotstable: added 'text indicator'
57 - new feature pgfplotstable: added 'percent is letter' to allow comment chars
58 within string-based tables
59
60 1.16:
61 - fixed bug #111 [fillbetween] strange behavior when `soft clip` is used and one of the paths touches the axis border
62 - fixed bug #183: Nan in the first line of a numeric table was interpreted as column name
63 - fixed bug #187 Wrong output from mod in axis
64 - fixed bug #109 `visualization depends on` doesn't work with table from pgfplotstable is now fixed for numeric values
65 - fixed bug: \pgfplotstablenew was unable to create tables with 0 or 1 rows.
66 - fixed bug: 114 fillbetween suffered from inaccuracy (produced invisible segments)
67 - fixed bug #139 [fillbetween] numerical issues with dense points
68 - fixed bug #153: \begin{tikzpicture}[scale=...] combined with fill between or
69 'set layers' resulted in a wrong bounding box
70 - \addplot gnuplot: autodetected unbounded coordinates
71 - new feature: parse tick positions using math parser (tracker #69)
72 - new feature: programmatic access to axis coordinates for given canvas coordinates (\pgfplotspointgetcoordinates, tracker 68)
73 - new feature: 'x filter/.append expression', a stackable variant of 'x filter/.expression'
74
75 1.15: bugfix release
76 - fixed regression: fpu caused forest library to fail as soon as one loads pgfplots
77 - fixed bug #149 : \edef{...\to...} was wrong and caused \pgfplotstablevertcat to fail
78 - usability: added support for \plotnum during \addplot
79 - fixed bug 134 [statistics] Histogram with custom `symbolic coords`
80 - fixed bug 140 (pgfplotstable read does not process empty rows anymore)
81 - fixed bug 150 Usage of \pgfkeysvalueof in xtick leads to 'Dimension too large'
82 - fixed bug 105 [manual] `xticklabel pos=upper` is not documented
83 in fact, some of the documented positions for 'xtick pos' where
84 unavailable.
85 - fixed bug 155 [groupplots] `scaled ticks` does not recognize `ticklabels at`
86 - fixed bug 160 `xticklabels` also used for `extra x tick labels` if they are not given explicitly
87 - implemented partial solution for bug 154 [log mode] sampling in 2D and 3D different
88 - fixed bug 163 [bar-chart] bars disappear when values are >xmax/ymax
89 - fixed bug 81 cannot use dollar sign as 'comment char'
90 - fixed bug 91 Hashes in data
91 - fixed bug 165 [minor ticks] minor tick drawn after the last xtick
92 - fixed bug 176: 2d plot expression in 3d axis fails for lualatex
93
94 1.14
95 - new feature: 'contour filled' (compat=1.14)
96 - new feature: building colormaps from other colormaps (see "Building Colormaps based on other Colormaps" in the manual)
97 - new feature: non-uniform colormaps (compat=1.14)
98 - new feature: colormaps defined on position of arbitrary magnitude
99 - new feature: colorbar as legend
100 - new feature: 'colorbar style={xtick=data}' positions tick labels at colormap positions
101 - fixed bug: pgfplots now handles incompatible changes of luatex
102 loading \usepackage{pgfplots} _before_ pgf also allows makes older
103 PGF versions compatible with luatex
104 - fixed bug: incompatibility between units + groupplots (bug 119)
105 - fixed bug: 'axis line shift' did not respect labels
106 - fixed bug: layers for axis lines were not respected
107 - fixed bug: two axes with fillbetween in the same picture failed due to clip paths on layers
108 - fixed bug: quiver plots with 'every arrow' failed to evaluate arrow tip length arguments
109 - fixed bug: \usepgfplotslibrary{colorbrewer}: colormap 'PuOr' was defined in reverse order
110
111 1.13:
112 - fixed bug: incompatibility between fillbetween and babel
113 - fixed bug: 'compat=1.9' (or newer) failed to work with log bar plots
114 - fixed bug: javascript incompatibility between Acrobat reader DC and clickable lib
115 - fixed bug in polar axes: repaired default axis label positions
116 - fixed bug in polar axes: repaired support for sloped descriptions
117 - fixed bug: 'axis line style={draw=none}' had no effect unless one had 2d boxed axes
118 - fixed bug: point meta expressions with '=' inside of them which caused compilation errors
119 - fixed bug: compat=1.12 combined with interrupted plots (by empty line) failed to work
120 - fixed bug: compat=1.12 combined with lualatex evaluated relational operations (<, ==) with the wrong operator precedence
121 - fixed bug: fixed floor and ceil functions
122 - fixed bug: 'set layers' broke alignment features with different manifestations
123 ('set layers' together with fill between in group plots, together with at={} key, together with anchor)
124 - fixed bug: fill between and group plots: fill-between graphics was missing (list of layers was lost)
125 - fixed bug: \addplot graphics {\newFile{P.pdf}}; failed to properly expand the file name
126 - fixed bug: fill between + error bars resulted in compilation error
127 - fixed bug: stacked plots occasionally used a wrong coordinate mapping
128 - fixed bug: provided suitable default legends for xbar and xbar stacked
129 - fixed bug: 'dateplot' now computes missing 'date ZERO' automatically. 'date ZERO' is managed automatically.
130 - new feature: Added support for search paths to find data files (table/search path)
131 - new feature: 'xtick distance' allows to define tick positions by distance
132 - new feature: "axis line shift=10pt" shifts axis lines together with all their descriptions
133 - new feature: 'matrix plot' (alias 'imagesc') which allows cell-based matrix plots
134 - new feature: unbounded point meta in mesh plots will be treated like an invisible patch
135 - new feature: added high quality colormap 'viridis' (use 'colormap name=viridis' to activate it)
136 - new feature: ensured that 'shader=flat' returns the same result for every choice of 'z buffer' (starting with compat=1.13)
137 - new feature: utility function \pgfplotsforeachungrouped: added support for \breakforeach
138 - new feature: compat=1.13: activates sampling routine with less rounding errors
139 - new feature: cycle multiindex list (uses the 'ith' element for every provided sub-list)
140 - new feature: 'color of colormap=<value>' or 'color of colormap=<value> of <colormap name>'
141 - new feature: 'index of colormap=<value>' or 'index of colormap=<value> of <colormap name>'
142 - new feature: cycle list={[of colormap]}
143 - new feature: cycle list={[colors of colormap={0,100,500,100} of viridis]}
144 - new feature: cycle list={[indices of colormap={0,1,2,3} of hot]}
145 - new feature: added support for 'stack negative=on previous|separate' which allows separate plots for '+' and '-' (useful for bar plots)
146 - new feature: added support for 'colormap access=direct' combined with 'shader=flat mean' and 'shader=interp':
147 it previously used to interpolate indices instead of colors
148 - new feature: \closedcycle now produces useful results for 3d line plots
149 - new feature: added \usetikzlibrary{colorbrewer} and \usepgfplotslibrary{colorbrewer}
150 - new feature: added 'colormap access=piecewise constant'
151 - new feature: added rudimentary support for "Filled Contours" (based on 'colormap access=piecewise constant')
152 - new feature: added methods to build colormaps based on other colormaps using
153 "color of colormap", "index of colormap", "colors of colormap", "samples of colormap", and "indices of colormap"
154
155 1.12.1: minor bugfix release
156 - fixed bug: incompatibility of 1.12 with unicode-math
157 - fixed bug: lua backend failed to work with table input and dependency on \coordindex
158 - fixed bug: lua backend failed with 'forget plot'
159
160 1.12: scalability + performance
161 - scalability: reduced TeX memory consumption for huge inline tables
162 - scalability: lualatex allows bigger 3d graphics
163 - scalability: lualatex now reduces compilation time for huge 3d graphics
164 (requires \pgfplotsset{compat=newest} at the time of this writing)
165 surf shader=faceted: time reduced to 61% of pdflatex
166 (\addplot3[surf,samples=70] {exp(-x^2-y^2 +x*y)})
167
168 surf shader=interp: time reduced to 25% of pdflatex
169 (\addplot3[surf,shader=interp,samples=70] {exp(-x^2-y^2 +x*y)})
170
171 surf shader=interp, parametric: time reduced to 36% of pdflatex
172 (\addplot3[surf,shader=interp,z buffer=sort, samples=50,domain=-1:0,y domain=0:2*pi] ({sqrt(1-x^2) * cos(deg(y))}, {sqrt( 1-x^2 ) * sin(deg(y))}, x);)
173
174 surf shader=faceted, parametric: time reduced to 40% of pdflatex
175 (\addplot3[surf,z buffer=sort, samples=50,domain=-1:0,y domain=0:2*pi] ({sqrt(1-x^2) * cos(deg(y))}, {sqrt( 1-x^2 ) * sin(deg(y))}, x);)
176
177 - scalability: lualated now reduces compilation time for boxplots.
178 10000 input points from table: time reduced to 23% of pdflatex
179 - fixed bug: 3d axes where all axes used log scale produced compile failure
180 - fixed bug: axis equal did not respect "disabledatascaling"
181 - fixed bug: mesh legend was confused by color input=explicit
182 - fixed bug: colorbar style did not reset zmin/zmax
183 - fixed bug: memory allocation in FPU consumed too much memory
184 - fixed bug: boxplots: removed compilation error due to spurious spaces in options list
185 - fixed bug: boxplots: now uses standard quantile estimators: has all 9 estimators of R and uses the same as in Excel as default (as of compat=1.12)
186 - fixed bug: boxplots: sometimes failed to compute boxplot statistics for special inputs
187 - fixed bug: boxplots: now, it sets 'mark=*' for outliers if there is no mark (compat=1.12)
188 - fixed regression: compat=1.11 broke arcs inside of axis
189 - new feature: ensured that arcs inside of axis make use of 'axis cs' and 'axis direction cs' automatically
190 - new feature: ensured that (0:1) is evaluated with axis cs
191 - fixed bug: precision of transformation cartesian to polar was too low (added atan2 to fpu)
192 - fixed bug: z buffer caused 'mesh legend' to produce a compile error
193 - new feature: added 'y filter/.expression={y==3 ? nan : y}' to simplify coordinate filters
194
195 1.11: usability + bug fixes.
196 - new feature: "hide obscured x ticks=false" to disable the feature which hides ticks
197 - simplified UI for symbolic coords: now, it accepts unexpandable
198 dictionary entries including umlauts, undefined macros, math mode, ...
199 - simplified UI for symbolic coords: added magic prefix
200 [normalized]<number> to allow something like xmin={[normalized]0.7}
201 - simplified UI for custom annotations: one does not need to say "axis cs" any longer;
202 coordinates like (1,2) are now automatically interpreted as (axis cs:1,2)
203 - new feature: 'type ticklabels with struts' improves baseline alignment of tick labels
204 - new feature: 'trig format plots=rad' allows to use radians in trigonometric evaluations
205 - simplified 'external lib': added driver auto-detection for pdflatex, lualatex, xelatex, dvips
206 (\usepgfplotslibrary{external}, or, with the next PGF release, \usetikzlibrary{external})
207 - simplified UI for \addplot coordinates: now, it expands macros as it goes.
208 - new feature: 'intersection segments' now accepts negative indices to count from the last backwards
209 - simplified UI: 'intersection segments' now accepts new syntax with 1-based indices (old 0-based are still supported)
210 - fixed bug: fillbetween has had a problem with pins on input paths
211 - fixed bug: now, 'stacked ignores zero' is no longer applied to error bars.
212 - fixed bug: tick lines were drawn incorrectly for centered axis lines in 3d
213 - fixed bug: variable=u failed to work in some contexts
214 - fixed bug: fill between implicitly activated layers, but did not install the
215 correct layers for grid lines etc.
216 - fixed bug: z grid style was applied to y grid style
217 - fixed bug: using 'x=1cm' failed to work in axis descriptions (legends)
218 - fixed bug: mesh legend failed to work with 'shader=interp'
219 - fixed bug: bounding box of shader=interp was wrong if there were transformations.
220 - fixed bug: added support for \addplot graphics in ConTeXt
221 - fixed bug: external lib failed to work with dvips (since PGF 3.0.0 I suppose); now it produces correct bounding boxes
222 - fixed bug: \pgfplotstablenew can now overwrite existing tables.
223 - fixed bug: extra ticks near intersections of axis lines were hidden
224 - fixed bug: 'intersection segments' did not work with '--cycle'
225 - fixed bug: 'intersection segments' did not update the last tikz point
226 - fixed bug: tick lines/grid lines have been clipped when they were near the boundary
227 - fixed bug: soft clip decoration failed to apply the transformation matrix
228 - fixed bug: polar axes and units library resulted in broken bounding box
229 - fixed bug: \addplot[stack plots=false] used to work up to 1.8, but failed until now. Fixed.
230 - fixed bug: hist/density was broken since some time
231
232
233 1.10:
234 - new feature: fill between plots (library fillbetween)
235 - new feature: concatenate intersection segments (library fillbetween)
236 - fixed bug: xelatex failed to run contour external
237 - fixed incompatibility with \label and \usepackage{mcaption}
238 - fixed bug: histograms produced wrong point meta
239 - fixed bug: histograms reported the wrong 'plot name' and confused shifts of bar plots
240
241 1.9:
242 - new feature: asymmetric error bars
243 - new feature: activated math parser for axis limit arguments, arguments in axis cs, and domain argument in log plots
244 - new feature: stacked bar plots place their 'nodes near coords' correctly in the middle and print the increment (compat=1.9)
245 - new feature: stacked bar plots suppress empty increments (compat=1.9).
246 - new feature: 'scatter/position=relative|absolute' allow to position 'nodes near coords' absolutely.
247 use-case: bar plots + nodes near coords which are at, say, y=0 rather than their y value
248 - new feature: integration of smooth shadings & auto-CMYK conversion
249 \usepackage[cmyk]{xcolor} or \selectcolormodel{cmyk} will reconfigure pgfplots to use CMYK (document-wide)
250 - new feature (advanced audience only): programmatic access to data coordinates during the visualization phase
251 -> allows much more customization for error bars, stacked plots, nodes near coords.
252 - wrote beginner tutorials
253 - fixed bug: error bars and point meta did not work together
254 - fixed bug: stacked plots did not respect 'visualization depends on'
255 - fixed bug: luatex 0.76 is not backwards compatible; added version switch
256 - fixed bug: ternary library precision has been improved
257 - fixed bug: problem with axis limits very close to 0
258 - fixed bug: colormap specification limit case produced out of bounds exception
259
260
261 1.8:
262 - new feature: tight bounding box even if the axis is no box and bb excludes clip path
263 - new feature: mesh/color input=explicit
264 - new feature: shader=interp now has drivers for both dvipdfmx and xetex
265 - new feature: support for more color spaces in colormap definitions
266 - new feature: shader=interp and device-level gray colorspaces
267 - new feature: 'contour/contour dir=[xyz]' to draw contours in different directions
268 - new feature: statistics library with boxplot handler (both boxplot prepared and automatic computation)
269 - fixed bug: 3d centered axis lines and label placement (requires compat=1.8 or higher)
270 - fixed bug: axis lines and placement of labels, tick scale labels, and reversed axes
271 (requires compat=1.8 or higher)
272 - fixed bug: filtering out coords from a mesh plot failed
273 - fixed bug: every legend image post was not respected inside of \ref{plotlabel}
274 - fixed bug: high-order patches computed the shader=flat mean in a wrong way.
275 - fixed bug: remember picture inside of pgfplots axes failed (due to cell picture)
276 - fixed bug: now, the tick scale label will be omitted if there are no ticks
277 - fixed bug: axis box path was not closed
278 - fixed bug: the bounding box was non-empty even if the axis was hidden.
279 - fixed bug: auto-alignment of nodes near coords failed for xbar plots
280 - fixed bug: providing bar width / bar shift in terms of axis units did
281 not work with [xy]bar and nodes near coords
282 - fixed bug: transformation 'data cs=cart' -> polar is more robust now
283 - fixed bug: code did not compile against pgf 2.00
284 - fixed bug: patch plot lib and shader=interp,patch type=biquadratic
285 - fixed bug: context path searching issue (pgfplots.lua)
286 - fixed bug: shader=interp and dvips driver
287 - fixed bug: error bars with explicit relative input failed
288
289 1.7
290 - added feature: 'bar shift' and 'bar width' can now be expressed in terms of axis units (compat=1.7 or higher)
291 - fixed incompatibility regression pgfplots 1.6.1 pgf 2.10: layers
292 - fixed incompatibility pgfplots and imakeidx
293 - added feature: 'enlargelimits={abs=1cm}', i.e. enlarge by dimension rather than unit
294 - patchplots lib: added patch type=bicubic
295 - patchplots lib: added support for global paths (fillable)
296 - patchplots lib: added patch type sampling feature
297 - patchplots lib: improved usability (documentation and improvements)
298 - fixed path issues in context: moved lua input file to tex/generic
299 - fixed bug: \ref{legendimage} inside of legend text was wrong.
300
301 1.6.1:
302 - fixed incompatibility lualatex,shader=interp, and german package (introduced in 1.6)
303
304 1.6:
305 - added support for layered graphics (main use case: multiple axes and layers)
306 - added support for second colormap in mesh plots (mesh/interior colormap name)
307 - added support for scopes inside of axes
308 - contour plots: added ability to provide list of discrete labels (mesh/levels)
309 - empty lines are interpreted as interruptions in data plots (was undocumented since 1.4)
310 - added more scaling options to 'scale mode=scale uniformly' (affects axis equal in 3d
311 and \addplot3 graphics)
312 - fixed wrong implementation of 'axis equal' and 'unit vector ratio' in 3d
313 (backwards compatible for 2d, but not for 3d - the 3d implementation was plain wrong)
314 - fixed incompatibility of lualatex and shader=interp
315 - fixed bugs/added features around \addplot3 graphics
316 - fixed bug: colorbar did not support ymode=log
317 - fixed a couple of minor bugs
318 - fixed bounding box computation for clip=false,axis lines=none
319
320 1.5.1:
321 - more operations for FPU library (==, !=,<=,>=,?)
322 - fixed bug in usage of decorations in \addplot
323 - bugfix for contour prepared format=matlab
324 - added 'const plot mark mid' and 'jump mark mid' plot handlers
325 - nodes on a plot (\addplot ... node[pos=<fraction>] {};)
326 - 'trim axis group left' and 'trim axis group right'
327 - bugfixes for polar axes and log+stacked plots
328 - added style 'log ticks with fixed point'
329 - introduced patched tikz paths to simplify circles and ellipses within an axis
330 - patchplots lib: patch type=polygon
331 - some more bugfixes
332
333 1.5:
334 - Contour plots,
335 - Histograms,
336 - Quiver plots,
337 - patch plots (library)
338 - Triangle Meshes
339 - Bilinear Elements
340 - Quadratic Triangles
341 - Biquadratic Quadrilaterals
342 - Coons Patches
343 - Discrete colorbars,
344 - Table sorting,
345 - Linear regression,
346 - Ternary diagrams,
347 - Tieline Plots
348 - Smith Charts
349 - Polar axes,
350 - Empty lines in input files result in interrupted plots,
351 - PDF user defined coordinate mouse popups
352 - CMYK colormaps and shadings,
353 - new markers and cycle lists
354 - access to axis limits,
355 - \addplot3 graphics: pgfplots draws an appropriate axis for a three-dimensional(!) external png graphics
356 - 3D axes: support to provide explicit unit vectors:
357 - explicit unit vectors
358 - explicit unit vectors which are uniformly rescaled to match width/height
359 - 3D axes: improved support for unit vector ratios
360 - improvements of the groupplot styles
361 - preliminary support for (2d) bar plots in 3d axes
362 - new shader 'faceted interp'
363 - table package:
364 - 'every nth row' style
365 - 'comment chars' key to define comment characters in input files
366 - 'skip first n' style
367 - lots of smaller bugfixes (see ChangeLog for details)
368
369
370 1.4.1:
371 - improved compatibility to gnuplot 4.4
372
373 1.4:
374 Version 1.4 contains several new features, mostly work on details.
375 It fixes many bugs and provides the following improvements:
376 - detached legends
377 - detached colorbars
378 - ybar (and similar plots) can now be mixed with other plot types
379 like line plots.
380 - improved legend formatting
381 - added 'restrict x to domain*' which cups coordinates outside of a specified domain (same for y and z)
382 - Added support for linear regression
383 - Inline tables,
384 - Lots of bug fixes
385
386 The next version will make a greater step when it is stable.
387
388
389 1.3.1:
390 Version 1.3.1 is a bugfix release containing
391 - improved parametric plots with gnuplot
392 - improved normalsize, small and footnotesize scale styles and added tiny
393 - a lot of bugfixes
394
395 1.3:
396 - improvements for two dimensional visualization, among them
397 - axis equal,
398 - color bars,
399 - nodes near coords,
400 - jumps in plots,
401 - improved description positioning,
402 - reverseable axis directions,
403 - simpler alignment of adjacent axes,
404 - units and a simplified user interface,
405 - new three dimensional line, scatter, mesh and surface plots,
406 - a copy of the automatic pdf externalization library,
407 - an improved manual enhanced with a lot of pdf cross references.
408
409 1.2.2:
410 - fixed a problem with the samples key,
411 - provides some smaller fixes and some manual improvements.
412 - added plot graphics.
413
414 1.2:
415 - completely rewritten math expression parser with extended data range,
416 - colormaps for scatter plots
417 - fine tuning for plot parameters.
418 - table package has been extended and is now a fully featured table typesetting, computing and postprocessing tool.
419