summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-02-05 01:04:42 +0000
committerKarl Berry <karl@freefriends.org>2009-02-05 01:04:42 +0000
commitad23c1c436c3e031cc4b81849d0fa2b892851467 (patch)
treed04be182dbf5cdb14c1728b8f2edddc84f77df03 /Master/texmf-dist/doc/latex/pgfplots
parent4041df693bc0b66ecdf77e891e5ff1a60f1497fc (diff)
pgfplots update (4feb09)
git-svn-id: svn://tug.org/texlive/trunk@12087 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/ChangeLog400
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/Makefile3
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/README36
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.pngbin0 -> 41531 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.pngbin0 -> 45244 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.pngbin0 -> 35554 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.pngbin0 -> 32390 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex26
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex23
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib13
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex25
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex61
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex38
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex178
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.mst17
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdfbin1215431 -> 1838847 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex36
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex1490
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex4
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex46
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotsJS.djs373
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdfbin17942 -> 17867 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.dat11
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.html13
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex14
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.mst17
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdfbin301531 -> 430450 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex1125
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment1.dat14
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment2.dat14
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment3.dat14
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment1.dat13
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment2.dat16
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment3.dat16
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/todo.txt496
35 files changed, 3839 insertions, 693 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
index dc60cdd20fc..382b4fd117e 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
+++ b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
@@ -1,3 +1,403 @@
+2009-02-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Released version 1.2
+
+2009-02-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - improved sanity checking in table package.
+ - fixed max/min implementation for fpu
+
+2009-02-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - patched key paths for plot file and plot table. One could not provide
+ options with key path /pgfplots. This will need a little bit more
+ attention later-on, see todo.txt.
+
+2009-02-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - removed missing character warnings
+ - fixed bug with domain processing for plot gnuplot.
+ - fixed bug in FPU : fpu+pgf 2.00 is problematic with unary minus signs
+
+2009-01-29 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - provided backwards compatibility for the domain and |samples at| key:
+ the tikz variants are used by default now.
+
+2009-01-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - manual improvements: fixed several typos in the manual; improved section
+ about alignment and section about upgrade remarks.
+ - manual improvements: replace a lot of gnuplot examples with 'plot
+ expression' commands.
+ - fixed the broken |axis equal| feature - it collided with the tickmin/max
+ processing. The tickmin/max is now processed somewhat different
+ - removed (some of the) 'no pt in nullfont' log warnings
+ - now, every input file will be protocolled to the log file (only).
+
+2009-01-24 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - re-implemented |domain|, |samples| and |samples at| keys. They are now
+ independ of the |/tikz/| variants - and provide the complete data range of
+ pgfplots.
+ - fixed missing \endgroup in plot gnuplot (in the case that -shell-escape
+ was not available)
+ - fixed small bug with empty-plot-special case and tickmin/max resetting
+
+2009-01-21 Pascal Wolkotte <wolkottept@users.sourceforge.net>
+
+ - implemented '[x|y]tick[min|max]' option
+
+2009-01-20 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed bug: 'scatter/classes' couldn't be provided as behavior option.
+
+2009-01-16 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - improved fault tolerance of |scatter/classes|.
+ - fixed scoping bug with plot markers
+
+2009-01-12 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - implemented \pgfplotstablesave
+ - \pgfplotstabletypeset and \pgfplotstabletypesetfile are now the same;
+ the input format is autodetected.
+
+
+2009-01-07 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - implemented simple test for 'samples at' vs. 'domain'
+ - implemented 'table/create col/set list' style
+ - implemented a method to create new tables from scratch
+ - implemented some more postprocessing routines for table package
+
+2009-01-06 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed bug in clickable lib: logarithmic scales in x axes have not been
+ processed properly.
+ - now, the logarithmic sampling won't be applied for parametric plot
+ expressions. Furthermore, it has been optimized.
+ - improved compatibility between FPU and fixed point library inside of
+ pgfplots
+
+2009-01-05 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - both, plot gnuplot and plot expression now sample their points
+ logarithmically if the x (y) axis is logarithmic.
+
+2009-01-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - the fpu is now used automatically for plot expression and for the table
+ create col/expr feature. However, it will be disabled during the low-level
+ drawing commands of pgfplots. I rewrote some of the internals to avoid
+ problems with the low data range of tikz (for example during domain
+ processing).
+
+2008-12-31 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - improved FPU support
+
+2008-12-30 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added backwards compatibility switches for my new PGF library FPU.
+
+2008-12-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed some issues with stacked plots and skewed axes
+ - fixed a lot of manual typos and mistakes, thanks to Jeremie Knuesel!
+ - Greatly simplified notation for |plot expression|.
+ - introduced |\addplot gnuplot| as alias for |\addplot function|.
+
+2008-12-17 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added |create col/expr accum| style: a variant of |expr| which now
+ allows simple accumulation of columns
+ - added a |date type| style based on the pgf calendar package
+
+2008-12-14 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - provided a further improvement for empty plot handling: the normal
+ processing is now applied for empty plots, with special handling for the
+ named start/end coordinates.
+ - improved future compatibility with FPU: just in case it moves to a
+ separate library, I will check for such a thing.
+
+2008-12-07 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - there was a bug with minorgrids auto-deactivation which has been fixed.
+ - fixed a 'plot function[domain=..]' bug introduced yesterday
+ - floating point methods now don't use 'fp' for mantisse computations if
+ the fixed point lib is used
+
+2008-12-06 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - scatter will now assign a mark if none is set.
+ - empty plot bug has been fixed.
+ - using xmode in wrong context leads to error message.
+ - xticklabel pos now accepts 'top' and 'bottom'
+ - manual has more compact index: I removed the '/pgfplots/' and '/tikz/'
+ collections.
+ - improved index formatting.
+ - re-implemented plot expression's sampling method. The PGF \foreach
+ statement does not allow sampling domains beyond PGF's native math parser,
+ the new implementation does also support the 'fp' package (combinded with
+ the associated PGF library).
+ Efficiency is expected to be higher than the previous \foreach
+ implementation.
+ - Provided a specialized processing of the |domain| argument for plot
+ function which avoids the pgf math parser. Now, plot function provides the
+ full data range of gnuplot.
+
+
+2008-12-05 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - improved sanity checking for plot coordinate syntax; empty lines in plot
+ coordinates are now processed correctly.
+ - added alias for 'sample' key. It can now be provided as argument to axis
+ environments.
+ - added |no markers| shortcut style.
+ - Added documentation for interrupted plots (for example for
+ discontinuities in plots)
+
+2008-12-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - updated docs.
+ - Fixed bug when there are less legend entries than plots.
+ - added 'forget plot' option (and 'every forget plot' style)
+ - made '/pgfplots/domain' option a public key alias to '/tikz/domain'
+
+2008-12-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed a remaining bug with 'axis equal'
+ - fixed bug in pgfplots/tikz search path code
+
+2008-11-30 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added keys 'axis equal' and 'axis equal image' to get the same length
+ for each unit vector.
+
+2008-11-28 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - optimiziation of \pgfmathfloattofixed yields 7% time savings for
+ pgfplotstest. For plots with many points it will be even more.
+
+2008-11-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added '/pgfplots/refstyle={label}' key.
+ - added 'read completely' key.
+ - fixed bug with error bars: some of the latest changes must have been
+ during sleep.
+ - eliminated 6 dimen registers.
+
+2008-11-24 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - document bounding box modifications with 'overlay' option of pgf.
+ The examples require the latest CVS version of pgf, because pgf 2.00 has a
+ bug here (overlay and matrizes).
+
+2008-11-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added 'scaled ticks=manual' feature. It allows complete control
+ over the scaled tick algorithm and scaled tick label placement.
+ - improved support for french language, i.e. for active ';' and ':'
+ characters. The manual does not compile completely if switched to french,
+ but it is not much.
+ - updated pgfplotstable such that it can be adopted to more general tasks.
+ As example, html file output has been added to the manual.
+
+2008-11-22 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - the clickable lib can now be used independently of pgfplots.
+
+2008-11-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - improved compatibility between pgfplotstable and colortbl: \rowcolor
+ and dec sep align (sci sep align) now works properly.
+ - Added 'every col no <index>' style as alias for 'display columns/<index>'.
+ - provided error message if \pgfplotstablerow is used in the wrong
+ context.
+ - improved pgfplots documentation.
+ - improved pgfplotstable documentation
+ - 'sci sep align' and 'dec sep align' now only enable math mode for their
+ numbers, not for empty columns.
+
+2008-11-18 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added error bar adjustments for 'ybar' style
+ - fixed bug: error bars are now drawn after the main path
+
+2008-11-11 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed missing code portion for scatter and log plots
+ - added 'view' option which allows to specify pitch and yaw for definition
+ of a 3D viewport (definition of x,y and z unit vectors of PGF).
+
+2008-11-10 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - documented default values of cycle lists.
+
+2008-11-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - prepared more code for 3D-axis drawing. It is growing now and won't take
+ long for good-looking 3D figures.
+
+2008-10-30 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - used 'y domain='<empty> as feature for \addplot3 (\x,\x,\x):
+ this will sample from a line, not from a surface.
+
+2008-10-29 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - implemented user interface to manually place 2D/3D tick LABELS (docs
+ missing).
+ The next step is to predefine them automatically for 3D plots.
+
+2008-10-28 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - renamed 'scatter plot' keys to 'scatter'
+ - improved scatter plot user interface (not yet documented in parts)
+ - implemented input methods for scatter coordinates (not yet documented)
+ - worked on 3D axis generation.
+
+2008-10-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Implemented colormaps.
+ - Implemented scatter plots.
+
+2008-10-25 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed a bug introduced in latest changes: 'tick align' produced wrongly
+ positioned tick labels.
+
+
+2008-10-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed a bug related to auto-tick placement and special cases of the
+ scaling transformation.
+ - Documented the new freedom in axis unit vector placement, reversed and
+ skewed axes.
+ - Introduced optimization for orthogonal axes.
+
+2008-10-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added 'copy' and 'sqrt' features to table package.
+
+
+2008-10-20 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Revised all new routines such that the 2D framework is running again.
+ All 2D tests appear to be ok.
+ The 3D stuff is neither documented nor ready, although early things
+ work. In the moment, it is only slowing things down, see todo.
+ - Updated clickable lib to work with the new framework.
+ - Removed remaining plain TeX '\loop' commands
+
+2008-10-14 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Restored state of 2008-09-25 because something did not work and I don't
+ have a stable version yet.
+ - Updated compatiblity for pgf 2.0: inserted 'min exponent for 1000 sep'
+ into compatibility files
+
+2008-10-12 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - implemented input routines for 3D plots using \addplot3:
+ - coordinates,
+ - gnuplot,
+ - file,
+ - table,
+ - expression.
+ - updated coordinate streaming methods to work with 3D data.
+ I also cleaned and optimized the 2D code.
+ -> stacked plots and error bars do not reflect this yet!
+ - added 'plot function[<further behavior options>]' which are merged
+ together with those after 'plot[<behavior options>]'
+
+2008-10-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - implemented first running 3D axis with orthogonal projection.
+ Most features work, especially tick placement, grid lines, tick label
+ placement. Some detail decisions of how to things look pretty have to
+ be done and realized. Scaling does not work yet and there are still
+ plenty of open problems. The user interface for setting views is crual.
+
+2008-10-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed bug related to 'current axis' and origin anchors which occured
+ if axis limits have been restricted manually and axis descriptions
+ employed origin anchors.
+ - continued the change to logical coordinates.
+
+2008-10-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - changed internals to use logical coordinates consistently.
+ - Added feature 'x={(10pt,-3pt)}, y=-1pt'; allowing
+ - skewed axes,
+ - reversed axes,
+ - rotated axes,
+ as preparation for 3d plots.
+
+2008-09-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - optimized number processing and log computations. Logs are now a factor
+ of 3.8 faster.
+
+2008-09-25 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Provided options to manually configure the tick scaling algorithm:
+ either 1/10^<exponent> or 1/<real> can be configured.
+ - Added check for PGF 2.00 availability
+
+2008-09-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Placed all drawing commands for plots and markers into separate scopes
+ to end the effect of 'fill opacity' and 'dotted' styles.
+ FIXME: check whether this affects any named nodes and such!
+
+2008-09-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Improved compatibility with figure-environments. I had to turn
+ "hidden=false" to fix this incompatiblity. I hope this does not produce
+ visible artefacts... needs to be checked.
+
+2008-09-17 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added 'include outfiles' option to table package, together with
+ 'force remake'
+
+2008-09-16 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed spacing bug in table package.
+ - outfile and debug feature of table package now produce proper newlines.
+
+2008-09-11 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added error messages if the table typeset features rely on LaTeX
+ packages (array,booktabs) which have not yet been loaded.
+
+2008-09-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added 'clear infinite' postprocessor to table package.
+
+2008-09-02 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - re-implemented minimum and maximum computation because the PGF math
+ parser interface has been changed. The changes are backwards compatible
+ now.
+ - fixed a bug in logarithm computation.
+ - fixed some bugs related to the pgfplotsclickable library
+
+2008-09-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Provided sanity checking for gradient computation in table package:
+ division by zero now leads to empty cells.
+
+2008-08-22 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Added pgfplotsclickable library which displays point coordinates when
+ clicking into the plot region (acrobat reader only; relies on acrotex
+ bundle)
+
2008-08-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
- Release 1.1
diff --git a/Master/texmf-dist/doc/latex/pgfplots/Makefile b/Master/texmf-dist/doc/latex/pgfplots/Makefile
index 8751da9863b..ab7aa8a5b89 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/Makefile
+++ b/Master/texmf-dist/doc/latex/pgfplots/Makefile
@@ -14,4 +14,7 @@ pgfplotstable: pgfplotstable.pdf
@echo ""
@echo "$@ compiled successfully. You may need to re-run make several times to get all cross-references right."
+clean:
+ rm -f *.aux *.ind *.idx *.toc *.out *.log *.ilg *.dvi pgfplots.pdf pgfplotstable.pdf *.djs *.bbl *.blg
+
FORCE:
diff --git a/Master/texmf-dist/doc/latex/pgfplots/README b/Master/texmf-dist/doc/latex/pgfplots/README
new file mode 100644
index 00000000000..e0a52efb27b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/README
@@ -0,0 +1,36 @@
+pgfplots - A tool to work with scientific data. It draws normal and/or
+logarithmic plots in LaTeX/TeX/ConTeXt.
+
+pgfplotstable - Loads, rounds and formats and postprocesses numerical tables.
+
+Pgfplots draws high-quality function plots in normal or logarithmic
+scaling with a user-friendly interface. The user supplies axis labels, legend
+entries and the plot coordinates for one or more plots and Pgfplots applies
+axis scaling, computes any logarithms and axis ticks and draws the plots.
+It is based on Till Tantau's package PGF/TikZ.
+
+Pgfplotstable displays numerical tables rounded to desired precision in various
+display formats, for example scientific format, fixed point format or integer,
+using TeX's math facilities for pretty printing.
+
+Please take a look at
+ doc/latex/pgfplots/pgfplots.pdf
+and
+ doc/latex/pgfplots/pgfplotstable.pdf.
+
+
+Copyright 2007/2008 by Christian Feuersaenger.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+
diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.png
new file mode 100644
index 00000000000..1304cf23291
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.png
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.png
new file mode 100644
index 00000000000..873a372dd73
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.png
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.png
new file mode 100644
index 00000000000..79b4d2fe0ff
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.png
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.png
new file mode 100644
index 00000000000..636f307f42a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.png
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex
index e4efc70dcfa..914383cdaf2 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex
@@ -7,9 +7,14 @@
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.
-% $Header: /cvsroot/pgfplots/pgfplots/doc/latex/pgfplots/pgfmanual-en-macros.tex,v 1.1 2008/05/24 12:09:27 ludewich Exp $
+% $Header: /cvsroot/pgfplots/pgfplots/doc/latex/pgfplots/pgfmanual-en-macros.tex,v 1.3 2008/12/27 21:39:10 ludewich Exp $
+% This file is part of the pgf manual; I re-use it here with
+% permission.
+%
+% I have changed very few things (marked with 'CF')
+
\providecommand\href[2]{\texttt{#1}}
@@ -238,7 +243,8 @@
\ifpgfutil@in@%
\extractinitial{#1}#2\@nil%
\else
- \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill(\extrakeytext no default)}%
+% \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill(\extrakeytext no default)}%
+ \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill}%
\fi%
\fi%
\def\mykey{#1}%
@@ -253,7 +259,8 @@
}
\def\extractinitial#1#2(initially #3)\@nil{%
- \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill (\extrakeytext no default, initially {\ttfamily#3})}%
+% \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill (\extrakeytext no default, initially {\ttfamily#3})}%
+ \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill (\extrakeytext initially {\ttfamily#3})}%
}
\def\extractequalinitial#1 (initially #2)\@nil{%
@@ -282,8 +289,17 @@
\def\myname{#1}%
\else%
\iffirsttime
- \def\mypath{#1@\protect\texttt{/#1/}!}%
- \firsttimefalse
+% CF : disabled for /pgfplots/ prefix.
+% \def\mypath{#1@\protect\texttt{/#1/}!}%
+% \firsttimefalse
+ \def\pgfplotslocTMPa{pgfplots}%
+ \edef\pgfplotslocTMPb{#1}%
+ \ifx\pgfplotslocTMPb\pgfplotslocTMPa
+ \def\mypath{}%
+ \else
+ \def\mypath{#1@\protect\texttt{/#1/}!}%
+ \fi
+ \firsttimefalse
\else
\expandafter\def\expandafter\mypath\expandafter{\mypath#1@\protect\texttt{#1/}!}%
\fi
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
index fbb96fa537d..f60170652e1 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
@@ -352,21 +352,21 @@
}}%
}%
-\def\pgfplotsshortstylekey #1=#2;{%
+\def\pgfplotsshortstylekey #1=#2\pgfeov{%
\pgfplotsassertcmdkeyexists{#1}%
\pgfplotsassertcmdkeyexists{#2}%
\begin{pgfplotskey}{#1=\marg{key-value-list}}
An abbreviation for \texttt{#2/.append style=}\marg{key-value-list}.
\end{pgfplotskey}
}
-\def\pgfplotsshortxystylekey #1=#2;{%
+\def\pgfplotsshortxystylekey #1=#2\pgfeov{%
\pgfplotsassertXYcmdkeyexists{#1}%
\pgfplotsassertXYcmdkeyexists{#2}%
\begin{pgfplotsxykey}{#1=\marg{key-value-list}}
An abbreviation for {\def\x{x}\texttt{#2/.append style=}}\marg{key-value-list} (or the respective style for $y$, {\def\x{y}\texttt{#2}}).
\end{pgfplotsxykey}
}
-\def\pgfplotsshortstylekeys #1,#2=#3;{%
+\def\pgfplotsshortstylekeys #1,#2=#3\pgfeov{%
\pgfplotsassertcmdkeyexists{#1}%
\pgfplotsassertcmdkeyexists{#2}%
\pgfplotsassertcmdkeyexists{#3}%
@@ -376,7 +376,7 @@
Different abbreviations for \texttt{#3/.append style=}\marg{key-value-list}.
\end{pgfplotskeylist}
}
-\def\pgfplotsshortxystylekeys #1,#2=#3;{%
+\def\pgfplotsshortxystylekeys #1,#2=#3\pgfeov{%
\pgfplotsassertXYcmdkeyexists{#1}%
\pgfplotsassertXYcmdkeyexists{#2}%
\pgfplotsassertXYcmdkeyexists{#3}%
@@ -387,4 +387,19 @@
\end{pgfplotsxykeylist}
}
+%
+% Creates and shows a colormap with specification '#1'.
+\def\pgfplotsshowcolormapexample#1{%
+ \pgfplotscreatecolormap{tempcolormap}{#1}%
+ \pgfplotsshowcolormap{tempcolormap}%
+}
+
+% Shows the colormap named '#1'.
+\def\pgfplotsshowcolormap#1{%
+ \pgfplotscolormaptoshadingspec{#1}{8cm}\result
+ \def\tempb{\pgfdeclarehorizontalshading{tempshading}{1cm}}%
+ \expandafter\tempb\expandafter{\result}%
+ \pgfuseshading{tempshading}%
+}
+
\makeatother
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib
index 37d144a7e99..0615f62d77c 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib
@@ -11,3 +11,16 @@
author = {Uwe Kern},
title = {{Extending \LaTeX's color facilities: the \texttt{xcolor} package}}
}
+
+@misc{acrotex,
+ author = {D. P. Story},
+ title = {{The Acro\TeX\ eDucation Bundle}},
+ howpublished = {\url{http://www.ctan.org/tex-archive/macros/latex/contrib/acrotex}},
+ note = {Sub packages |insdljs| and |eforms| are required for the clickable library.}
+}
+
+@misc{phptojs,
+ author = {Kevin van Zonneveld},
+ title = {{PhP to javascript conversion project (GPL)}},
+ howpublished = {\url{http://kevin.vanzonneveld.net/techblog/article/phpjs_licensing}}
+}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
index 048dc50e721..e4d0099f383 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
@@ -2,10 +2,10 @@
\label{sec:pgfplots:importexport}
This section contains information of how to single pictures into separate \pdf\ graphics files (or \eps\ graphics files). Furthermore, it explains a matlab (tm) script which allows to convert from matlab to \PGFPlots.
-\subsection{Export to \pdf/\eps}
+\subsection[Export to pdf/eps]{Export to {\normalfont\pdf/\eps}}
It is possible to export images to single \pdf-documents using routines of \pgfname\ and/or \Tikz.
-\subsubsection{Using the Externalization framework of \pgfname\ ``by hand''}
+\subsubsection[Using the Externalization framework of pgf by hand]{Using the Externalization framework of {\normalfont\pgfname} ``by hand''}
The first way to export \TeX-pictures to single graphics files is to use the externalization framework of \pgfname.
The basic idea is to encapsulate the desired parts with
@@ -39,7 +39,7 @@ A complete example may look as follows.
\beginpgfgraphicnamed{testfigure}
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\endpgfgraphicnamed
@@ -50,7 +50,7 @@ A complete example may look as follows.
\beginpgfgraphicnamed{testfigure2}
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^3);
+ \addplot {x^3};
\end{axis}
\end{tikzpicture}
\endpgfgraphicnamed
@@ -82,7 +82,7 @@ It is also possible to externalize graphics with the high-level library
|\usetikzlibrary{external}|
-\noindent which comes with (recent versions of) \Tikz\footnote{At the time of this writing, it is only available in the CVS~$2.0$ version of \pgfname, sorry.}. It is a front-end for |\beginpgfgraphicnamed| which automatically encapsulates every picture in your document with the required externalization commands and performs commands to generate all required graphics files.
+\noindent which comes with (very recent versions of) \Tikz. At the time of this writing, it is \textbf{only available in the CVS~$2.0$ version of} \pgfname, sorry. It is a front-end for |\beginpgfgraphicnamed| which automatically encapsulates every picture in your document with the required externalization commands and performs commands to generate all required graphics files.
\begin{enumerate}
\item Every |\begin{tikzpicture}| $\dotsc$ |\end{tikzpicture}| gets a file name. The file name can be assigned manually with |\tikzsetnextfilename|\marg{output file name} or automatically, in which case \meta{tex file name}|-figure|\meta{number} is used with an increasing \meta{number}.
@@ -105,7 +105,7 @@ The only steps which are necessary is to use
\begin{figure}
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\caption{Our first external graphics example}
@@ -114,7 +114,7 @@ The only steps which are necessary is to use
\begin{figure}
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^3);
+ \addplot {x^3};
\end{axis}
\end{tikzpicture}
\caption{A second graphics}
@@ -123,7 +123,7 @@ The only steps which are necessary is to use
\end{codeexample}
\noindent To enable the system calls, we type
\begin{codeexample}[code only]
-pdflatex --shell-escape test
+pdflatex -shell-escape test
\end{codeexample}
\noindent and \LaTeX\ will now generate the required graphics files |test-figure0.pdf| and |test-figure1.pdf| automatically.
@@ -137,10 +137,12 @@ The command |\tikzsetexternalprefix|\marg{file prefix} can be used to prepend a
\end{codeexample}
\noindent to produce |figures/test-figure0.pdf| and |figures/test-figure1.pdf| in our example.
-The complete reference documentation and remaining options are documented in the documentation for the ``PDF externalization library'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed.
+The complete reference documentation and remaining options are documented in the documentation for the ``PDF externalization library'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed or how to provide work-arounds with |.pdf| images and bounding box restrictions.
+\index{External Graphics!Bounding Box Issues}
+\index{Bounding Box Control!Image Externalization Problems}
\subsection{matlab2pgfplots.m}
-This is a matlab (tm) script which attempts to convert a matlab figure to \PGFPlots.
+This is a Matlab (tm) script which attempts to convert a matlab figure to \PGFPlots. It requires Matlab version 7.4 (or higher).
The idea is to
\begin{itemize}
@@ -165,3 +167,6 @@ A \texttt{bash}-script which simply starts matlab and runs
matlab2pgfplots( 'outputfile.pgf', 'fig', f );
\end{lstlisting}
See matlab2pgfplots.m above.
+
+\subsection{SVG Output}
+It is possible to write every single \Tikz\ picture into a scalable vector graphics (\texttt{.svg}) file. This has nothing to do with \PGFPlots, it is a separate driver of \PGF. Please refer to~\cite[Section ``Producing HTML / SVG Output'']{tikz}.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex
index b94fa632f7b..e87dd0f8bd0 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex
@@ -1,7 +1,7 @@
% main=manual.tex
-\section{Installation}
-\subsection{Licensing}
+\subsection{Installation and Prerequisites}
+\subsubsection{Licensing}
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
@@ -18,17 +18,23 @@ doc/latex/pgfplots/gpl-3.0.txt
\end{verbatim}
You may also visit~\url{http://www.gnu.org/licenses}.
-\subsection{Prerequisites}
+\subsubsection{Prerequisites}
\PGFPlots\ requires \PGF\ with \textbf{at least version~$2.0$}. It is used with
\begin{verbatim}
\usepackage{pgfplots}
\end{verbatim}
-in your preamble (see section~\ref{sec:tex:dialects} for information about how to use it with Con{\TeX}t and plain \TeX). There are several ways how to teach \TeX\ where to find the files. Choose the option which fits your needs best.
+in your preamble (see section~\ref{sec:tex:dialects} for information about how to use it with Con{\TeX}t and plain \TeX).
-\subsection{Installation in Windows}
-Windows users often use Mik\TeX\ which downloads the latest stable package versions automatically. As far as I know, you do not need to install anything manually here.
-\subsection{Assigning the \texttt{TEXINPUTS} Variable}
+%\subsubsection{Installation}
+There are several ways how to teach \TeX\ where to find the files. Choose the option which fits your needs best.
+
+\subsubsection{Installation in Windows}
+Windows users often use Mik\TeX\ which downloads the latest stable package versions automatically. As far as I know, you do not need to install anything manually here. However, Mik\TeX\ provides a feature to install packages locally in its own \TeX-Directory-Structure (TDS). This is the preferred way if you like to install newer version than those of Mik\TeX. The basic idea is to unzip \PGFPlots\ in a directory of your choice and use configure the Mik\TeX\ Package Manager to use this specific directory with higher priority than its default paths.
+
+See also section~\ref{pgfplots:tds} for more information about separate TDS directories.
+
+\subsubsection{Installation in Any Directory - the \texttt{TEXINPUTS} Variable}
You can simply install \PGFPlots\ anywhere on your disc, for example into
\begin{verbatim}
/foo/bar/pgfplots.
@@ -49,22 +55,45 @@ so that the \TeX-documentation system finds the files |pgfplots.pdf| and |pgfplo
Please refer to your operating systems manual for how to set environment variables.
-\subsection{Installation into a local \texttt{texmf}-directory}
+\subsubsection{Installation Into a Local \texttt{texmf}-Directory}
Copy \PGFPlots\ to a local \texttt{texmf} directory like \lstinline!~/texmf! in your home directory. Then, install \PGFPlots\ into the subdirectory \lstinline!texmf/tex/generic/pgfplots! and run \lstinline!texhash!.
-\subsection{Installation into a local TDS compliant \texttt{texmf}-directory}
-A TDS conforming installation will use the same base directory as in the last section, but it requires to merge the contents of `\texttt{latex}' into `\texttt{texmf/tex/latex}'; the contents of `\texttt{generic}' to `\texttt{texmf/tex/generic}' and the contents of `\texttt{doc}' to `\texttt{texmf/doc}'.
+\subsubsection{Installation Into a Local TDS Compliant \texttt{texmf}-Directory}
+\label{pgfplots:tds}
+A TDS conforming installation will use the same base directory as in the last section. Since \PGFPlots\ comes in TDS conforming directory structure, you can simply unpack the files into a directory of your choice and configure \TeX\ to use this directory as further include path.
Do not forget to run \lstinline!texhash!.
-\subsection{If everything else fails...}
-If \TeX\ still doesn't find your files, you can copy all \lstinline!.sty! and all |.tex|-files into your current project's working directory.
+\subsubsection{Installation If Everything Else Fails...}
+If \TeX\ still doesn't find your files, you can copy all \lstinline!.sty! and all |.code.tex|-files into your current project's working directory.
Please refer to \url{http://www.ctan.org/installationadvice/} for more information about package installation.
-\subsection{Restrictions for DVI-Viewers and \texttt{dvipdfm}}
+\subsection{Troubleshooting -- Error Messages}
+This section discusses some problems which may occur when using \PGFPlots.
+Some of the error messages are shown in the index, take a look at the end of this manual (under ``Errors'').
+
+
+\subsubsection{Problems with available Dimen-registers}
+To avoid problems with the many required \TeX-registers for \PGF\ and \PGFPlots, you may want to include
+\begin{verbatim}
+\usepackage{etex}
+\end{verbatim}
+as first package. This avoids problems with ``no room for a new dimen''
+\index{Error Messages!No room for a new dimen}%
+in most cases. It should work with any modern installation of \TeX\ (it activates the e-\TeX\ extensions).
+
+\subsubsection{Dimension Too Large Errors}
+The core mathematical engine of \PGF\ relies on \TeX\ registers to perform fast arithmetics. To compute $50+299$, it actually computes |50pt+299pt| and strips the |pt| suffix of the result. Since \TeX\ registers can only contain numbers up to $\pm 16384$, overflow error messages like ``Dimension too large'' occur if the result leaves the allowed range. Normally, this should never happen -- \PGFPlots\ uses a floating point unit with data range $\pm 10^{324}$ and performs all mappings automatically. However, there are some cases where this fails. Some of these cases are:
+\begin{enumerate}
+ \item The axis range (for example, for $x$) becomes \emph{relatively} small. It's no matter if you have absolutely small ranges like $[10^{-17},10^{-16}]$. But if you have an axis range like $[1.99999999,2]$, where a lot of significant digits are necessary, this may be problematic.
+ \item The |axis equal| key will be confused if $x$ and $y$ have a very different scale.
+ \item You may have found a bug -- please contact the developers.
+\end{enumerate}
+
+\subsubsection{Restrictions for DVI-Viewers and \texttt{dvipdfm}}
\label{sec:drivers}%
\PGF\ is compatible with
\begin{itemize}
@@ -91,3 +120,9 @@ Furthermore, \PGF\ needs to know a \emph{driver} so that the DVI file can be con
Please read the corresponding sections in~\cite[Section 7.2.1 and 7.2.2]{tikz} if you have further questions. These sections also contain limitations of particular drivers.
The choice which won't produce any problems at all is |pdflatex|.
+
+\subsubsection{Problems with \TeX's Memory Capacities}
+\PGFPlots\ can handle small up to medium sized plots. However, \TeX\ has never been designed for data plots -- you will eventually face the problem of small memory capacities. See section~\ref{sec:pgfplots:optimization} for how to enlarge them.
+
+\subsubsection{Other Problems}
+Please contact the authors (preferrably by mail). Visit the webpages shown above to get contact information.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
index c81d1a1268e..9bdbed56dff 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
@@ -7,7 +7,7 @@
\begin{description}
\def\HEAD{%
\small
- \lstset{boxpos=b,breaklines=false,aboveskip=3pt,belowskip=3pt}%
+ %\lstset{boxpos=b,breaklines=false,aboveskip=3pt,belowskip=3pt}%
%\hspace{-1cm}%
\begin{tabular}{*{2}{p{4cm}}}%
}%
@@ -101,7 +101,6 @@ Plotting is done using \lstinline|\begin{axis} ... \addplot ...; \end{axis}|, wh
\begin{tikzpicture}
\begin{axis}[
xlabel=Cost,
- name=an axis,
ylabel=Error]
\addplot[color=red,mark=x] coordinates {
(2,-2.8559703)
@@ -116,23 +115,38 @@ Plotting is done using \lstinline|\begin{axis} ... \addplot ...; \end{axis}|, wh
\end{tikzpicture}
\end{codeexample}
+
\begin{codeexample}[]
-\begin{tikzpicture}%
+\begin{tikzpicture}
\begin{axis}[
xlabel=$x$,
- ylabel=$\sin(x)$,
- name=an axis,
+ ylabel={$f(x) = x^2 - x +4$}
]
- \addplot plot[id=sin] function{sin(x)};
+ % use TeX as calculator:
+ \addplot {x^2 - x +4};
\end{axis}
-\end{tikzpicture}%
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ xlabel=$x$,
+ ylabel=$\sin(x)$
+ ]
+ % invoke external gnuplot as
+ % calculator:
+ \addplot gnuplot[id=sin]{sin(x)};
+ \end{axis}
+\end{tikzpicture}
\end{codeexample}
-The |plot coordinates| and |plot function| commands are two of the several \Tikz\ ways to create plots, see section~\ref{sec:addplot} for more details\footnote{Please note that you need \lstinline{gnuplot} installed to use \lstinline{plot function}.}. The options `|xlabel|' and `|ylabel|' define axis descriptions.
+
+The |plot coordinates|, |plot gnuplot| and |plot expression| commands are three of the several supported ways to create plots, see section~\ref{sec:addplot} for more details\footnote{Please note that you need \lstinline{gnuplot} installed to use \lstinline{plot gnuplot}.} and the remaining ones (|plot file| and |plot table|). The options `|xlabel|' and `|ylabel|' define axis descriptions.
\subsection{Two plots in the same axis}
Multiple |\addplot|-commands can be placed into the same axis.
% generated with this statement:
- %\addplot plot[id=filesuffix_noise,domain=-6:5,samples=10] function{(-x**5 - 242 + (-300 + 600*rand(0)))};
+ %\addplot plot[id=filesuffix_noise,domain=-6:5,samples=10] gnuplot{(-x**5 - 242 + (-300 + 600*rand(0)))};
\begin{codeexample}[leave comments]
\begin{tikzpicture}
\begin{axis}[
@@ -141,7 +155,7 @@ Multiple |\addplot|-commands can be placed into the same axis.
grid=major,
]
- \addplot plot[id=filesuffix] function{(-x**5 - 242)};
+ \addplot plot[id=filesuffix] gnuplot{(-x**5 - 242)};
\addlegendentry{model}
\addplot coordinates {
@@ -298,7 +312,7 @@ The cycle list can be modified, see the reference below.
\subsection{Scaling plots}
You can use any of the \Tikz\ options to modify the appearance. For example, the ``|scale|'' transformation takes the picture as such and scales it.
-{%
+
\begin{codeexample}[]
\begin{tikzpicture}[scale=0.5]
\begin{loglogaxis}[
@@ -344,3 +358,5 @@ However, you can also scale plots by assigning a |width=5cm| and/or |height=3cm|
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
+
+\endinput
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex
new file mode 100644
index 00000000000..0c49dd0b0be
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex
@@ -0,0 +1,178 @@
+\section{Related Libraries}
+This section describes some libraries which come with \PGFPlots, but they are more or less special and need to be activated separately.
+
+\subsection{Dates as Input Coordinates}
+\begin{tikzlibrary}{dateplot}
+ A library which allows to use dates like |2008-01-01| as input coordinates in plots. The library converts dates to numbers and tick labels will be pretty-printed dates.
+
+ This library is documented in section~\ref{pgfplots:sec:symbolic:coords} on page~\pageref{pgfplots:sec:date:coords}.
+\end{tikzlibrary}
+
+\subsection{Clickable Plots}
+\begin{tikzlibrary}{pgfplotsclickable}
+ A library which generates small popups whenever one clicks into a plot. The popup displays the coordinate under the mouse pointer. Furthermore, the library allows to display slopes if one holds the mouse pressed and drags it to another point in the plot.
+
+ Although this library has been written for \PGFPlots, it can be used independently of an \PGFPlots\ environment.
+
+ It is completely sufficient to write
+\begin{codeexample}[code only]
+\usetikzlibrary{pgfplotsclickable}
+\end{codeexample}
+ \noindent in the document preamble. This will automatically prepare every plot.
+
+ The library works with Acrobat Javascript and \pdf\ forms: every plot becomes a push--button.
+
+ \includegraphics[height=6cm]{figures/pgfplotsclickable-fig1.png}
+ \rlap{\includegraphics[height=6cm]{figures/pgfplotsclickable-fig2.png}}\hfill
+
+ \includegraphics[height=6cm]{figures/pgfplotsclickable-fig3.png}
+ \rlap{\includegraphics[height=6cm]{figures/pgfplotsclickable-fig4.png}}\hfill
+
+ \nobreak
+ These screenshots show the result of clicking into the axis range (left column) and of dragging from one point to another (right column). The second case shows start- and end points and the slope of the line segment in--between.
+
+ This document has been produces with |pgfplotsclickable|, so it is possible to load it into Acrobat Reader and simply click into a plot.
+
+ A click places an annotation at the coordinate under the mouse pointer, a snap--to--nearest feature is not available (yet?).
+
+ \paragraph{Requirements:}
+ \begin{itemize}
+ \item The library relies on the \LaTeX\ packages |insdljs| (``Insert document level Javascript'') and |eforms| which are both part of the freely available |AcroTeX| education bundle~\cite{acrotex}\footnote{These packages rely on \LaTeX, so the library is only available for \LaTeX, not for plain \TeX\ or Con\TeX t.}. The |insdljs| package creates a temporary file with extension |.djs|.
+
+ \item At the time of this writing, only Adobe Acrobat Reader interpretes Javascript and Forms properly. The library doesn't have any effect if the resulting document is used in other viewers (as far as I know).
+
+ \end{itemize}
+
+ \paragraph{Compatibility issues:}
+ There a several restrictions when using this library. Most of them will vanish in future versions -- but up to now, I can't do magic.
+ \begin{itemize}
+ \item The library does not yet support rotated axes. Use |clickable=false| for those axes.
+ \item The library works only with |pdflatex|, |dvips| or |dvipdfm| are not supported\footnote{In fact, they should be. I don't really know why they don't $\hdots$ any hint is welcome.}.
+
+ \item Up to now, it is \emph{not} possible to use this library in conjunction with the image externalization methods of section~\ref{sec:pgfplots:importexport}.
+
+ To be more precise, the exported \pdf\ documents will work correctly, but the |\includegraphics| command does not import the dynamic features.
+ Please note that the exported \pdf\ documents will only work if |\usepackage[pdftex]{eforms}| is placed \emph{before} loading \pgfname, \Tikz\ or \PGFPlots.
+
+ \item The library automatically calls |\begin{Form}| at |\begin{document}| and |\end{Form}| at the end of the document. This environment of |hyperref| is necessary for dynamic user interaction and should be kept in mind if the document contains other form elements.
+ \end{itemize}
+
+ \paragraph{Acknowledgements:}
+ \begin{itemize}
+ \item I have used a javascript |sprintf| implementation of Kevin van Zonneveld~\cite{phptojs} (the javascript API has only a limited set of conversions).
+ \end{itemize}
+\end{tikzlibrary}
+
+It is possible to customize |pgfplotsclickable| with several options.
+
+\begin{pgfplotskey}{clickable=\mchoice{true,false} (initially true)}
+ Allows to disable the library for single plots.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{annot/js fillColor=\marg{javascript color} (initially ["RGB",1,1,.855])}
+ Sets the background (fill) color of the short popup annotations.
+
+ Possible choices are |transparent|, gray, RGB or CMYK color specified as four--element--arrays of the form
+ |["RGB", |\meta{red}|,|\meta{green}|,|\meta{blue}|]|. Each color component is between $0$ and $1$.
+
+ Again: this option is for Javascript. It is \emph{not} possible to use colors as in \pgfname.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{annot/point format=\marg{sprintf-format} (initially {(\%.1f,\%.1f)})}
+ Allows to provide an |sprintf| format string which is used to fill the annotations with text.
+ The first argument to |sprintf| is the $x$-coordinate and the second argument is the $y$-coordinate.
+
+ The |every semilogx axis|, |every semilogy axis| and |every loglog axis| styles have been updated to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ every semilogy axis/.append style={/pgfplots/annot/point format={(\%.1f,\%.1e)}},
+ every semilogx axis/.append style={/pgfplots/annot/point format={(\%.1e,\%.1f)}},
+ every loglog axis/.append style={/pgfplots/annot/point format={(\%.1e,\%.1e)}}
+}
+\end{codeexample}
+ \noindent such that every logarithmic coordinate is displayed in scientific format.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{annot/slope format=\marg{sprintf-format} (initially \%.1f*x \%+.1f)}
+ Allows to provide an |sprintf| format string which is used to fill the slope--annotation with text.
+ The first argument is the slope and the second the line offset.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{annot/printable=\mchoice{true,false} (initially false)}
+ Allows to configure whether the small annotations will be printed. Otherwise, they are only available on screen.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{annot/font=\marg{javascript font name} (initially font.Times)}
+ Allows to choose a javascript font for the annotations. Possible choices are limited to what javascripts accepts (which is \emph{not} the same as \LaTeX). The default fonts and its names are shown below.
+
+ \begin{center}
+ \begin{tabular}{ll}
+ \toprule
+ Font Name & Name in Javascript\\
+ \midrule
+ Times-Roman & font.Times\\
+ Times-Bold & font.TimesB\\
+ Times-Italic & font.TimesI\\
+ Times-BoldItalic & font.TimesBI\\
+ Helvetica & font.Helv\\
+ Helvetica-Bold & font.HelvB\\
+ Helvetica-Oblique & font.HelvI\\
+ Helvetica-BoldOblique & font.HelvBI\\
+ Courier & font.Cour\\
+ Courier-Bold & font.CourB\\
+ Courier-Oblique & font.CourI\\
+ Courier-BoldOblique & font.CourBI\\
+ Symbol & font.Symbol\\
+ ZapfDingbats & font.ZapfD\\
+ \bottomrule
+ \end{tabular}
+ \end{center}
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{annot/textSize=\marg{Size in Point} (initially 11)}
+ Sets the text size of annotations in points.
+\end{pgfplotskey}
+
+\subsubsection{Using the Clickable Library in Other Contexts}
+This library provides essentially one command, |\pgfplotsclickablecreate| which creates a clickable area of predefined size, combined with javascript interaction code. It can be used independently of \PGFPlots.
+
+\begin{command}{\pgfplotsclickablecreate\oarg{required key-value-options}}
+ Creates an area which is clickable. A click produces a popup which
+ contains information about the point under the cursor.
+
+ The complete (!) context needs to be provided using key-value-pairs, either set before
+ calling this method of inside of \oarg{required key-value-options}.
+
+ This command actually creates an AcroForm which invokes javascript
+ whenever it is clicked. A javascript Object is created which
+ represents the context (axis limits and options). This javascript
+ object is available at runtime.
+
+ This method is public and it is \emph{not} restricted to \PGFPlots.
+ The \PGFPlots\ hook simply initialises the required key-value-pairs.
+
+ This method does not draw anything. It initialises only a
+ clickable area and javascript code.
+
+ The required key-value-pairs are documented below.
+
+ \paragraph{Attention:} Complete key-value validation is \emph{not} performed here. It
+ can happen that invalid options will produce javascript bugs when
+ opened with Acrobat Reader. Use the javascript console to find them.
+\end{command}
+
+\noindent All options described in the following are only interesting for users who intend to use this library without \PGFPlots.
+
+\begin{pgfplotskey}{annot/width=\marg{dimension} (initially -)}
+ This required key communicates the area's width to |\pgfplotsclickablecreate|. It must be a \TeX\ dimension like |5cm|.
+\end{pgfplotskey}
+\begin{pgfplotskey}{annot/height=\marg{dimension} (initially -)}
+ This required key communicates the area's height to |\pgfplotsclickablecreate|. It must be a \TeX\ dimension like |5cm|.
+\end{pgfplotskey}
+\begin{pgfplotskey}{annot/jsname=\marg{string} (initially -)}
+ This required key communicates a unique identifier to |\pgfplotsclickablecreate|. This identifier is used to identify the object in javascript, so there can't be more than one of them. If it is empty, a default identifier will be created.
+\end{pgfplotskey}
+
+\begin{pgfplotskeylist}{annot/xmin=\marg{number},annot/xmax=\marg{number},annot/ymin=\marg{number},annot/ymax=\marg{number} (initially empty)}
+ These required keys communicate the axis limits to |\pgfplotsclickablecreate|. They should be set to numbers which can be assigned to a javascript floating point number (standard IEEE double precision).
+\end{pgfplotskeylist}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.mst b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.mst
new file mode 100644
index 00000000000..642be497a04
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.mst
@@ -0,0 +1,17 @@
+headings_flag 1
+heading_prefix "{\\bf ---~"
+heading_suffix "~---}"
+delim_0 "\\dotfill\\indexpageno{"
+delim_1 "\\dotfill\\indexpageno{"
+delim_2 "\\dotfill\\indexpageno{"
+delim_t "}"
+delim_n "}, \\indexpageno{"
+delim_r "} -- \\indexpageno{"
+suffix_2p "}f.{"
+suffix_3p "}ff.{"
+symhead_negative "Symbols"
+symhead_positive "Symbols"
+numhead_negative "Numbers"
+numhead_positive "Numbers"
+quote '+'
+line_max 255
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf
index 5f8f5f5dc3e..5b9883b8734 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
index fdc26bad5ad..640da6556ec 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
@@ -21,6 +21,14 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[a4paper]{ltxdoc}
+\usepackage{makeidx}
+
+% DON't let hyperref overload the format of index and glossary.
+% I want to do that on my own in the stylefiles for makeindex...
+\makeatletter
+\let\@old@wrindex=\@wrindex
+\makeatother
+
\usepackage{ifpdf}
\ifpdf
\usepackage[pdftex]{hyperref}
@@ -29,19 +37,31 @@
\fi
\hypersetup{pdfborder={0 0 0}}
+\makeatletter
+\let\@wrindex=\@old@wrindex
+\makeatother
+
+% Formatiere Seitennummern im Index:
+\newcommand{\indexpageno}[1]{%
+ {\bfseries\hyperpage{#1}}%
+}
+
+
\newcommand{\R}{\mathbb{R}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\Z}{\mathbb{Z}}
+\long\def\COMMENTLOWLEVEL#1\ENDCOMMENT{}
+\def\ENDCOMMENT{}
+
\usepackage{textcomp}
+\usepackage{booktabs}
\usepackage{calc}
\usepackage[formats]{listings}
%\usepackage{courier} % don't use it - the '^' character can't be copy-pasted in courier
-%--------------------------------------------------
-% \usepackage{array}
-%--------------------------------------------------
+\usepackage{array}
\lstset{%
basicstyle=\ttfamily,
language=[LaTeX]tex, % Seems as if \lstset{language=tex} must be invoked BEFORE loading tikz!?
@@ -61,13 +81,21 @@
%\def\pgfsysdriver{pgfsys-pdftex.def}
\usepackage{pgfplots}
+\ifpdf
+ \usetikzlibrary{pgfplotsclickable}
+\fi
+
+%\usepackage{fp}
+% ATTENTION:
+% this requires pgf version NEWER than 2.00 :
+%\usetikzlibrary{fixedpointarithmetic}
+
\usetikzlibrary{dateplot}
\usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
\usepackage{amsmath,amssymb}
\usepackage{xxcolor}
\usepackage{pifont}
-\usepackage{makeidx}
\usepackage[latin1]{inputenc}
\usepackage{amsmath}
\usepackage{eurosym}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
index 40049e9d851..e5ba9fe8f32 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
@@ -77,7 +77,7 @@ coordinates
\begin{axis}
\addplot plot
[id=parable,domain=-5:5]
- function{4*x**2 - 5}
+ gnuplot{4*x**2 - 5}
node[pin=180:{$4x^2-5$}]{};
\end{axis}
\end{tikzpicture}
@@ -129,6 +129,7 @@ Some more details:
\item For normal plots, \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 at least~$5$ significant decimal digits for the mantisse. 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 \]
with properly chosen integers $s_x, s_y \in \Z$ and shifts $a_x,a_y\in \R$. Section~\ref{sec:disabledatascaling} contains a description of |disabledatascaling| and provides more details about the transformation.
+ \index{Accuracy!Floating Point in \PGFPlots}%
\item As a consequence of the coordinate parsing routines, you can't use the mathematical expression parsing method of \PGF\ as coordinates (that means: you will need to provide coordinates without suffixes like ``cm'' or ``pt'' and you can't invoke mathematical functions).
@@ -136,12 +137,13 @@ Some more details:
The automatic computation of axis limits works as follows:
\begin{enumerate}
\item Every coordinate will be checked. Care has been taken to avoid \TeX's limited numerical capabilities.
- \item Since more than one |\addplot| command may be used inside an |\begin{axis}...\end{axis}|, all drawing commands will be postponed until |\end{axis}|.
+ \item Since more than one |\addplot| command may be used inside of |\begin{axis}...\end{axis}|, all drawing commands will be postponed until |\end{axis}|.
\end{enumerate}
\end{itemize}
\end{command}
-\subsubsection{Providing Input Coordinates}
+\subsubsection{Coordinate Lists}
+\label{pgfplots:providing:input}
\begin{addplotoperation}[]{coordinates}{\marg{coordinate list}}
The `|plot coordinates|' command is provided by \Tikz\ and reads its input data from a sequence of point coordinates.
@@ -173,8 +175,19 @@ or
These error coordinates are only used in case of error bars, see section~\ref{sec:errorbars}. 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, |plot 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 page~\pageref{pgfplots:scatterclasses} for an example). Meta data (if any) must be provided after the coordinates and after error bar bounds (if any) in square brackets:
+\begin{codeexample}[code only]
+\addplot plot coordinates {
+ (1300,1e-6) [1]
+ (2600,5e-7) [2]
+ (4000,1e-7) [3]
+};
+\end{codeexample}
+Please refer to the documentation of |scatter src| on page~\pageref{pgfplots:scatter:src} for more information about per point meta data.
\end{addplotoperation}
+\subsubsection{Reading Coordinates From Files}
\begin{addplotoperation}[]{file}{\marg{name}}
\PGFPlots\ supports two ways to read plot coordinates of external files, and one of them is the \Tikz-command `|plot file|'. It is to be used like
@@ -204,13 +217,20 @@ Plot file accepts one optional argument,
\noindent
which allows to skip over a non-comment header line. This allows to read the same input files as |plot table| by skipping over column names. Please note that comment lines do not count as lines here.
+The input method |plot file| can also read meta data for every coordinate. As already explained for |plot coordinates| (see above), meta data can be used to change colors or other style parameters for every marker separately. Now, if |scatter src| is set to |explicit| or to |explicit symbolic| and the input method is |plot file|, one further element will be read from disk - for every line. Meta data is always the last element which is read. See page~\pageref{pgfplots:scatter:src} for information and examples about per point meta data and page~\pageref{pgfplots:scatterclasses} for an application example using |scatter/classes|.
+
+
Plot file is very similar to |plot table|: you can achieve the same effect with
\begin{codeexample}[code only]
\addplot table[x index=0,y index=0,header=false] {datafile.dat};
\end{codeexample}
\noindent Due to its simplicity, |plot file| is slightly faster while |plot table| allows higher flexibility.
+
+Technical note: every opened file will be protocolled into your log file.
\end{addplotoperation}
+\subsubsection{Reading Coordinates From Tables}
+
\begin{addplotoperation}[]{table}{\oarg{column selection}\marg{file}}
\PGFPlots\ comes with a new plotting command, the `|plot table|' macro. It's usage is similar in spirit to `|plot file|', but its flexibility is higher. Given a data file like
\begin{codeexample}[code only]
@@ -230,7 +250,7 @@ one may want to plot `|dof|' versus `|L2|' or `|dof|' versus `|Lmax|'. This can
\begin{tikzpicture}
\begin{loglogaxis}[
xlabel=Dof,
- ylabel=$L_2$ error$]
+ ylabel=$L_2$ error]
\addplot table[x=dof,y=L2] {datafile.dat};
\end{loglogaxis}
\end{tikzpicture}
@@ -240,7 +260,7 @@ or
\begin{tikzpicture}
\begin{loglogaxis}[
xlabel=Dof,
- ylabel=$L_infty$ error$]
+ ylabel=$L_infty$ error]
\addplot table[x=dof,y=Lmax] {datafile.dat};
\end{loglogaxis}
\end{tikzpicture}
@@ -268,14 +288,17 @@ If you do prefer to access columns by column indices instead of column names (or
Summary and remarks:
\begin{itemize}
- \item Use |plot table[x=|\marg{column name}|,y=|\marg{column name}|]}| to access column names. Those names are case sensitive and need to exist.
- \item Use |plot table[x index=|\marg{column index}|,y index=|\marg{column index}|]}| to access column indices. Indexing starts with~$0$. You may also use an index for~$x$ and a column name for~$y$.
+ \item Use |plot table[x=|\marg{column name}|,y=|\marg{column name}|]| to access column names. Those names are case sensitive and need to exist.
+ \item Use |plot table[x index=|\marg{column index}|,y index=|\marg{column index}|]| to access column indices. Indexing starts with~$0$. You may also use an index for~$x$ and a column name for~$y$.
\item Use |plot table[header=false] |\marg{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.
\item 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 \marg{source columns}. See section~\ref{sec:errorbars} for details about error bars.
+ \item It is possible to read per point meta data (usable in |scatter src|, see page~\pageref{pgfplots:scatter:src}) as has been discussed for |plot coordinates| and |plot file| above. The meta data column can be provided using the |meta| key (or the |meta index| key).
\item Use |plot table[|\meta{source columns}|] from |\marg{\textbackslash macro} to use a pre--read table. Tables can be read using
\begin{codeexample}[code only]
\pgfplotstableread{datafile.dat}\macroname.
\end{codeexample}
+ The keyword `|from|' can be omitted.
+
\item The accepted input format of those tables is as follows:
\begin{itemize}
\item Columns are usually separated by white spaces (at least one tab or space).
@@ -292,6 +315,10 @@ Summary and remarks:
\item The accepted number format is the same as for `|plot coordinates|', see above.
\item If you omit column selectors, the default is to plot the first column against the second. That means |plot table| does exactly the same job as |plot file| for this case.
\end{itemize}
+ \item It \emph{is} possible to create new columns out of existing ones, see the \PGFPlotstable\ manual section ``Postprocessing Data in New Columns''.
+
+ In this context, you should consider using the key |read completely|, see below.
+ \item Technical note: every opened file will be protocolled into your log file.
\end{itemize}
\end{addplotoperation}
@@ -305,115 +332,244 @@ Summary and remarks:
Please note that column \emph{aliases} will be considered if unknown column names are used. Please refer to the manual of \PGFPlotstable\ which comes with this package.
\end{pgfplotsxykeylist}
\begin{pgfplotsxykeylist}{%
- \x\ error=\marg{column name},
- \x\ error index=\marg{column index}}
+ table/\x\ error=\marg{column name},
+ table/\x\ error index=\marg{column index}}
These keys define input sources for error bars with explicit error values. Please see section~\ref{sec:errorbars} for details.
\end{pgfplotsxykeylist}
+\begin{pgfplotsxykeylist}{%
+ table/meta=\marg{column name},
+ table/meta index=\marg{column index}}
+ These keys define input sources for per point meta data. Please see page~\pageref{pgfplots:scatter:src} for details about meta data or the documentation for |plot coordinates| and |plot file| for further information.
+\end{pgfplotsxykeylist}
\begin{key}{/pgfplots/table/col sep=\mchoice{space,comma,semicolon,colon,braces} (initially space)}
Allows to choose column separators for |plot table|. Please refer to the manual of \PGFPlotstable\ which comes with this package for details about |col sep|.
\end{key}
+\begin{key}{/pgfplots/table/read completely=\marg{true,false} (initially false)}
+ Allows to customize |\addplot table|\marg{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'').
-\begin{addplotoperation}[]{function}{\marg{gnuplot code}}
-The plot function command uses the external program |gnuplot| to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot function| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with |plot function| (it configures high precision output). You should use different ids to avoid conflicts in such a case.}).
+ \paragraph{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 datastructures 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.
+\end{key}
-Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example
-\begin{codeexample}[code only]
-pdflatex -shell-escape filename.tex.
+\subsubsection{Computing Coordinates with Mathematical Expressions}
+
+\begin{addplotoperation}[]{expression \marg{math expr}}{}
+ This input method allows to provide mathematical expressions which will be sampled. But unlike |plot 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=|\meta{N} as for plot gnuplot.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}
+ \addplot expression {x^2 + 4};
+ \addplot expression {-5*x^3 - x^2};
+\end{axis}
+\end{tikzpicture}
\end{codeexample}
-Sometimes it is called |shell-escape| or |enable-write18|.
+
+Please note that \PGF's math parser uses degrees for trigonometric functions:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
-\addplot plot[id=sin]
- function{sin(x)};
+ \addplot expression[domain=0:360]
+ {sin(x)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
+\noindent If you want to use radians, use
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}
+ \addplot expression[domain=-pi:pi]
+ {sin(deg(x))};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent to convert the radians to degrees. The plot expression parser also accepts some more options like |samples at=|\marg{coordinate list} or |domain=|\meta{first}|:|\meta{last} which are described below.
+
+\paragraph{Remarks}
+\begin{enumerate}
+ \item 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|, for example. Then, |x| will be the same as |\t| (there won't be a short-hand name for user defined variable names).
+\index{x@\texttt{\textbackslash x} In Coordinate Expressions}%
+%\index{y@\texttt{\textbackslash y} In Coordinate Expressions}%
+
+ \item 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 constanst |pi| and |e|, |^| (power operation), |factorial|\footnote{Starting with \PGF\ versions newer than $2.00$, you can use the postfix operator \texttt{!} instead of \texttt{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~\cite{tikz}, the FPU routines have been developed as part of \PGFPlots. The documentation for both parts can be found in~\cite{tikz}.
+
+ Please note, however, that trigonometric functions are defined in degrees. The character `|^|' is used for exponentiation (not `|**|' as in gnuplot).
+
+ \item If the $x$ axis is logarithmic, samples will be drawn logarithmically.
+
+ \item Please note that plot expression does not allow per point meta data.
+\end{enumerate}
+
+\paragraph{About the precision and number range:}
+\index{Accuracy!High Precision for Plot Expression}%
+\index{Errors!dimension too large}%
+ \index{Precision}\index{Floating Point Unit} Starting with version 1.2, |plot 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.
+
+ In case the |fpu| does not provide the desired mathematical function or is too slow\footnote{Or in case you find a bug$\dotsc$}, you should consider using the |plot gnuplot| method which invokes the external, freely available program |gnuplot| as desktop calculator.
\begin{codeexample}[]
\begin{tikzpicture}
-\begin{semilogyaxis}
-\addplot plot[id=exp,domain=0:10]
- function{exp(x)};
-\end{semilogyaxis}
+ \begin{loglogaxis}[
+ title={$\frac{1}{x^2}$}]
+ \addplot[blue]
+ expression[domain=1:1e30]
+ {x^-2};
+ \end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
-The \meta{style options} determine the appearance of the plotted function; these parameters also affect the legend. The \meta{behavior options} are specific to the gnuplot interface. These options are described in all detail in \cite[section~18.6]{tikz}. A short summary is shown below.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{semilogyaxis}[
+ title={$e^x$ logarithmically plotted}]
+ \addplot[blue]
+ expression[domain=1:700]
+ {exp(x)};
+ \end{semilogyaxis}
+\end{tikzpicture}
+\end{codeexample}
\end{addplotoperation}
-\begin{key}{/tikz/domain=\meta{start}:\meta{end} (initially [-5:5])}
+\begin{addplotoperation}[]{\marg{math expression}}{}
+ Use
+
+ |\addplot |\marg{math expression}|;|
+
+ as short-hand equivalent for
+
+ |\addplot expression |\marg{math expression}|;|
+\end{addplotoperation}
+
+\begin{addplotoperation}[]{(\meta{$x$ expression},\meta{$y$ expression})}{}
+ 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, you can't use round braces for either \meta{$x$ expression} or \meta{$y$ expression}. You will need to introduce curly braces additionally to round braces.
+\end{addplotoperation}
+
+\begin{key}{/pgfplots/domain=\meta{start}:\meta{end} (initially [-5:5])}
Determines the plotted range. This is not necessarily the same as the axis limits (which are configured with the |xmin|/|xmax| options).
- This option is also used for plot expression, see below.
-\end{key}
+ This option is used for |plot expression| and for |plot gnuplot|.
-\begin{key}{/tikz/id=\marg{unique string identifier}}
- A unique identifier for the current plot. It is used to generate temporary filenames for |gnuplot| output.
-\end{key}
+ The |domain| key won't be used if |samples at| is specified; |samples at| has higher precedence.
-\begin{key}{/tikz/prefix=\marg{file name prefix}}
- A common path prefix for temporary filenames (see \cite[section~18.6]{tikz} for details).
+ \paragraph{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.
\end{key}
-\begin{key}{/tikz/samples=\marg{number}}
- Sets the number of sample points.
-\end{key}
+\begin{key}{/pgfplots/samples=\marg{number} (initially 25)}
+ Sets the number of sample points for |plot expression| and |plot gnuplot|.
-\begin{key}{/tikz/raw gnuplot}
- Disables the use of |samples| and |domain|.
+ 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.
\end{key}
-\noindent
-Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction.
+\begin{pgfplotskey}{samples at=\marg{coordinate list}}
+ Sets the $x$ coordinates for |plot expression| explicitly. This overrides |domain| and |samples|.
-\begin{addplotoperation}[]{(\meta{$x$ expression},\meta{$y$ expression})}{}
- Similar to |plot function|, this input method allows to provide expressions which will be sampled. But unlike |plot function|, the expressions are evaluated using the math parser of \PGF, no external program is required.
-\begin{codeexample}[]
-\begin{tikzpicture}
-\begin{axis}
- \addplot (\x,\x^2 + 4);
- \addplot (\x,-5*\x^3 - \x^2);
-\end{axis}
-\end{tikzpicture}
+ The \marg{coordinate list} is a |\foreach| expression, that means it can contain a simple list of coordinates (comma--separated) but also complex |...| expressions like\footnote{Unfortunately, the |...| is somewhat restrictive when it comes to extended accuracy. So, if you have particularly small or large numbers (or a small distance), you have to provide a comma--separated list (or use the \texttt{domain} key).}
+\begin{codeexample}[code only]
+\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}}
\end{codeexample}
-The number of points and the sampled range is configured as for |plot function|, that means using |samples| and |domain|.
-Please note that \PGF's math parser uses degrees for trigonometric functions:
+ The same special treatment of |/tikz/samples at| and |/pgfplots/samples at| as for the |domain| key applies here. See above for details.
+
+ \paragraph{Attention:} |samples at| overrides |domain|, even if |domain| has been set \emph{after} |samples at|! Use |samples at={}| to clear \marg{coordinate list} and re-activate |domain|.
+\end{pgfplotskey}
+
+\subsubsection{Computing Coordinates with Mathematical Expressions (gnuplot)}
+
+\begin{addplotoperation}[]{gnuplot}{\marg{gnuplot code}}
+In contrast to |plot 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 |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot gnuplot| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with |plot gnuplot| (it configures high precision output). You should use different ids to avoid conflicts in such a case.}).
+
+The differences between |plot expression| and |plot gnuplot| are:
+\begin{itemize}
+ \item |plot expression| does not require any external programs and requires no additional command line options.
+ \item |plot expression| does not produce a lot of temporary files.
+ \item |plot gnuplot| uses radians for trigonometric functions while |plot expression| has degrees.
+ \item |plot gnuplot| is faster.
+ \item |plot gnuplot| has a larger mathematical library.
+ \item |plot gnuplot| has a higher accuracy. However, starting with version 1.2, this is no longer a great problem. The new floating point unit for \TeX\ provides reasonable accuracy and the same data range as |gnuplot|.
+\end{itemize}
+
+Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example
+\begin{codeexample}[code only]
+pdflatex -shell-escape filename.tex.
+\end{codeexample}
+Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two slashes -- that all depends on your \TeX\ distribution.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
- \addplot plot[domain=0:360]
- (\x,{sin(\x)});
+\addplot plot[id=sin]
+ gnuplot{sin(x)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
-the braces are necessary to delimit the $y$ argument here. If you want to use radians, use
+
\begin{codeexample}[]
\begin{tikzpicture}
-\begin{axis}
- \addplot plot[domain=-3.14159:3.14159]
- (\x,{sin(\x r)});
-\end{axis}
+\begin{semilogyaxis}
+\addplot plot[id=exp,domain=0:10]
+ gnuplot{exp(x)};
+\end{semilogyaxis}
\end{tikzpicture}
\end{codeexample}
-to convert the radians to degrees. The \Tikz\ plot expression parser also accepts some more options like |samples at=|\marg{coordinate list} or |variable=\t| which are described in the \Tikz\ manual.
+
+The \meta{style options} determine the appearance of the plotted function; these parameters also affect the legend. The \meta{behavior options} are specific to the gnuplot interface. These options are described in all detail in \cite[section~18.6]{tikz}. A short summary is shown below.
+
+Please note that |plot gnuplot| does not allow per point meta data.
+
+Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction.
\end{addplotoperation}
+\begin{addplotoperation}[]{function}{\marg{gnuplot code}}
+ Use
+
+ |\addplot function |\marg{gnuplot code}|;|
+
+ as alias for
+
+ |\addplot gnuplot |\marg{gnuplot code}|;|
+\end{addplotoperation}
+
+\begin{key}{/tikz/id=\marg{unique string identifier}}
+ A unique identifier for the current plot. It is used to generate temporary filenames for |gnuplot| output.
+\end{key}
+
+\begin{key}{/tikz/prefix=\marg{file name prefix}}
+ A common path prefix for temporary filenames (see \cite[section~18.6]{tikz} for details).
+\end{key}
+
+\begin{key}{/tikz/raw gnuplot}
+ Disables the use of |samples| and |domain|.
+\end{key}
+
+
\begin{command}{\addplot+\oarg{style options} \textcolor{gray}{\dots};}
Does the same like |\addplot[|\meta{style options}|] ...;| except that \meta{style options} is \emph{appended} to the arguments which would have been taken for |\addplot ...| (the element of the default list).
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
-\addplot (\x,{sin(\x r)});
+\addplot {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
\begin{axis}
-\addplot+[only marks] (\x,{sin(\x r)});
+\addplot+[only marks] {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -451,9 +607,9 @@ It can be used to draw any \Tikz-graphics at axis coordinates. It is used like
(553983, 3.053e-05)
};
- \node[coordinate,pin=above:Bad!]
+ \node[coordinate,pin=above:{Bad!}]
at (axis cs:5503,2.027e-03) {};
- \node[coordinate,pin=left:Good!]
+ \node[coordinate,pin=left:{Good!}]
at (axis cs:187903,9.063e-05) {};
\end{loglogaxis}
\end{tikzpicture}
@@ -554,16 +710,16 @@ The legend appearance can be configured with the help of several styles and opti
\begin{tikzpicture}[baseline]
\begin{axis}
\addplot+[only marks]
- plot[samples=15,
+ expression[samples=15,
error bars/y dir=both,
error bars/y fixed=2.5]
- (\x,3*\x+2.5*rand);
+ {3*x+2.5*rand};
\label{pgfplots:label1}
- \addplot+[mark=none] (\x,3*\x);
+ \addplot+[mark=none] {3*x};
\label{pgfplots:label2}
- \addplot (\x,{4*cos(\x r)});
+ \addplot {4*cos(deg(x))};
\label{pgfplots:label3}
\end{axis}
\end{tikzpicture}
@@ -598,10 +754,18 @@ Label2 = \ref{pgfplots:label2}
This will also work together with |hyperref| links and |\pageref|.
\end{command}
+\begin{key}{/pgfplots/refstyle=\marg{label name}}
+ Can be used to set the \emph{styles} of a labeled, single plot. This allows to write
+\begin{codeexample}[code only]
+\addplot[/pgfplots/refstyle={pgfplots:label2}]
+\end{codeexample}
+ \noindent somewhere. Please note that it may be easier to define a style with |.style|.
+\end{key}
+
\begin{stylekey}{/pgfplots/every crossref picture}
A style which will be used by the cross-referencing feature for plots. The default is
\begin{codeexample}[code only]
-\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em}
+\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em}}
\end{codeexample}
\end{stylekey}
@@ -615,7 +779,7 @@ Label2 = \ref{pgfplots:label2}
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^2+2) \closedcycle;
+ \addplot {x^2+2} \closedcycle;
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -623,7 +787,7 @@ Label2 = \ref{pgfplots:label2}
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
- \addplot+[fill] (\x,\x^2+2) \closedcycle;
+ \addplot+[fill] {x^2+2} \closedcycle;
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -679,9 +843,6 @@ The number is printed using the current number printing options, see section~\re
\begin{command}{\pgfplotstabletypeset\marg{\textbackslash macro}}
Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle.
\end{command}
-\begin{command}{\pgfplotstabletypesetfile\marg{file}}
- Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle.
-\end{command}
\section{Option Reference}
There are several required and even more optional arguments to modify axes. They are used like
@@ -700,6 +861,45 @@ The overall appeareance can be changed with
\noindent
for example. There are several other styles predefined to modify the appearance, see section~\ref{sec:styles}.
+\begin{command}{\pgfplotsset\marg{key-value-list}}
+ Defines or sets all options in \marg{key-value-list}.
+
+ It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path.
+
+ This command can be used to define default options for the complete document or a part of the document. For example,
+\begin{codeexample}[code only]
+\pgfplotsset{
+ cycle list={%
+ {red, mark=*}, {blue,mark=*},
+ {red, mark=x}, {blue,mark=x},
+ {red, mark=square*}, {blue,mark=square*},
+ {red, mark=triangle*}, {blue,mark=triangle*},
+ {red, mark=diamond*}, {blue,mark=diamond*},
+ {red, mark=pentagon*}, {blue,mark=pentagon*}
+ },
+ legend style={
+ at={(0.5,-0.2)},
+ anchor=north,
+ legend columns=2,
+ cells={anchor=west},
+ font=\footnotesize,
+ rounded corners=2pt,
+ },
+ xlabel=$x$,ylabel=$f(x)$
+}
+\end{codeexample}
+ can be used to set document--wise styles for line specifications, the legend's style and axis labels.
+
+ You can also define new styles (collections of key--value--pairs) with |.style| and |.append style|.
+\begin{codeexample}[code only]
+\pgfplotsset{
+ My Style 1/.style={xlabel=$x$, legend entries={1,2,3} },
+ My Style 2/.style={xlabel=$X$, legend entries={4,5,6} }
+\end{codeexample}
+ The |.style| and |.append style| key handlers are described in section~\ref{sec:styles} in more detail.
+\end{command}
+
+
\subsection{Pgfplots Options and \Tikz\ Options}
This section is more or less technical and can be skipped unless one really wants to know more about this topic.
@@ -811,15 +1011,15 @@ coordinates
\begin{plottype}{jump mark left}
A variant of `|const plot mark left|' which does not draw vertical lines.
\begin{codeexample}[]
-\begin{tikzpicture}[samples=8]
-\begin{axis}
+\begin{tikzpicture}
+\begin{axis}[samples=8]
\addplot+[jump mark left]
- plot[id=parablex,domain=-5:0]
- function{4*x**2 - 5};
+ expression[domain=-5:0]
+ {4*x^2 - 5};
\addplot+[jump mark right]
- plot[id=cubic,domain=-5:0]
- function{0.7*x**3 + 50};
+ expression[domain=-5:0]
+ {0.7*x^3 + 50};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -848,6 +1048,7 @@ Bar plots place horizontal or vertical bars at coordinates. Multiple bar plots i
Bars are centered at plot coordinates with width |bar width|. Using bar plots usually means more than just a different way of how to connect coordinates, for example to draw ticks outside of the axis, change the legend's appearance or introduce shifts if multiple |\addplot| commands appear.
There is a preconfigured style for |xbar| which is installed automatically if you provide |xbar| as argument to the axis environment which provides this functionality.
+% \usetikzlibrary{patterns}
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[xbar,enlargelimits=0.15]
@@ -871,7 +1072,7 @@ Here |xbar| yields |/pgfplots/xbar| because it is an argument to the axis, not t
\begin{stylekey}{/pgfplots/xbar=\marg{shift for multiple plots} (default 2pt)}
This style sets |/tikz/xbar| \emph{and} some commonly used options concerning horizontal bars for the complete axis. This is automatically done if you provide |xbar| as argument to an axis argument, see above.
-The |xbar| style defines shifts if multiple plots are placed into one axis. If draws bars adjacent to each other, separated by \marg{shift for multiple plots}. Furthermore, it sets the style |bar cycle list| and sets tick and legend appearance options.
+The |xbar| style defines shifts if multiple plots are placed into one axis. It draws bars adjacent to each other, separated by \marg{shift for multiple plots}. Furthermore, it sets the style |bar cycle list| and sets tick and legend appearance options.
The style is defined as follows.
\begin{codeexample}[code only]
@@ -882,7 +1083,10 @@ The style is defined as follows.
{\draw[##1,bar width=3pt,yshift=-0.2em,bar shift=0pt]
plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};},
/pgf/bar shift={%
+ % total width = n*w + (n-1)*skip
+ % -> subtract half for centering
-0.5*(\numplots*\pgfplotbarwidth + (\numplots-1)*#1) +
+ % the '0.5*w' is for centering
(.5+\plotnum)*\pgfplotbarwidth + \plotnum*#1},
/tikz/xbar},
\end{codeexample}
@@ -1044,7 +1248,7 @@ Here |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not t
\end{pgfplotsxykey}
\subsubsection{Comb Plots}
-Comb plots are very similar to bar plots except that they emplot single horizontal/vertical lines instead of rectangles.
+Comb plots are very similar to bar plots except that they employ single horizontal/vertical lines instead of rectangles.
\begin{plottype}{xcomb}
\begin{codeexample}[]
@@ -1071,7 +1275,7 @@ Comb plots are very similar to bar plots except that they emplot single horizont
\subsubsection{Stacked Plots}
\begin{pgfplotskey}{stack plots=\mchoice{x,y,false} (initially false)}
- Allows stacking of plots in either $x$ or $y$ direction. Stacking means add either $x$- or $y$ coordinates of successive |\addplot| commands on top of each other.
+ Allows stacking of plots in either $x$ or $y$ direction. Stacking means to add either $x$- or $y$ coordinates of successive |\addplot| commands on top of each other.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[stack plots=y]
@@ -1137,10 +1341,11 @@ Comb plots are very similar to bar plots except that they emplot single horizont
\end{axis}
\end{tikzpicture}
\end{codeexample}
+The current implementation for |stack plots| does \emph{not} interpolate missing coordinates. That means stacking will fail if the plots have different grids.
\end{pgfplotskey}
\begin{pgfplotskey}{stack dir=\mchoice{plus,minus} (initially plus)}
- Configures the direction of |stack plots|. The value |plus| will adds coordinates of successive plots while |minus| subtracts them.
+ Configures the direction of |stack plots|. The value |plus| will add coordinates of successive plots while |minus| subtracts them.
\end{pgfplotskey}
\begin{pgfplotskey}{reverse stacked plots=\mchoice{true,false} (initially true, default true)}
@@ -1159,10 +1364,10 @@ Comb plots are very similar to bar plots except that they emplot single horizont
\end{stylekey}
\begin{stylekey}{/pgfplots/xbar interval stacked=\mchoice{plus,minus} (default plus)}
- A sttyle similar to |/pgfplots/xbar stacked| for the interval based bar plot variant.
+ A style similar to |/pgfplots/xbar stacked| for the interval based bar plot variant.
\end{stylekey}
\begin{stylekey}{/pgfplots/ybar interval stacked=\mchoice{plus,minus} (default plus)}
- A sttyle similar to |/pgfplots/ybar stacked| for the interval based bar plot variant.
+ A style similar to |/pgfplots/ybar stacked| for the interval based bar plot variant.
\end{stylekey}
\subsubsection{Area Plots}
@@ -1187,7 +1392,7 @@ Area plots are a combination of |\closedcycle| and |stack plots|. They can be co
\end{tikzpicture}
\end{codeexample}
\noindent
-Area plots may need modified legends, for example using the |area legend| key. Furthermore, one may want to consider the |axis on top| key such that filled areas to not overlap ticks and grid lines.
+Area plots may need modified legends, for example using the |area legend| key. Furthermore, one may want to consider the |axis on top| key such that filled areas do not overlap ticks and grid lines.
\begin{stylekey}{/pgfplots/area style}
A style which sets
@@ -1311,6 +1516,223 @@ Area plots may need modified legends, for example using the |area legend| key. F
\end{tikzpicture}
\end{codeexample}
+\subsubsection{Scatter Plots}
+\label{pgfplots:scatter}
+For scatter plots, the marker appearance changes for each data point. An example is that marker colors depend on the magnitude of function values $f(x)$.
+
+Scatter plots require ``source'' coordinates. These source coordinates can be the $y$ coordinate, or explicitly provided additional values.
+
+\begin{plottype}{scatter}
+ Enables marker appearance modifications. The default implementation acquires ``source coordinates'' for every data point (see |scatter src| below) and maps them linearly into the current color map. The resulting color is used as draw and fill color of the marker.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}
+ \addplot+[scatter,only marks]
+ expression[samples=50,scatter src=y]
+ {x-x^2};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ The key |scatter| is simply a boolean variable which enables marker modifications. It applies only to markers and it can be combined with any other plot type.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}
+ \addplot+[scatter]
+ expression[samples=50,scatter src=y]
+ {x^3};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\end{plottype}
+
+Scatter plots can be configured using a set of options. One of them is mandatory, the rest allows fine grained control over marker appearance options.
+
+\label{pgfplots:scatter:src}
+\begin{pgfplotskey}{scatter src=\mchoice{none,x,y,z,explicit,explicit symbolic} (initially none)}
+ This key is necessary for any scatter plot. It needs to be provided as \marg{behavior option} for |\addplot| to configure the value used to determine marker appearances.
+
+ The choices |x|, |y| and |z| will use either the $x$, $y$ or $z$ coordinates to determine marker options\footnote{The coordinates are used after any coordinate filters, logarithms or stacked-plot computations have been applied.}. The choice |explicit| expects the scatter source data as additional coordinate from the coordinate input streams (see section~\ref{pgfplots:providing:input} for how to provide input meta data). They will be treated as numerical data. Finally, |explicit symbolic| also expects scatter source data as additional meta information for each input coordinate, but it treats them as strings, not as numerical data. Consequently, no arithmetics is performed. It is task of the scatter plot style to do sometthing with it. See, for example, the |scatter/classes| style below.
+
+ Please note that |scatter src|$\neq$|none| results in computational work even if |scatter=false|.
+\end{pgfplotskey}
+
+\begin{stylekey}{/pgfplots/scatter/use mapped color=\marg{options for each marker} (initially draw=mapped color!80!black,fill=mapped color)}
+ This style is installed by default. When active, it recomputes the color |mapped color| for every processed point coordinate by transforming the |scatter src| coordinates into the current colormap linearly. Then, it evaluates the options provided as \marg{options for each marker} which are expected to depend on |mapped color|.
+
+ The user interface for colormaps is described in section~\ref{pgfplots:colormap}.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[title=Default arguments]
+\addplot+[scatter]
+ expression[scatter src=y]
+ {2*x+3};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ title=Black fill color and varying draw color,
+ scatter/use mapped color=
+ {draw=mapped color,fill=black}]
+\addplot+[scatter]
+ expression[scatter src=y]
+ {2*x+3};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ title=Black draw color and varying fill color,
+ scatter/use mapped color=
+ {draw=black,fill=mapped color}]
+\addplot+[scatter]
+ expression[scatter src=y]
+ {2*x+3};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ This key is actually a style which redefines |@pre marker code| and |@post marker code| (see below).
+\end{stylekey}
+
+\label{pgfplots:scatterclasses}
+\begin{stylekey}{/pgfplots/scatter/classes=\marg{styles for each classname}}
+ A scatter plot style which visualizes points using several classes. The style assumes that every point coordinate has a class label attached, that means the choice |scatter src=explicit symbolic| is assumed\footnote{If \texttt{scatter src} is not \texttt{explicit symbolic}, we expect a numeric argument which is rounded to the nearest integer. The resulting integer is used a class label. If that fails, the numeric argument is truncated to the nearest integer. If that fails as well, the point has no label.}. A class label can be a number, but it can also be a symbolic constant. Given class labels for every point, \marg{styles for each classname} contains a comma-separated list which associates appearance options to each class label.
+
+ If you need different |scatter/classes| arguments per plot, they must be given as \marg{behavior option}, not as style option.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[scatter/classes={
+ a={mark=square*,blue},%
+ b={mark=triangle*,red},%
+ c={mark=o,draw=black,fill=black}}]
+
+ \addplot+[scatter,only marks]
+ plot[scatter src=explicit symbolic]
+ coordinates {
+ (0.1,0.15) [a]
+ (0.45,0.27) [c]
+ (0.02,0.17) [a]
+ (0.06,0.1) [a]
+ (0.9,0.5) [b]
+ (0.5,0.3) [c]
+ (0.85,0.52) [b]
+ (0.12,0.05) [a]
+ (0.73,0.45) [b]
+ (0.53,0.25) [c]
+ (0.76,0.5) [b]
+ (0.55,0.32) [c]
+ };
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+In this example, the coordinate |(0.1,0.15)| has the associated label `|a|' while |(0.45,0.27)| has the label `|c|' (see section~\ref{sec:addplot} for details about specifying point meta data). Now, The argument to |scatter/classes| contains styles for every label -- for label `|a|', square markers will be drawn in color blue.
+
+In general, the format of \marg{styles for each classname} is a comma separated list of \meta{label}|=|\marg{style options}.
+
+\paragraph{Attention:} The keys |every mark| and |mark options| have \emph{no effect} when used inside of \marg{styles for each classname}! So, instead of assigning |mark options|, you can simply provide the options directly. They apply only to markers anyway.
+\end{stylekey}
+
+\begin{pgfplotsxycodekeylist}{
+ scatter/@pre marker code,
+ scatter/@post marker code}
+ These two keys constitute the public low-level interface which determines the marker appearance depending on the scatter source coordinates.
+
+ Redefining them allows fine grained control even over marker types, linestyles and colors.
+
+ The scatter plot algorithm works as follows:
+\begin{enumerate}
+\item The scatter source coordinates form a data stream whose data limits are computed additionally to the axis limits. This step is skipped for |symbolic| meta data.
+\item Before any markers are drawn, a linear coordinate transformation from these data limits to the interval $[0.0,1000.0]$ is initialised.
+\item Every scatter source coordinate\footnote{During the evaluation, the public macros \texttt{\textbackslash pgfplotspointmeta} and \texttt{\textbackslash pgfplotspointmetarange} indicate the source coordinate and the source coordinate range in the format $a:b$ (for log--axis, they are given in fixed point representation and for linear axes in floating point).} will be transformed linearly and the result is available as macro |\pgfplotspointmetatransformed| $ \in [0.0,1000.0]$.
+
+The decision is thus based on per thousands of the data range. The transformation is skipped for |symbolic| meta data (and the meta data is simply contained in the mentioned macro).
+\item The code of |scatter/@pre marker code| is evaluated (without arguments).
+\item The standard code which draws markers is evaluated.
+\item The code of |scatter/@post marker code| is evaluated (without arguments).
+\end{enumerate}
+ The idea is to generate a set of appearance keys which depends on |\pgfplotspointmetatransformed|. Then, a call to |\scope|\oarg{generated keys} as |@pre| code and the associated |\endscope| as |@post| code will draw markers individually using \oarg{generated keys}.
+
+A technical example is shown below. It demonstrates how to write user defined routines, in this case a three--class system\footnote{Please note that you don't need to copy this particular example: the multiple--class example is also available as predefined style \texttt{scatter/classes}.}.
+\begin{codeexample}[]
+\begin{tikzpicture}
+% Low-Level scatter plot interface Example:
+% use three different marker classes
+% 0% - 30% : first class
+% 30% - 60% : second class
+% 60% - 100% : third class
+\begin{axis}[
+scatter/@pre marker code/.code={%
+ \ifdim\pgfplotspointmetatransformed pt<300pt
+ \def\markopts{mark=square*,fill=blue}%
+ \else
+ \ifdim\pgfplotspointmetatransformed pt<600pt
+ \def\markopts{mark=triangle*,fill=orange}%
+ \else
+ \def\markopts{mark=pentagon*,fill=red}%
+ \fi
+ \fi
+ \expandafter\scope\expandafter[\markopts]
+},%
+scatter/@post marker code/.code={%
+ \endscope
+}]
+
+\addplot+[scatter]
+ expression[scatter src=y,samples=40]
+ {sin(deg(x))};
+
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+Please note that |\ifdim| compares \TeX\ lengths, so the example employs the suffix |pt| for any number used in this context. That doesn't change the semantics.
+
+\end{pgfplotsxycodekeylist}
+
+\subsubsection{Interrupted Plots}
+\index{Interrupted Plots}%
+Sometimes it is desireable to draw parts of a single plot separately, without connection between the parts (discontinuities). There is limited support for such an application.
+\label{pgfplots:interrupt}
+\begin{pgfplotskey}{/pgfplots/forget plot=\marg{true,false} (initially false)}
+ This key tells \PGFPlots\ to add a plot without changing cycle list position and legends. This key is described in all detail on page~\pageref{pgfplots:forgetplot}.
+
+ However, it can be used to get the interesting effect of ``interrupted plot'', so it is also discussed here:
+\begin{codeexample}[width=4cm]
+\begin{tikzpicture}
+\begin{axis}[
+ width=10cm, height=210pt,
+ xmin=-4.7124, xmax=4.7124,
+ ymin=-10, ymax=10,
+ xtick={-4.7124,-1.5708,...,10},
+ xticklabels={$-\frac32 \pi$,$-\pi/2$,$\pi/2$,$\frac32 \pi$},
+ axis x line=center,axis y line=center,
+ no markers,
+ samples=100]
+
+% Use gnuplot as calculator here. The first two plots won't be counted:
+\addplot gnuplot[id=tan0,forget plot,domain=-1.5*pi+0.003:-0.5*pi-0.003] {tan(x)};
+\addplot gnuplot[id=tan1,forget plot,domain=-0.5*pi+0.003: 0.5*pi-0.003] {tan(x)};
+\addplot gnuplot[id=tan2, domain= 0.5*pi+0.003: 1.5*pi-0.003] {tan(x)};
+\legend{$\tan(x)$}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ The interesting part is in the |\addplot| commands. The |id| is specific to the gnuplot interface (and can be omitted). The |domain| option defines separate domains for every plot part. Due to the |forget plot| key, the |cycle list| position is not updated so all three plots use the same line specification. Furthermore, only the last command affects the legend (and advances the cycle list).
+
+ \paragraph{Remark:} The |forget plot| feature is \emph{not very sophisticated}. In particular, it has the following \textbf{restrictions}:
+ \begin{enumerate}
+ \item Besides the |cycle list| side--effect, no styles are communicated between successive plots.
+ \item It won't work together with |stack plots|.
+ \end{enumerate}
+\end{pgfplotskey}
+
\subsection{Markers and Linestyles}
\label{sec:markers}%
The following options of \Tikz\ are available to plots.
@@ -1395,7 +1817,9 @@ All these options have been drawn with the additional options
\end{axis}
\end{tikzpicture}
\end{codeexample}
+\end{key}
+\begin{stylekey}{/pgfplots/every axis plot post (initially {})}
The |every axis plot post| style can be used to overwrite parts (or all) of the drawing styles which are assigned for plots.
\begin{codeexample}[]
% Overwrite any cycle list:
@@ -1410,7 +1834,11 @@ The |every axis plot post| style can be used to overwrite parts (or all) of the
\end{axis}
\end{tikzpicture}
\end{codeexample}
-\end{key}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/no markers}
+ A style which appends |mark=none| to |every axis plot post|, which disables markers for every plot (even if the cycle list contains markers).
+\end{stylekey}
\begin{key}{/tikz/mark options=\marg{options}}
Resets |every mark| to \marg{options}.
@@ -1456,7 +1884,15 @@ The following line styles are predefined in \Tikz.
\begin{stylekey}{/tikz/loosely dashed}
\showit{style=loosely dashed}
\end{stylekey}
-You may need the option |mark options={solid}| to avoid dotted or dashed marker boundaries.
+\noindent since these styles apply to markers as well, you may want to consider using
+\begin{codeexample}[code only]
+\pgfplotsset{
+ every mark/.append style={solid}
+}
+\end{codeexample}
+\noindent in marker styles.
+
+Besides linestyles, \PGF\ also offers (a lot of) arrow heads. Please refer to~\cite{tikz} for details.
\endgroup
\subsubsection{Font Size and Line Width}
@@ -1467,7 +1903,7 @@ Often, one wants to change line width and font sizes for plots. This can be done
\end{key}
\begin{key}{/tikz/line width=\marg{dimension} (initially 0.4pt)}
- Sets the line width. Please note that line widths for tick lines and grid lines are predefined, so you may need to override the styles |every tick| and |every axis grid|.
+ Sets the line width. Please note that line widths for tick lines and grid lines are predefined, so it may be necessary to override the styles |every tick| and |every axis grid|.
The |line width| key is changed quite often in \Tikz. You should use
\begin{codeexample}[code only]
@@ -1477,7 +1913,7 @@ Often, one wants to change line width and font sizes for plots. This can be done
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={thick}}
\end{codeexample}
- to change the overall line width. To also adjust ticks and grid lines, you can use
+ to change the overall line width. To also adjust ticks and grid lines, one can use
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={
line width=1pt,
@@ -1509,6 +1945,7 @@ This example shows the same plots as on page~\pageref{page:plotcoords:src} (usin
xlabel=\textsc{Dof},
ylabel=$L_2$ Error
]
+ % see above for this macro:
\plotcoords
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{loglogaxis}
@@ -1525,6 +1962,7 @@ This example shows the same plots as on page~\pageref{page:plotcoords:src} (usin
xlabel=\textsc{Dof},
ylabel=$L_2$ Error
]
+ % see above for this macro:
\plotcoords
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{loglogaxis}
@@ -1566,18 +2004,18 @@ The package |xcolor| defines a set of predefined colors, namely
\begin{tikzpicture}
\begin{axis}[enlarge x limits=false]
\addplot[red]
- plot[samples=500] (\x,{sin(\x r)});
+ expression[samples=500] {sin(deg(x))};
\addplot[orange]
- plot[samples=7] (\x,{sin(\x r)});
+ expression[samples=7] {sin(deg(x))};
\addplot[teal,const plot]
- plot[samples=14] (\x,{sin(\x r)});
+ expression[samples=14] {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}
-Besides predefined colors, you can \emph{mix} two (or more) colors. For example, \showcolorandname{red!30!white} contains $30\%$ of \showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently, one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$ white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This mixing can be done with any color, \showcolorandname{red!50!green}, \showcolorandname{blue!50!yellow}.
+Besides predefined colors, it is possible to \emph{mix} two (or more) colors. For example, \showcolorandname{red!30!white} contains $30\%$ of \showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently, one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$ white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This mixing can be done with any color, \showcolorandname{red!50!green}, \showcolorandname{blue!50!yellow}.
A different type of color mixing is supported, which allows to take $100\%$ of \emph{each} component. For example, \showcolorandname{rgb,2:red,1;green,1} will add $1/2$ part \showcolorandname{red} and $1/2$ part \showcolorandname{green} and we reproduced the example from above. Using the denominator~$1$ instead of~$2$ leads to \showcolorandname{rgb,1:red,1;green,1} which uses $1$ part \showcolorandname{red} and $1$ part \showcolorandname{green}. Many programs allow to select pieces between $0,\dotsc,255$, so a denominator of $255$ is useful. Consequently, \showcolorandname{rgb,255:red,231;green,84;blue,121} uses $231/255$ red, $84/255$ green and $121/255$. This corresponds to the standard RGB color $(231,84,121)$. Other examples are \showcolorandname{rgb,255:red,32;green,127;blue,43}, \showcolorandname{rgb,255:red,178;green,127;blue,43}, \showcolorandname{rgb,255:red,169;green,178;blue,43}.
@@ -1597,6 +2035,36 @@ It is also possible to use RGB values, the HSV color model or the HTML color syn
\noindent creates the color with $208/255$ pieces red, $178/255$ pieces green and $43$ pieces blue, specified in standard HTML notation. Please refer to the |xcolor| manual~\cite{xcolor} for more details and color models.
}%
+\subsubsection{Color Maps}
+\label{pgfplots:colormap}
+\begin{pgfplotskey}{colormap name=\marg{color map name} (initially hot)}
+ Changes the current color map to the already defined map named \marg{color map name}. Available standard color maps are
+
+ \begin{tabular}{>{\ttfamily}ll}
+ hot & \pgfplotsshowcolormap{hot}\\
+ \end{tabular}
+
+ Colormaps can be used, for example, in scatter plots (see section~\ref{pgfplots:scatter}).
+
+ You can use |colormap| to create new color maps (see below).
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{colormap=\marg{name}\marg{color specification}}
+ Defines a new colormap named \marg{name} according to \marg{color specification} and activates it using |colormap name=|\marg{name}.
+
+ The syntax of \marg{color specification} is the same as those for \PGF\ shadings described in~\cite[VIII -- Shadings]{tikz}: it consists of a series of colors along with a length.
+\begin{codeexample}[code only]
+rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb(2cm)=(0,0,1); gray(3cm)=(0.3); color(4cm)=(green)
+\end{codeexample}
+\pgfplotsshowcolormapexample{rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb(2cm)=(0,0,1); gray(3cm)=(0.3); color(4cm)=(green)}
+
+\noindent The single colors are separated by semicolons `|;|'. The length describes how much of the bar is occupied by the interval. Each entry has the form \meta{color model}|(|\meta{length}|)=(|\meta{arguments}|)|. The line above means that the left end of the colormap shall have RGB components $1,0,0$, indicating $100\%$ red and $0\%$ green and blue. The next entity starts at |1cm| and describes a color with $100\%$ green. Finally, |gray| specifies a color with the same value for each, R G and B and |color| accesses predefined colors.
+
+The complete length of a colormap is irrelevant: it will be mapped linearly to an internal range anyway (for efficient interpolation). The only requirement is that the left end must be at |0|.
+
+\paragraph{Remark:} Currently, only equidistant \marg{color specification}s are supported (each interval must have the same length).
+\end{pgfplotskey}
+
\subsubsection{Options Controlling Linestyles}
\label{sec:cycle:list}%
@@ -1605,26 +2073,120 @@ Allows to specify a list of plot specifications which will be used for each \hbo
There are several possiblities to change it:
\begin{enumerate}
- \item Use one of the predefined lists,
+ \item Use one of the predefined lists\footnote{These lists were named \texttt{\textbackslash coloredplotspeclist} and \texttt{\textbackslash blackwhiteplotspeclist} which appeared to be unnecessarily long, so they have been renamed. The old names are still accepted, however.},
+ \begin{itemize}
+ \item |color| (from top to bottom)
\begin{codeexample}[]
\begin{tikzpicture}
-\begin{loglogaxis}[
- cycle list name=\coloredplotspeclist]
-\plotcoords
-\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
-\end{loglogaxis}
+\begin{axis}[
+ stack plots=y,stack dir=minus,
+ cycle list name=color]
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\end{axis}
\end{tikzpicture}
\end{codeexample}
-These examples employs the same coords as in the example on page~\pageref{page:plotcoords:src}.
+
+ \item |exotic| (from top to bottom)
\begin{codeexample}[]
\begin{tikzpicture}
-\begin{loglogaxis}[
- cycle list name=\blackwhiteplotspeclist]
-\plotcoords
-\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
-\end{loglogaxis}
+\begin{axis}[
+ stack plots=y,stack dir=minus,
+ cycle list name=exotic]
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\end{axis}
\end{tikzpicture}
\end{codeexample}
+
+ \item |black white| (from top to bottom)
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ stack plots=y,stack dir=minus,
+ cycle list name=black white]
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\addplot coordinates {(0,1) (0.5,1) (1,1)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ \end{itemize}
+
+These predefined cycle lists habe been created with
+\begin{codeexample}[code only]
+\pgfplotscreateplotcyclelist{color}{%
+ blue,every mark/.append style={fill=blue!80!black},mark=*\\%
+ red,every mark/.append style={fill=red!80!black},mark=square*\\%
+ brown!60!black,every mark/.append style={fill=brown!80!black},mark=otimes*\\%
+ black,mark=star\\%
+ blue,every mark/.append style={fill=blue!80!black},mark=diamond*\\%
+ red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\%
+ brown!60!black,densely dashed,every mark/.append style={
+ solid,fill=brown!80!black},mark=square*\\%
+ black,densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\%
+ blue,densely dashed,mark=star,every mark/.append style=solid\\%
+ red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\%
+}
+\pgfplotscreateplotcyclelist{black white}{%
+ every mark/.append style={fill=gray},mark=*\\%
+ every mark/.append style={fill=gray},mark=square*\\%
+ every mark/.append style={fill=gray},mark=otimes*\\%
+ mark=star\\%
+ every mark/.append style={fill=gray},mark=diamond*\\%
+ densely dashed,every mark/.append style={solid,fill=gray},mark=*\\%
+ densely dashed,every mark/.append style={solid,fill=gray},mark=square*\\%
+ densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\%
+ densely dashed,every mark/.append style={solid},mark=star\\%
+ densely dashed,every mark/.append style={solid,fill=gray},mark=diamond*\\%
+}
+\pgfplotscreateplotcyclelist{exotic}{%
+ teal,every mark/.append style={fill=teal!80!black},mark=*\\%
+ orange,every mark/.append style={fill=orange!80!black},mark=square*\\%
+ cyan!60!black,every mark/.append style={fill=cyan!80!black},mark=otimes*\\%
+ red!70!white,mark=star\\%
+ lime!80!black,every mark/.append style={fill=lime},mark=diamond*\\%
+ red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\%
+ yellow!60!black,densely dashed,
+ every mark/.append style={solid,fill=yellow!80!black},mark=square*\\%
+ black,every mark/.append style={solid,fill=gray},mark=otimes*\\%
+ blue,densely dashed,mark=star,every mark/.append style=solid\\%
+ red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\%
+}
+\end{codeexample}
+
\item Provide the list explicitly,
\begin{codeexample}[]
\begin{tikzpicture}
@@ -1645,7 +2207,7 @@ These examples employs the same coords as in the example on page~\pageref{page:p
(This example list requires |\usetikzlibrary{plotmarks}|).
\item Define macro names and use them with `|cycle list name|':
\begin{codeexample}[code only]
-\pgfcreateplotcyclelist{\mylist}{%
+\pgfplotscreateplotcyclelist{mylist}{%
{blue,mark=*},
{red,mark=square},
{dashed,mark=o},
@@ -1653,7 +2215,7 @@ These examples employs the same coords as in the example on page~\pageref{page:p
{brown!60!black,mark options={fill=brown!40},mark=otimes*}}
}
...
-\begin{axis}[cycle list name=\mylist]
+\begin{axis}[cycle list name=mylist]
...
\end{axis}
\end{codeexample}
@@ -1673,21 +2235,21 @@ These examples employs the same coords as in the example on page~\pageref{page:p
...
\end{axis}
\end{codeexample}
-In this case, the \emph{last} entry also needs a terminating `|\\|', but you can omit braces around the single entries.
+In this case, the \emph{last} entry also needs a terminating `|\\|', but one can omit braces around the single entries.
\end{pgfplotskeylist}
\subsection{Axis Descriptions}
-Axis descriptions are labels for $x$ and $y$ axis and titles. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. Their placement is always relative to the axis rectangle, where $(0,0)$ refers to the lower left corner and $(1,1)$ refers to the upper right one.
+Axis descriptions are labels for $x$ and $y$ axis and titles. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. Their placement is always \emph{relative to the axis rectangle}, where $(0,0)$ refers to the lower left corner and $(1,1)$ refers to the upper right one.
Furthermore, axis descriptions can be placed using the predefined node |current axis|. At the time when axis descriptions are drawn, all anchors which refer to the axis origin (that means the ``real'' point $(0,0)$) or any of the axis corners can be references using |current axis.|\meta{anchor name}. Please see section~\ref{pgfplots:sec:align}, Alignment, for further details.
\subsubsection{Labels}
\begin{pgfplotsxykey}{\x label=\marg{text}}
-The options |xlabel| and |ylabel| change axis labels to \marg{text} which is any \TeX\ text. Use ``|xlabel={, = characters}|'' if you need to include `|=|' or `|,|' literally.
+The options |xlabel| and |ylabel| change axis labels to \marg{text} which is any \TeX\ text. Use ``|xlabel={, = characters}|'' if characters like `|=|' or `|,|' need to be included literally.
Labels are \Tikz-Nodes which are placed with
\begin{codeexample}[code only]
@@ -1712,7 +2274,7 @@ The default styles are
xshift=-35pt,
rotate=90}}
\end{codeexample}
-Whenever possible, you should use |.append style| instead of overwriting the default styles to ensure compatibility with future versions.
+Whenever possible, consider using |.append style| instead of overwriting the default styles to ensure compatibility with future versions.
\begin{codeexample}[code only]
\pgfplotsset{every axis label/.append style={...}}
\pgfplotsset{every axis x label/.append style={...}}
@@ -1789,7 +2351,7 @@ As all other axis descriptions, the code can use $(0,0)$ to access the lower lef
}}}
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -1801,12 +2363,12 @@ As all other axis descriptions, the code can use $(0,0)$ to access the lower lef
Legends can be generated in two ways: the first is to use |\addlegendentry| or |\legend| inside of an axis. This method has been presented in section~\ref{pgfplots:sec:legendcmds}, Legend Commands. The other method is to use a key.
\begin{pgfplotskey}{legend entries=\marg{comma separated list}}
- This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|.
+ This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|. Again, the positioning is relative to the axis rectangle (unless units like |cm| or |pt| are specified explicitly).
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend entries={$x$,$x^2$}]
- \addplot (\x,\x);
- \addplot (\x,\x^2);
+ \addplot {x};
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -1815,12 +2377,13 @@ Legends can be generated in two ways: the first is to use |\addlegendentry| or |
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend entries={$x$,$x^2$}]
- \addplot (\x,\x);
- \addplot (\x,\x^2);
+ \addplot {x};
+ \addplot {x^2};
\legend{$a$,$b$}% overrides the option
\end{axis}
\end{tikzpicture}
\end{codeexample}
+ Please be careful with whitespaces in \marg{comma separated list}: they will contribute to legend entries. Consider using `|%|' at the end of each line in multiline arguments (the end of line character is also a whitespace in \TeX).
\end{pgfplotskey}
{%
@@ -1840,7 +2403,7 @@ will draw it at the lower left corner of the axis while
\end{codeexample}
means the upper right corner. The `|anchor|' option determines which point \emph{of the legend} will be placed at $(0,0)$ or $(1,1)$.
-The legend is a \Tikz-matrix, so you can use any \Tikz\ option which affects
+The legend is a \Tikz-matrix, so one can use any \Tikz\ option which affects
nodes and matrizes (see~\cite[section 13~and~14]{tikz}). The matrix is created by something like
\begin{codeexample}[code only]
\matrix[style=every axis legend] {
@@ -1879,7 +2442,7 @@ Use |legend columns=|\marg{number} to configure the number of horizontal legend
\end{tikzpicture}
\end{codeexample}
\noindent
-Instead of the |.append style|, you can also use |legend style| as in the following example. It has the same effect.
+Instead of the |.append style|, it is possible to use |legend style| as in the following example. It has the same effect.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -1914,6 +2477,8 @@ Whenever possible, consider using |.append style| to keep the default styles act
\end{codeexample}
\end{stylekey}
+\pgfplotsshortstylekey legend style=every axis legend\pgfeov
+
}
\begin{pgfplotskey}{legend columns=\marg{number} (default 1)}
@@ -1953,6 +2518,7 @@ The default is
\end{codeexample}
\begin{codeexample}[]
+% \usetikzlibrary{patterns}
\begin{tikzpicture}
\begin{axis}[area legend,
axis x line=bottom,
@@ -1963,13 +2529,13 @@ The default is
axis on top,xmin=0]
\addplot[pattern=crosshatch dots,
pattern color=blue,draw=blue]
-plot[samples=500]
- (\x,{sqrt(\x)}) \closedcycle;
+expression[samples=500]
+ {sqrt(x)} \closedcycle;
\addplot[pattern=crosshatch,
pattern color=blue!30!white,
draw=blue!30!white]
- (\x,\x^2) \closedcycle;
+expression {x^2} \closedcycle;
\addplot[red] coordinates {(0,0) (1,1)};
\legend{$\sqrt x$,$x^2$,$x$}
@@ -2015,8 +2581,8 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas
xlabel=$x$,ylabel=$\sin x$]
\addplot[blue,mark=none]
- plot[id=sinneg,domain=-10:0,samples=40]
- function{sin(x)};
+ expression[domain=-10:0,samples=40]
+ {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2030,8 +2596,8 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas
xlabel=$x$,ylabel=$\sin x$
]
\addplot[blue,mark=none]
- plot[id=sinneg,domain=-10:0,samples=40]
- function{sin(x)};
+ expression[domain=-10:0,samples=40]
+ {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2044,8 +2610,8 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas
xlabel=$x$,ylabel=$\sqrt{|x|}$
]
\addplot[blue,mark=none]
- plot[id=sqrtabsx,domain=-4:4,samples=501]
- function{sqrt(abs(x))};
+ expression[domain=-4:4,samples=501]
+ {sqrt(abs(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2058,9 +2624,9 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas
axis x line=middle,
xlabel=$x$,ylabel=$\sin x$
]
- \addplot[blue,mark=none]
- plot[domain=-5:5,samples=40]
- (\x,{sin(\x r)});
+ \addplot[smooth,blue,mark=none]
+ [domain=-5:5,samples=40]
+ {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2073,9 +2639,9 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas
axis x line=middle,
xlabel=$x$,ylabel=$\sin x$
]
- \addplot[blue,mark=none]
- plot[domain=-5:5,samples=40]
- (\x,{sin(\x r)});
+ \addplot[smooth,blue,mark=none]
+ [domain=-5:5,samples=40]
+ {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2099,7 +2665,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea
{|->>},
xlabel=$x$,ylabel=$y^3$
]
-\addplot[blue] plot[domain=-3:5] (\x,\x^3);
+\addplot[blue] expression[domain=-3:5] {x^3};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2119,7 +2685,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea
\addplot[blue] plot[id=DoG,
samples=100,
domain=-15:15]
- function{1.3*exp(-x**2/10) - exp(-x**2/20)};
+ gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2130,7 +2696,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea
Both cases have their advantages and disadvantages, I fear there is no reasonable default (suggestions are welcome).
- The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, you will see unsatisfactory edges.
+ The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, unsatisfactory edges occur.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
@@ -2140,10 +2706,14 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea
every outer y axis line/.append style=
{-stealth,green!30!black},
]
-\addplot[blue] plot[id=DoG,
+\addplot[blue]
+ expression[
samples=100,
domain=-15:15]
- function{1.3*exp(-x**2/10) - exp(-x**2/20)};
+ {1.3*exp(0-x^2/10) - exp(0-x^2/20)};
+ % Unfortunately, there is a bug in PGF 2.00
+ % something like exp(-10^2)
+ % must be written as exp(0-10^2) :-(
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2161,7 +2731,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea
\addplot[blue] plot[id=DoG,
samples=100,
domain=-15:15]
- function{1.3*exp(-x**2/10) - exp(-x**2/20)};
+ gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2215,7 +2785,7 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam
axis y line=left,
xlabel=$x$,
ylabel=First ordinate]
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\begin{axis}[
@@ -2224,11 +2794,11 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam
axis y line=right,
axis x line=none,
ylabel=Second ordinate]
- \addplot[red] (\x,3*\x);
+ \addplot[red] {3*x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
-\noindent The basic idea is to draw two axis ``on top'' of each other -- one, which contains the $x$ axis and the left $y$ axis, and one which has \emph{only} the right $y$ axis. This requires attention in the following possibly non-obvious aspects:
+\noindent The basic idea is to draw two axis ``on top'' of each other -- one, which contains the $x$ axis and the left $y$ axis, and one which has \emph{only} the right $y$ axis. Since \PGFPlots\ does not really know what it's doing here, user attention in the following possibly non-obvious aspects is required:
\begin{enumerate}
\item Scaling. You should set |scale only axis| because this forces equal dimensions for both axis, without respecting any labels.
\item Same $x$ limits. You should set those limits explicitly.
@@ -2244,7 +2814,7 @@ It is also possible to use only the axis, without any plots:
axis y line=left,
xlabel=$x$,
ylabel=Absolute]
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\begin{axis}[
@@ -2300,13 +2870,40 @@ The description applies |axis y discontinuity| as well, with interchanged meanin
ymin=95, enlargelimits=false
]
\addplot[blue,mark=none]
- plot[id=square,domain=-4:4,samples=20]
- function{x*x+x+104};
+ expression[domain=-4:4,samples=20]
+ {x*x+x+104};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}
+A problem might occur with the placement of the ticks on the axis.
+This can be solved by specifying the minimum or maximum axis value for which a tick will be placed.
+
+\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord} (default axis limits), \x tickmax=\marg{coord} (default axis limits)}
+\label{key:xytickminmax}
+The options |xtickmin|, |xtickmax| and |ytickmin|, |ytickmax| allow to define the axis tick limits, i.e. the axis values before respectively after no ticks will be placed.
+Everything outside of the axis tick limits will be not drawn.
+Their default values are equal to the axis limits.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ axis x line=bottom,
+ axis y line=center,
+ tick align=outside,
+ axis y discontinuity=crunch,
+ xtickmax=3,
+ ytickmin=110,
+ ymin=95, enlargelimits=false
+]
+ \addplot[blue,mark=none]
+ plot[domain=-4:4,samples=20]
+ expression{x*x+x+104};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\end{pgfplotsxykeylist}
\begin{pgfplotsxykey}{hide \x\ axis=\mchoice{true,false} (initially false)}
Allows to hide either the $x$ or the $y$ axis. No outer rectangle, no tick marks and no labels will be drawn. Only titles and legends will be processed as usual.
@@ -2317,8 +2914,8 @@ Axis scaling and clipping will be done as if you did not use |hide x axis|.
\begin{axis}[
hide x axis,
hide y axis,
- title={$\cos(x)$}]
- \addplot (\x,{cos(\x)*\x^2});
+ title={$x^2\cos(x)$}]
+ \addplot {cos(x)*x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2328,8 +2925,8 @@ Axis scaling and clipping will be done as if you did not use |hide x axis|.
\begin{axis}[
hide x axis,
axis y line=left,
- title={$\cos(x)$}]
- \addplot (\x,{cos(\x)*\x^2});
+ title={$x^2\cos(x)$}]
+ \addplot {cos(x)*x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2386,17 +2983,53 @@ If |scale only axis| is enabled, label, tick and legend dimensions won't influen
If |scale only axis=false| (the default), \PGFPlots\ will try to produce the desired width \emph{including} labels, titles and ticks.
\end{pgfplotskey}
-\begin{pgfplotsxykey}{\x=\marg{dimen}}
-Sets the unit size for one $x$ (or $y$) coordinate to \marg{dimen}.
-
- Setting $x$ explicitly overrides the |width| option. Setting $y$ explicitly overrides the |height| option.
+\begin{pgfplotsxykeylist}{
+ \x=\marg{dimen},
+ \x={\{(\meta{x},\meta{y})\}}}
+Sets the unit vectors for $x$ (or $y$). Every logical plot coordinate $(x,y)$ is drawn at the position
+\[ x \cdot \begin{bmatrix} e_{xx} \\ e_{xy} \end{bmatrix} + y \cdot \begin{bmatrix} e_{yx} \\ e_{yy} \end{bmatrix}. \]
+The unit vectors $e_x$ and $e_y$ determine the paper position in the current (always two dimensional) image.
+
+The key |x=|\marg{dimen} simply sets $e_x = (\meta{dimen},0)^T $ while |y=|\marg{dimen} sets $e_y = (0,\meta{dimen})^T$.
+Here, \marg{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. It is allowed to specify a negative \marg{dimen}.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[x=1cm,y=1cm]
-\addplot plot[domain=0:3] (\x,2*\x);
+\addplot expression[domain=0:3] {2*x};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[x=1cm,y=-0.5cm]
+\addplot expression[domain=0:3] {2*x};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})^T$ explicitly\footnote{Please note that you need extra curly braces around the vector. Otherwise, the comma will be interpreted as separator for the next key-value pair.}; the corresponding |y| key works similiarly. This allows to define skewed or rotated axes.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[x={(1cm,0.1cm)},y=1cm]
+\addplot expression[domain=0:3] {2*x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ x={(5pt,1pt)},
+ y={(-4pt,4pt)}]
+\addplot {1-x^2};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ Setting $x$ explicitly overrides the |width| option. Setting $y$ explicitly overrides the |height| option.
+
Setting |x| and/or |y| for logarithmic axis will set the dimension used for $1 \cdot e \approx 2.71828$.
Please note that it is \emph{not} possible to specify |x| as argument to |tikzpicture|. The option
@@ -2408,7 +3041,75 @@ Sets the unit size for one $x$ (or $y$) coordinate to \marg{dimen}.
\end{tikzpicture}
\end{codeexample}
won't have any effect because an axis rescales its coordinates (see the |width| option).
-\end{pgfplotsxykey}
+
+\paragraph{Limitations:} Unfortunately, skewed axes are \textbf{not available for bar plots}.
+\index{Errors!Skewed axes and bar plots}%
+\index{Bar Plots!Skewed axes problems}%
+\end{pgfplotsxykeylist}
+
+\begin{pgfplotskey}{axis equal=\marg{true,false} (initially false)}
+ Each unit vector is set to the same length while the axis dimensions stay constant. Afterwards, the size ratios for each unit in $x$ and $y$ will be the same.
+
+ Axis limits will be enlarge to compensate for the scaling effect.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[axis equal=false]
+ \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\hspace{1cm}
+\begin{tikzpicture}
+ \begin{axis}[axis equal=true]
+ \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{loglogaxis}[axis equal=false]
+ \addplot expression[domain=1:10000] {x^-2};
+ \end{loglogaxis}
+\end{tikzpicture}
+\hspace{1cm}
+\begin{tikzpicture}
+ \begin{loglogaxis}[axis equal=true]
+ \addplot expression[domain=1:10000] {x^-2};
+ \end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{axis equal image=\marg{true,false} (initially false)}
+ Similar to |axis equal|, but the axis limits will stay constant as well (leading to smaller images).
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[axis equal image=false]
+ \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\hspace{1cm}
+\begin{tikzpicture}
+ \begin{axis}[axis equal image=true]
+ \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{loglogaxis}[axis equal image=false]
+ \addplot expression[domain=1:10000] {x^-2};
+ \end{loglogaxis}
+\end{tikzpicture}
+\hspace{1cm}
+\begin{tikzpicture}
+ \begin{loglogaxis}[axis equal image=true]
+ \addplot expression[domain=1:10000] {x^-2};
+ \end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+\end{pgfplotskey}
\subsection{Error Bars}
\label{sec:errorbars}
@@ -2456,7 +3157,7 @@ coordinates {
\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}}
\begin{codeexample}[]
-\pgfplotstabletypesetfile{pgfplots.testtable2.dat}
+\pgfplotstabletypeset{pgfplots.testtable2.dat}
\begin{tikzpicture}
\begin{loglogaxis}
@@ -2547,7 +3248,7 @@ Allows to change the default drawing commands for error bars. The two arguments
\item the target point, $(\tilde x,\tilde y)$.
\end{itemize}
Both are determined by \PGFPlots\ according to the options described above. The default code is
-\begin{codeexample}[code only][basicstyle=\footnotesize\ttfamily]
+\begin{codeexample}[code only]
/pgfplots/error bars/draw error bar/.code 2 args={%
\pgfkeysgetvalue{/pgfplots/error bars/error mark}%
{\pgfplotserrorbarsmark}%
@@ -2564,7 +3265,7 @@ Both are determined by \PGFPlots\ according to the options described above. The
\subsubsection{Input Formats of Error Coordinates}
\label{sec:errorbar:input}%
-Error bars with explicit error estimations for single data points require some sort of input format. This applies to `|error bars/|\meta{[xy]}| explizit|' and `|error bars/|\meta{[xy]}| explizit relative|'.
+Error bars with explicit error estimations for single data points require some sort of input format. This applies to `|error bars/|\meta{[xy]}| explicit|' and `|error bars/|\meta{[xy]}| explicit relative|'.
Error bar coordinates can be read from `|plot coordinates|' or from `|plot table|'. The inline plot coordinates format is
\begin{codeexample}[code only]
@@ -2681,25 +3382,24 @@ where the `|log plot exponent style|' allows to change number formatting options
\begin{pgfplotskey}{log plot exponent style=\marg{key-value-list}}
Allows to configure the number format of log plot exponents. This style is installed just before `|log base 10 number format code|' will be invoked. Please note that this style will be installed within the default code for `|log number format code|'.
\begin{codeexample}[]
-\tikzset{samples=15}
-\pgfplotsset{every axis/.append style={
- width=7cm,
- xlabel=$x$,
- ylabel=$f(x)$,
- extra y ticks={45},
- legend style={at={(0.03,0.97)},
- anchor=north west}}}
+\pgfplotsset{
+ samples=15,
+ width=7cm,
+ xlabel=$x$,
+ ylabel=$f(x)$,
+ extra y ticks={45},
+ legend style={at={(0.03,0.97)},
+ anchor=north west}}
\begin{tikzpicture}
\begin{semilogyaxis}[
log plot exponent style/.style={
/pgf/number format/fixed zerofill,
- /pgf/number format/precision=1}]
+ /pgf/number format/precision=1},
+ domain=-5:10]
- \addplot plot[id=gnuplot_exp,domain=-5:10]
- function{exp(x)};
- \addplot plot[id=gnuplot_expv,domain=-5:10]
- function{exp(2*x)};
+ \addplot {exp(x)};
+ \addplot {exp(2*x)};
\legend{$e^x$,$e^{2x}$}
\end{semilogyaxis}
@@ -2707,26 +3407,25 @@ Allows to configure the number format of log plot exponents. This style is insta
\end{codeexample}
\begin{codeexample}[]
-\tikzset{samples=15}
-\pgfplotsset{every axis/.append style={
- width=7cm,
- xlabel=$x$,
- ylabel=$f(x)$,
- extra y ticks={45},
- legend style={at={(0.03,0.97)},
- anchor=north west}}}
+\pgfplotsset{
+ samples=15,
+ width=7cm,
+ xlabel=$x$,
+ ylabel=$f(x)$,
+ extra y ticks={45},
+ legend style={at={(0.03,0.97)},
+ anchor=north west}}
\begin{tikzpicture}
\begin{semilogyaxis}[
log plot exponent style/.style={
/pgf/number format/fixed,
/pgf/number format/use comma,
- /pgf/number format/precision=2}]
+ /pgf/number format/precision=2},
+ domain=-5:10]
- \addplot plot[id=gnuplot_exp,domain=-5:10]
- function{exp(x)};
- \addplot plot[id=gnuplot_expv,domain=-5:10]
- function{exp(2*x)};
+ \addplot {exp(x)};
+ \addplot {exp(2*x)};
\legend{$e^x$,$e^{2x}$}
\end{semilogyaxis}
@@ -2734,51 +3433,6 @@ Allows to configure the number format of log plot exponents. This style is insta
\end{codeexample}
\end{pgfplotskey}
-%--------------------------------------------------
-% \subsubsection{Defining Own Display Styles}
-% You can define own display styles, although this may require some insight into \TeX-programming. Here are two examples:
-% \begin{enumerate}
-% \item A new fixed point display style: The following code defines a new style named `\texttt{my own fixed point style}' which uses $1{\cdot}00$ instead of $1.00$.
-% \begin{lstlisting}
-% \def\myfixedpointstyleimpl#1.#2\relax{%
-% #1{\cdot}#2%
-% }%
-% \def\myfixedpointstyle#1{%
-% \pgfutilensuremath{%
-% \ifpgfmathfloatroundhasperiod
-% \expandafter\myfixedpointstyleimpl#1\relax
-% \else
-% #1%
-% \fi
-% }%
-% }
-% \pgfkeys{/my own fixed point style/.code={%
-% \let\pgfmathprintnumber@fixed@style=\myfixedpointstyle}
-% }%
-% \end{codeexample}
-% You only need to overwrite the macro |\pgfmathprintnumber@fixed@style|. This macro takes one argument (the result of any numerical computations). The \TeX-boolean |\ifpgfmathfloatroundhasperiod| is true if and only if the input number contains a period.
-%
-% \item An example for a new scientific display style:
-% \begin{lstlisting}
-% % #1:
-% % 0 == '0' (the number is +- 0.0),
-% % 1 == '+',
-% % 2 == '-',
-% % 3 == 'not a number'
-% % 4 == '+ infinity'
-% % 5 == '- infinity'
-% % #2: the mantisse
-% % #3: the exponent
-% \def\myscistyle#1#2e#3\relax{%
-% ...
-% }
-% \pgfkeys{/my own sci style/.code={%
-% \let\pgfmathfloatrounddisplaystyle=\myscistyle},
-% }%
-% \end{codeexample}
-% \end{enumerate}
-%--------------------------------------------------
-
@@ -2789,13 +3443,13 @@ The options |xmin|, |xmax| and |ymin|, |ymax| allow to define the axis limits, i
Each missing limit will be determined automatically.
-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 disable using |clip limits=false|.
+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.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2803,7 +3457,7 @@ Axis limits can be increased automatically using the |enlargelimits| option.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[xmin=0]
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2811,7 +3465,7 @@ Axis limits can be increased automatically using the |enlargelimits| option.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[ymax=10]
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2846,12 +3500,13 @@ A small value of |enlarge x limits| may avoid problems with large markers near t
\end{stylekey}
\begin{environment}{{pgfplotsinterruptdatabb}}
+\index{Bounding Box Control!Disable \protect\emph{data} bounding box modifications}
Everything in \marg{environment contents} will not contribute to the data bounding box.
\end{environment}
\subsection{Tick and Grid Options}
-\begin{pgfplotsxykey}{\x tick=\mchoice{\textbackslash empty,data,\marg{coordinate list}} (initially \marg{})}
+\begin{pgfplotsxykey}{\x tick=\mchoice{\textbackslash empty,data,\normalfont\marg{coordinate list}} (initially \marg{})}
The options |xtick| and |ytick| assigns a list of \emph{Positions} where ticks shall be placed. The argument is either the command |\empty|, |data| or a list of coordinates. The choice |\empty| will result in no tick at all. The special value |data| will produce tick marks at every coordinate of the first plot. Otherwise, tick marks will be placed at every coordinate in \marg{coordinate list}. If this list is empty, \PGFPlots\ will compute a default list.
\marg{coordinate list} will be used inside of a |\foreach \x in |\marg{coordinate list} statement. The format is as follows:
@@ -2861,11 +3516,13 @@ The options |xtick| and |ytick| assigns a list of \emph{Positions} where ticks s
\item |{0,2,...,10}| (the same as |{0,2,4,6,8,10}|),
\item |{9,...,3.5}| (the same as |{9, 8, 7, 6, 5, 4}|),
\item See \cite[Section~34]{tikz} for a more detailed definition of the options.
+ \item Please be careful with whitespaces inside of \marg{coordinate list} (at least around the dots).
\end{itemize}
For logplots, \PGFPlots\ will apply $\log(\cdot)$ to each element in `\marg{coordinate list}'.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[xtick={12,9897,1468864}]
+ % see above for this macro:
\plotcoords
\end{loglogaxis}
\end{tikzpicture}
@@ -2911,7 +3568,7 @@ or
\end{codeexample}
Please prefer the `|.append style|' versions whenever possible to ensure compatibility with future versions.
-This style commands can be used at any time. The tick line width can be configured with `|major tick length|' and `|minor tick length|'.
+These style commands can be used at any time. The tick line width can be configured with `|major tick length|' and `|minor tick length|'.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -2950,8 +3607,8 @@ This style commands can be used at any time. The tick line width can be configur
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[minor tick num=1]
- \addplot (\x,\x^3);
- \addplot (\x,-20*\x);
+ \addplot {x^3};
+ \addplot {-20*x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2959,8 +3616,8 @@ This style commands can be used at any time. The tick line width can be configur
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[minor tick num=3]
- \addplot (\x,\x^3);
- \addplot (\x,-20*\x);
+ \addplot {x^3};
+ \addplot {-20*x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2975,8 +3632,8 @@ This style commands can be used at any time. The tick line width can be configur
\begin{tikzpicture}
\begin{axis}[minor x tick num=1,
minor y tick num=3]
- \addplot (\x,\x^3);
- \addplot (\x,-20*\x);
+ \addplot {x^3};
+ \addplot {-20*x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -2999,7 +3656,7 @@ Adds \emph{additional} tick positions and tick labels to the $x$~or~$y$ axis. `A
rotate=90,anchor=east}},
extra x tick labels={Cut},
]
- \addplot (\x,{exp(\x)});
+ \addplot {exp(x)};
\addlegendentry{$e^x$}
\end{axis}
\end{tikzpicture}
@@ -3051,7 +3708,7 @@ They are affected by |major tick length| or options like |grid=major|.
\end{pgfplotsxykey}
\begin{pgfplotskeylist}{
- space between ticks=\marg{number} (initially 35),
+ max space between ticks=\marg{number} (initially 35),
try min ticks=\marg{number} (initially 4),
try min ticks log=\marg{number} (initially 3)}
see Options |xtick| and |ytick| for a description.
@@ -3070,18 +3727,18 @@ These options allow to place ticks at selected positions $10^k, k \in \text{\mar
Using `|xtickten={1,2,3,4}|' is equivalent to `|xtick={1e1,1e2,1e3,1e4}|', but it requires fewer computational time and it allows to use the short syntax `|xtickten={1,...,4}|'.
\begin{codeexample}[]
-\begin{tikzpicture}[samples=8]
+\begin{tikzpicture}
\begin{semilogyaxis}[
+ samples=8,
ytickten={-6,-4,...,4},
domain=0:10]
-% invoke gnuplot to generate coordinates:
-\addplot plot[id=pow1]
- function {2**(-2*x + 6)};
+\addplot {2^(-2*x + 6)};
\addlegendentry{$2^{-2x + 6}$}
+% or invoke gnuplot to generate coordinates:
\addplot plot[id=pow2]
- function {2**(-1.5*x -3)};
+ gnuplot {2**(-1.5*x -3)};
\addlegendentry{$2^{-1.5x -3}$}
\end{semilogyaxis}
\end{tikzpicture}
@@ -3194,7 +3851,7 @@ which has the same effect as the `|every x tick label|' statement above. This is
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[x tick label as interval]
- \addplot (\x,3*\x);
+ \addplot {3*x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -3226,12 +3883,9 @@ which has the same effect as the `|every x tick label|' statement above. This is
\label{sec:scaled:ticks}%
\begin{pgfplotsxykeylist}{
- scaled \x\ ticks=\mchoice{true,false} (initially true),
- scaled ticks=\mchoice{true,false} (initially true)}
-Allows to factor out common exponents in tick labels. For example, if you have tick labels $20000,40000$ and $60000$, you may want to save some space and write $2,4,6$ with a separate factor `$\cdot 10^4$'. Use `|scaled ticks=true|' to enable this feature (default is |true|).
-
- The |scaled ticks| key is a style which simply enables scaled ticks for both, $x$ and $y$.
-
+ scaled \x\ ticks=\mchoice{true,false,base 10:{\normalfont\meta{e}},real:{\normalfont\meta{number}},manual:{\normalfont\marg{text}\marg{tick scale code}}} (initially true),
+ scaled ticks=\mchoice{true,false,base 10:{\normalfont\meta{e}},real:{\normalfont\meta{number}},manual:{\normalfont\marg{text}\marg{tick scale code}\hfill}} (initially true)}
+Allows to factor out common exponents in tick labels for \emph{linear axes}. For example, if you have tick labels $20000,40000$ and $60000$, you may want to save some space and write $2,4,6$ with a separate factor `$\cdot 10^4$'. Use `|scaled ticks=true|' to enable this feature. In case |true|, tick scaling will be triggered if the data range is either too large or too small (see below).
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[scaled ticks=true]
@@ -3255,13 +3909,102 @@ Allows to factor out common exponents in tick labels. For example, if you have t
\end{axis}
\end{tikzpicture}
\end{codeexample}
+
+ The |scaled ticks| key is a style which simply sets scaled ticks for both, $x$ and $y$.
+
+ The value |base 10:|\meta{e} allows to adjust the algorithm manually. For example, |base 10:3| will divide every tick label by $10^3$:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[scaled ticks=base 10:3,
+ /pgf/number format/sci subscript]
+ \addplot coordinates
+ {(-0.00001,2e12) (-0.00005,4e12) };
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Here, the \texttt{sci subscript} option simply saves space.
+In general, |base 10:|$e$ will divide every tick by $10^e$. The effect
+is not limited by the ``too large or too small'' decisions mentioned
+above.
+
+ The value |real:|\meta{number} allows to divide every tick by a fixed \meta{number}.
+ For example, the following plot is physically ranged from $0$ to $2\pi$, but the tick scaling algorithm is configured to divide every tick label by $\pi$.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ xtick={0,1.5708,...,10},
+ domain=0:2*pi,
+ scaled x ticks={real:3.1415},
+ xtick scale label code/.code={$\cdot \pi$}]
+ \addplot {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ \noindent Setting |scaled ticks=real:|\meta{number} also changes the |tick scale label code| to
+\begin{codeexample}[code only]
+\pgfkeys{/pgfplots/xtick scale label code/.code={$\cdot \pgfmathprintnumber{#1}$}}.
+\end{codeexample}
+
+A further -- not very useful -- example is shown below. Every $x$ tick label has been divided by $2$, every $y$ tick label by $3$.
+\nobreak
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ scaled x ticks=real:2,
+ scaled y ticks=real:3]
+ \addplot {x^3};
+ \node[pin=135:{$(3,9)$}] at (axis cs:3,9) {};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ Unfortunately, \meta{number} can't be evaluated with \PGF's math parser (yet) to maintain the full data range accepted by \PGFPlots.
+
+ The last option, |scaled ticks=manual:|\marg{text}\marg{tick scale code} allows even more customization. It allows \emph{full control} over the displayed scaling label \emph{and} the scaling code: \marg{text} is used as-is inside of the tick scaling label while \marg{tick scale code} is supposed to be a one-argument-macro which scales each tick. Example:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ % warning: the '%' signs are necessary (?)
+ scaled y ticks=manual:{$+65\,535$}{%
+ \pgfmathfloatcreate{1}{6.5535}{4}%
+ \pgfmathfloatsubtract{#1}{\pgfmathresult}%
+ },
+ yticklabel style={
+ /pgf/number format/fixed,
+ /pgf/number format/precision=1},
+]
+\addplot plot coordinates {
+ (0, 65535)
+ (13, 65535)
+ (14, 65536)
+ (15, 65537)
+ (30, 65537)
+};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent The example uses |$+65\,535$| as tick scale label content. Furthermore, it defines the customized tick label formula $y - (+6.5535\cdot 10^4) = y - 65535$ to generate $y$ tick labels.
+
+The \marg{text} can be arbitrary. It is completely in user control. The second argument, \marg{tick scale code} is supposed to be a one-argument-macro in which |#1| is the current tick position in floating point representation. The macro is expected to assign |\pgfmathresult| (also in floating point representation). The \PGF\ manual~\cite{tikz} contains detailed documentation about its math engine (including floating point\footnote{However, that particular stuff is newer than \PGF\ $2.00$. At the time of this writing, it is only available as (public) CVS version.}).
+
+This feature may also be used do transform coordinates in case they can't be processed with \PGFPlots: transform them and supply a proper tick scaling method such that tick labels represent the original range.
+
+If \marg{text} is empty, the tick scale label won't be drawn (and no space will be occupied).
+
+Tick scaling does \emph{not} work for logarithmic axes.
\end{pgfplotsxykeylist}
-\begin{pgfplotscodekey}{tick scale label code}
+\begin{pgfplotsxycodekeylist}{\x tick scale label code}
Allows to change the default code for scaled tick labels. The default is
\begin{codeexample}[code only]
-tick scale label code/.code={$\cdot 10^{#1}$}.
+xtick scale label code/.code={$\cdot 10^{#1}$}.
\end{codeexample}
+
+If the code is empty, no tick scale label will be drawn (and no space is consumed).
+\end{pgfplotsxycodekeylist}
+
+\begin{pgfplotscodekey}{tick scale label code}
+ A style which sets both, |xtick scale label code| and the corresponding variant for $y$.
\end{pgfplotscodekey}
\begin{pgfplotskey}{scale ticks below=\marg{exponent}}
@@ -3282,7 +4025,7 @@ Allows fine tuning of the '|scaled ticks|' algorithm: if the axis limits are of
\begin{pgfplotsxykey}{\x tick pos=\mchoice{left,right,both} (initially both)}
Allows to choose where to place the small tick lines. In the default configuration, this does also affect tick \emph{labels}, see below.
-For $y$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$.
+For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$.
\end{pgfplotsxykey}
\begin{pgfplotskey}{tickpos=\mchoice{left,right,both}}
@@ -3292,7 +4035,7 @@ For $y$, the additional choices |bottom| and |top| can be used which are equival
\begin{pgfplotsxykey}{\x ticklabel pos=\mchoice{left,right,default} (initially default)}
Allows to choose where to place tick \emph{labels}. The choices |left| and |right| place tick labels either at the left or at the right side of the complete axis. The choice |default| uses the same setting as |xtick pos| (or |ytick pos|). This option is only useful for boxed axis -- keep it to |default| for non-boxed figures.
-For $y$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$.
+For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $x$.
\end{pgfplotsxykey}
\begin{pgfplotskey}{ticklabelpos=\mchoice{left,right,default}}
@@ -3386,6 +4129,7 @@ This example employs the coordinates defined on page~\pageref{page:plotcoords:sr
ylabel={$L_2$ Error},
grid=major
]
+% see above for this macro:
\plotcoords
\end{loglogaxis}
\end{tikzpicture}
@@ -3413,6 +4157,9 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn
\end{codeexample}
\end{pgfplotsxykeylist}
+\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord}, \x tickmax=\marg{coord}}
+ These keys can be used to modify minimum/maximum values before ticks are drawn. Because this applies to axis discontinuities, it is described on page~\pageref{key:xytickminmax} under section~\ref{key:xytickminmax}, ``Axis Discontinuities"'.
+\end{pgfplotsxykeylist}
@@ -3435,14 +4182,6 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn
Use |\pgfplotsset{|\meta{key}|/.append style={|\meta{key-value-list}|}}| to append \marg{key-value-list} to the style \meta{key}. This will assume the prefix |/pgfplots|.
\end{handler}
-\begin{command}{\pgfplotsset\marg{key-value-list}}
- Defines or sets all options in \marg{key-value-list}.
-
- It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path.
-
- You can define new style keys with |.style| and |.append style|, see above.
-\end{command}
-
\subsubsection*{Styles installed for linear/logarithmic axis}
\begin{stylekey}{/pgfplots/every axis (initially empty)}
@@ -3469,8 +4208,6 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn
\begin{stylekey}{/pgfplots/every axis plot (initially empty)}
Installed for each plot. This style may contain \meta{behavior options} like samples, gnuplot parameters, error bars and it may contain \meta{style options} which affect the final drawing commands.
-
-% \FIXME{currently, pgfplots options need to be prefixed with /pgfplots/}
\end{stylekey}
\begin{stylekey}{/pgfplots/every axis plot post (initially empty)}
@@ -3485,8 +4222,8 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn
legend style={
at={(0.03,0.97)},anchor=north west},
domain=0:1]
- \addplot (\x,\x^2);
- \addplot (\x,{exp(\x)});
+ \addplot {x^2};
+ \addplot {exp(x)};
\legend{$x^2$,$e^x$}
\end{axis}
\end{tikzpicture}
@@ -3494,7 +4231,11 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn
\end{stylekey}
\begin{stylekey}{/pgfplots/every axis plot no \# (initially empty)}
- Used for every \#th plot where $\#=1,2,3,4,\dotsc$. This option may also contain \meta{behavior options}.
+ Used for every \#th plot where $\#=0,1,2,3,4,\dotsc$. This option may also contain \meta{behavior options}.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/every forget plot (initially empty)}
+ Used for every plot which has |forget plot| activated. This option may also contain \meta{behavior options}.
\end{stylekey}
\subsubsection*{Styles for axis descriptions}
@@ -3503,7 +4244,7 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn
Used for $x$~and~$y$ axis label. You can use `|at=|\parg{x,y} to set its position where $(0,0)$ refers to the lower left corner and $(1,1)$ to the upper right one.
\end{stylekey}
-\pgfplotsshortstylekey label style=every axis label;
+\pgfplotsshortstylekey label style=every axis label\pgfeov
\begin{xystylekey}{/pgfplots/every axis \x\ label}
Used only~$x$ or only for~$y$ labels, installed after `|every axis label|'.
@@ -3524,7 +4265,7 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn
\paragraph{Attention:} These styles will be overwritten by |axis x line| and/or |axis y line|. Please remember to place your modifications after the axis line variations.
\end{xystylekey}
-\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label;
+\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label\pgfeov
\begin{stylekey}{/pgfplots/every axis title}
Used for any axis title. The |at=|\parg{x,y} command works as for `|every axis label|'.
@@ -3535,7 +4276,7 @@ The initial setting is
\end{codeexample}
\end{stylekey}
-\pgfplotsshortstylekey title style=every axis title;
+\pgfplotsshortstylekey title style=every axis title\pgfeov
\begin{stylekey}{/pgfplots/every axis legend}
Installed for each legend. As for |every axis label|, the legend's position can be placed using coordinates between $0$~and~$1$, see above.
@@ -3552,7 +4293,7 @@ The initial setting is
\end{codeexample}
\end{stylekey}
-\pgfplotsshortstylekey legend style=every axis legend;
+\pgfplotsshortstylekey legend style=every axis legend\pgfeov
\subsubsection*{Styles for axis lines}
\begin{xystylekey}{/pgfplots/every outer \x\ axis line (initially empty)}
@@ -3584,19 +4325,19 @@ Please refer to section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots:
Installed for each of the small tick \emph{lines}.
\end{stylekey}
-\pgfplotsshortstylekey tick style=every tick;
+\pgfplotsshortstylekey tick style=every tick\pgfeov
\begin{stylekey}{/pgfplots/every minor tick (initially empty)}
Used for each minor tick line, installed after `|every tick|'.
\end{stylekey}
-\pgfplotsshortstylekey minor tick style=every minor tick;
+\pgfplotsshortstylekey minor tick style=every minor tick\pgfeov
\begin{stylekey}{/pgfplots/every major tick (initially empty)}
Used for each major tick line, installed after `|every tick|'.
\end{stylekey}
-\pgfplotsshortstylekey major tick style=every major tick;
+\pgfplotsshortstylekey major tick style=every major tick\pgfeov
\begin{stylekey}{/pgfplots/every tick label (initially empty)}
Used for each $x$~and~$y$ tick labels.
@@ -3606,7 +4347,7 @@ Please refer to section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots:
Used for each $x$ (or $y$, respectively) tick label, installed after `|every tick label|'.
\end{xystylekey}
-\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label;
+\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label\pgfeov
\begin{xystylekey}{/pgfplots/every \x\ tick scale label}
Configures placement and display of the nodes containing the order of magnitude of tick labels, see section~\ref{sec:scaled:ticks} for more information about |scaled ticks|.
@@ -3619,24 +4360,24 @@ The initial settings are
\end{codeexample}
\end{xystylekey}
-\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label;
+\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label\pgfeov
\begin{xystylekey}{/pgfplots/every \x\ tick (initially empty)}
Installed for tick \emph{lines} on either $x$ or $y$ axis.
\end{xystylekey}
-\pgfplotsshortxystylekey \x\ tick style=every \x\ tick;
+\pgfplotsshortxystylekey \x\ tick style=every \x\ tick\pgfeov
\begin{xystylekey}{/pgfplots/every minor \x\ tick (initially empty)}
Installed for minor tick lines on either $x$ or $y$ axis.
\end{xystylekey}
-\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick;
+\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick\pgfeov
\begin{xystylekey}{/pgfplots/every major \x\ tick (initially empty)}
Installed for major tick lines on either $x$ or $y$ axis.
\end{xystylekey}
-\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick;
+\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick\pgfeov
\begin{xystylekey}{/pgfplots/every extra \x\ tick}
Allows to configure the appearance of `|extra x ticks|'. This style is installed before touching the first extra $x$~tick. It is possible to set any option which affects tick or grid line generation.
@@ -3656,7 +4397,7 @@ The initial setting is
\end{codeexample}
\end{xystylekey}
-\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick;
+\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick\pgfeov
@@ -3666,37 +4407,37 @@ The initial setting is
Used for each grid line.
\end{stylekey}
-\pgfplotsshortstylekey grid style=every axis grid;
+\pgfplotsshortstylekey grid style=every axis grid\pgfeov
\begin{stylekey}{/pgfplots/every minor grid (initially empty)}
Used for each minor grid line, installed after `|every axis grid|'.
\end{stylekey}
-\pgfplotsshortstylekey minor grid style=every minor grid;
+\pgfplotsshortstylekey minor grid style=every minor grid\pgfeov
\begin{stylekey}{/pgfplots/every major grid (initially empty)}
Likewise, for major grid lines.
\end{stylekey}
-\pgfplotsshortstylekey major grid style=every major grid;
+\pgfplotsshortstylekey major grid style=every major grid\pgfeov
\begin{xystylekey}{/pgfplots/every axis \x\ grid (initially empty)}
Used for each grid line in either $x$ or $y$ direction.
\end{xystylekey}
-\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid;
+\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid\pgfeov
\begin{xystylekey}{/pgfplots/every minor \x\ grid (initially empty)}
Used for each minor grid line in either $x$ or $y$ direction.
\end{xystylekey}
-\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid;
+\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid\pgfeov
\begin{xystylekey}{/pgfplots/every major \x\ grid (initially empty)}
Used for each major grid line in either $x$ or $y$ direction.
\end{xystylekey}
-\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid;
+\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid\pgfeov
\subsubsection*{Styles for error bars}
@@ -3704,7 +4445,7 @@ The initial setting is
Installed for every error bar.
\end{stylekey}
-\pgfplotsshortstylekey error bars/error bar style=every error bar;
+\pgfplotsshortstylekey error bars/error bar style=every error bar\pgfeov
\subsubsection{(Re-)Defining Own Styles}
\label{sec:styles:own}%
@@ -3721,7 +4462,7 @@ to create own styles. If \meta{style name} exists already, it will be replaced.
\end{tikzpicture}
\end{codeexample}
-\subsection{Alignment Options}
+\subsection{Alignment Options and Bounding Box Control}
\label{pgfplots:sec:align}
\begin{pgfplotskey}{anchor=\marg{name} (initially south west)}
@@ -3748,7 +4489,7 @@ There are four sets of anchors available: anchors positioned on the axis rectang
\addplot table from{\plottable};
%\addplot coordinates {(0,0) (1,1)};
\addlegendentry{$f(x)$}
- \addplot[red] plot[id=gnuplot_ppp,domain=-40:40,samples=120] function{10000*sin(x/3)};
+ \addplot[red] plot[id=gnuplot_ppp,domain=-40:40,samples=120] gnuplot{10000*sin(x/3)};
\addlegendentry{$g(x)$}
\end{axis}
}%
@@ -3827,7 +4568,7 @@ And finally, we have origin anchors which are especially useful when axis lines
every axis y label/.style={at={(current axis.above origin)},anchor=north east},
inner axis line style={->},
]
- \addplot plot[domain=-2:5] (\x,20*\x);
+ \addplot plot[domain=-2:5] {20*x};
\end{axis}
{\pgfplotsset{every pin/.append style={pin distance=1cm}}%
\showit{above origin}{45}
@@ -3851,13 +4592,13 @@ The default axis anchor is |south west|, which means that the picture coordinate
\tikzset{domain=-1:1}
\begin{tikzpicture}
\begin{axis}[xlabel=A normal sized $x$ label]
- \addplot[smooth,blue,mark=*] (\x,\x^2);
+ \addplot[smooth,blue,mark=*] {x^2};
\end{axis}
\end{tikzpicture}%
\hspace{0.15cm}
\begin{tikzpicture}
\begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }]
- \addplot[smooth,blue,mark=*] (\x,\x^2);
+ \addplot[smooth,blue,mark=*] {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -3866,13 +4607,13 @@ The default axis anchor is |south west|, which means that the picture coordinate
\tikzset{domain=-1:1}
\begin{tikzpicture}[baseline]
\begin{axis}[xlabel=A normal sized $x$ label]
- \addplot[smooth,blue,mark=*] (\x,\x^2);
+ \addplot[smooth,blue,mark=*] {x^2};
\end{axis}
\end{tikzpicture}%
\hspace{0.15cm}
\begin{tikzpicture}[baseline]
\begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }]
- \addplot[smooth,blue,mark=*] (\x,\x^2);
+ \addplot[smooth,blue,mark=*] {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -3921,12 +4662,70 @@ cycle list={
\end{codeexample}
-\item[Bounding box restrictions]
+\item[Bounding box restrictions] Bounding box restrictions can be realized with several methods of \PGF:
+\begin{enumerate}
+ \item The |overlay| option,
+ \item The |pgfinterruptboundingbox| environment,
+ \item The |\useasboundingbox| path.
+\end{enumerate}
+\begin{key}{/tikz/overlay}
+\index{Bounding Box Control!Excluding Image Parts}
+ A special key of \PGF\ which disables bounding box updates for (parts of) the image. The effect is that those parts are an ``overlay'' over the document.
+
+ For \PGFPlots, |overlay| can be useful to position legends or other axis descriptions outside of the axis~-- without affecting its size (and without affecting alignment).
+
+For example, one may want to include only certain parts of the axis into the final bounding box. This would allow horizontal alignment (centering):
+\begin{codeexample}[]
+\begin{tikzpicture}%
+ \begin{axis}[
+ title=A title,
+ ylabel style={overlay},
+ yticklabel style={overlay},
+ xlabel={$x$},
+ ylabel={$y$},
+ legend style={at={(0.5,0.97)},
+ anchor=north,legend columns=-1},
+ domain=-2:2
+ ]
+ \addplot {x^2};
+ \addplot {x^3};
+ \addplot {x^4};
+ \legend{$x^2$,$x^3$,$x^4$}
+ \end{axis}
+\end{tikzpicture}%
+\end{codeexample}
+\noindent Now, the left axis descriptions ($y$ label and $y$ ticks) stick out of the bounding box.
+
+The following example places a legend somewhere without affecting the bounding box.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ domain=0:6.2832,samples=200,
+ legend style={
+ overlay,
+ at={(-0.5,0.5)},
+ anchor=center},
+ every axis plot post/.append style={mark=none},
+ enlargelimits=false]
+
+ \addplot {sin(deg(x)+3)+rand*0.05};
+ \addplot {cos(deg(x)+2)+rand*0.05};
+ \legend{Signal 1,Signal 2}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ More information about the |overlay| option can be found in the \PGF\ manual~\cite{tikz}.
+\end{key}
+
+
\label{sec:bounding:box:example}%
+\index{Bounding Box Control}
+\index{Bounding Box Control!pgfinterruptboundingbox}
{%
-The following figure is centered and encapsulated with an |\fbox| to show its bounding box.
-\setlength{\fboxsep}{0pt}%
+An alternative to |overlay| is shown below: the figure has a truncated bounding box with is shown using |\fbox|.
\begin{codeexample}[]
+\setlength{\fboxsep}{0pt}%
\fbox{%
\begin{tikzpicture}%
\begin{pgfinterruptboundingbox}
@@ -3939,9 +4738,9 @@ The following figure is centered and encapsulated with an |\fbox| to show its bo
anchor=north,legend columns=-1},
domain=-2:2
]
- \addplot (\x,\x^2);
- \addplot (\x,\x^3);
- \addplot (\x,\x^4);
+ \addplot {x^2};
+ \addplot {x^3};
+ \addplot {x^4};
\legend{$x^2$,$x^3$,$x^4$}
\end{axis}
\end{pgfinterruptboundingbox}
@@ -3953,7 +4752,7 @@ The following figure is centered and encapsulated with an |\fbox| to show its bo
}%
\end{codeexample}%
}%
-The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument.
+The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument (see~\cite{tikz}).
\end{description}
\end{pgfplotskey}
@@ -3967,10 +4766,11 @@ The |pgfinterruptboundingbox| environment does not include its content into the
\end{predefinednode}
\begin{pgfplotskey}{at=\marg{coordinate expression}}
-Assigns a position for the complete axis image. This option works similarly to the |at|-option of |\node[at=|\marg{coordinate expression}|]|, see~\cite{tikz}. The common syntax is |at=|\parg{x,y}.
+Assigns a position for the complete axis image. This option works similarly to the |at|-option of |\node[at=|\marg{coordinate expression}|]|, see~\cite{tikz}. The common syntax is |at={|\parg{x,y}|}|.
\end{pgfplotskey}
\subsection{Symbolic Coordinates and User Transformations}
+\label{pgfplots:sec:symbolic:coords}
\PGFPlots\ supports user transformations which can be applied to input and output coordinates. Suppose the plot shall display days versus account statements over time. Then, one wants to visualize date versus credit balance. But: dates need to be transformed to numbers before doing so! Furthermore, tick labels shall be displayed as dates as well. This, and more general transformations, can be realized using the |x coord trafo| and |y coord trafo| keys.
\begin{pgfplotsxycodekeylist}{
@@ -4005,7 +4805,8 @@ Assigns a position for the complete axis image. This option works similarly to t
\noindent which simply disables the transformation (the same for $y$, of course).
\end{pgfplotsxycodekeylist}
-\subsubsection{Dates as input coordinates}
+\subsubsection{Dates as Input Coordinates}
+\label{pgfplots:sec:date:coords}
The already mentioned application of using dates as input coordinates has been predefined. It relies on the \pgfname\ calendar library which converts dates to numbers in the julian calendar. Then, one coordinate unit is one day.
\begin{tikzlibrary}{dateplot}
@@ -4029,10 +4830,11 @@ The already mentioned application of using dates as input coordinates has been p
A complete example (with fictional data) is shown below.
\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}}
+% \usetikzlibrary{dateplot}\usepackage{eurosym}
\begin{codeexample}[]
% requires \usetikzlibrary{dateplot} !
-\pgfplotstabletypesetfile[string type]{plotdata/accounts.dat}
+\pgfplotstabletypeset[string type]{plotdata/accounts.dat}
\begin{tikzpicture}
\begin{axis}[
@@ -4072,6 +4874,8 @@ where $y = \log(m)$ is computed with a newton method applied to $\exp(y) - m$. T
\label{sec:disabledatascaling}%
\begin{pgfplotskey}{disabledatascaling=\mchoice{true,false} (initally false, default true)}
+\index{Accuracy!Data Transformation}%
+\index{Errors!dimension too large}%
Disables internal re-scaling of input data. Normally, every input data like plot coordinates, tick positions or whatever, are parsed without using \TeX's limited number precision. Then, a transformation like
\[ T(x) = 10^{q-m} \cdot x - a \]
is applied to every input coordinate/position where $m$ is ``the order of $x$'' base~$10$. Example: $x=1234 = 1.234\cdot 10^3$ has order~$m=4$ while $x=0.001234 = 1.234\cdot 10^{-3}$ has order $m=-2$. The parameter~$q$ is the order of the axis' width/height.
@@ -4085,10 +4889,10 @@ So far, the data scale transformation applies only to normal axis (logarithmic s
\end{pgfplotskey}
-\begin{pgfplotsxykey}{\x\ filter/.code=\marg{...}} % FIXME create a xycodekey environment
+\begin{pgfplotsxycodekeylist}{\x\ filter}
The code keys |x filter| and |y filter| allow coordinate filtering. A coordinate filter gets an input coordinate as |#1|, applies some operation and writes the result into the macro |\pgfmathresult|. If |\pgfmathresult| is empty afterwards, the coordinate is discarded.
-It is allowed if filters do not |\pgfmathresult|. In this case, the unfiltered coordinate will be used.
+It is allowed if filters do not change |\pgfmathresult|. In this case, the unfiltered coordinate will be used.
Coordinate filters are useful in automatic processing system, where \PGFPlots\ is used to display automatically generated plots. You may not want to filter your coordinates by hand, so these options provide a tool to do this automatically.
@@ -4118,7 +4922,7 @@ During evaluation of the filter, the macro |\coordindex| contains the number of
\fi
\fi
}]
-\addplot (\x,\x^2);
+\addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -4129,7 +4933,7 @@ There is also a style key which simplifies selection by index, see below.
If the corresponding axis is logarithmic, |#1| is the \emph{logarithm} of the coordinate as a real number, for example |#1=4.2341|.
The arguments to coordinate filters are not transformed. You may need to call coordinate parsing routines.
-\end{pgfplotsxykey}
+\end{pgfplotsxycodekeylist}
\begin{stylekey}{/pgfplots/skip coords between index=\marg{begin}\marg{end}}
A style which appends an |x filter| which discards selected coordinates. The selection is done by index where indexing starts with~$0$, see |\coordindex|. Every coordinate with index $\meta{begin} \le i < \meta{end}$ will be skipped.
@@ -4140,7 +4944,7 @@ There is also a style key which simplifies selection by index, see below.
skip coords between index={5}{11},
skip coords between index={15}{18}]
-\addplot (\x,\x^2);
+\addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -4153,13 +4957,49 @@ There is also a style key which simplifies selection by index, see below.
\begin{pgfplotskey}{execute at begin plot=\marg{commands}}
This axis option allows to invoke \marg{commands} at the beginning of each |\addplot| command. The argument \marg{commands} can be any \TeX\ content.
-You may use this in conjunction with |xfilter=...| to reset any counters or whatever. An example would be to change every $4$th coordinate.
+You may use this in conjunction with |x filter=...| to reset any counters or whatever. An example would be to change every $4$th coordinate.
\end{pgfplotskey}
\begin{pgfplotskey}{execute at end plot=\marg{commands}}
This axis option allows to invoke \marg{commands} after each |\addplot| command. The argument \marg{commands} can be any \TeX\ content.
\end{pgfplotskey}
+\begin{pgfplotskey}{forget plot=\marg{true,false} (initially false)}
+\label{pgfplots:forgetplot}
+ Allows to include plots which are not remembered for legend entries, which do not increase the number of plots and which are not considered for cycle lists.
+
+ A forgotten plot can be some sort of decoration which has a separate style and does not influence the axis state, although it is processed as any other plot.
+ Please provide this option as \meta{behavior option} to |\addplot| as in the following example.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{loglogaxis}[
+ table/x=Basis,
+ table/y={L2/r},
+ xlabel=Degrees of Freedom,
+ ylabel=relative Error,
+ title=New Experiments (old in gray),
+ legend entries={$e_1$,$e_2$,$e_3$}
+ ]
+ \addplot[black!15] plot[forget plot]
+ table {plotdata/oldexperiment1.dat};
+ \addplot[black!15] plot[forget plot]
+ table {plotdata/oldexperiment2.dat};
+ \addplot[black!15] plot[forget plot]
+ table {plotdata/oldexperiment3.dat};
+ \addplot table {plotdata/newexperiment1.dat};
+ \addplot table {plotdata/newexperiment2.dat};
+ \addplot table {plotdata/newexperiment3.dat};
+ \end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+ Since forgotten plots won't increase the plot index, they will use the same |cycle list| entry as following plots. This can be used to ``interrupt'' plots as is described in section~\ref{pgfplots:interrupt}.
+\index{Interrupted Plots}
+
+ The style |every forget plot| can be used to configure styles for each such plot. Please note that |every plot no |\meta{index} styles are not applicable here.
+
+ A forgotten plot will be stacked normally if |stack plots| is enabled!
+\end{pgfplotskey}
+
\begin{pgfplotscodekey}{before end axis}
Allows to insert \marg{commands} just before the axis is ended. This option takes effect inside of the clipped area.
\begin{codeexample}[]
@@ -4172,7 +5012,7 @@ Allows to insert \marg{commands} just before the axis is ended. This option take
}}}
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -4189,7 +5029,7 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm
}}}
\begin{tikzpicture}
\begin{axis}
- \addplot (\x,\x^2);
+ \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -4207,7 +5047,7 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm
axis on top=true,
axis x line=middle,
axis y line=middle]
- \addplot+[fill] (\x,\x^3) \closedcycle;
+ \addplot+[fill] {x^3} \closedcycle;
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -4218,9 +5058,23 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm
axis on top=false,
axis x line=middle,
axis y line=middle]
- \addplot+[fill] (\x,\x^3) \closedcycle;
+ \addplot+[fill] {x^3} \closedcycle;
\end{axis}
\end{tikzpicture}
\end{codeexample}
Please note that this feature does not affect plot marks. I think it looks unfamiliar if plot marks are crossed by axis descriptions.
\end{pgfplotskey}
+
+\begin{key}{/pgf/fpu=\marg{true,false} (initially true)}
+\index{Precision}
+ This key activates or deactivates the floating point unit. If it is disabled (|false|), the core \PGF\ math engine written by Mark Wibrow and Till Tantau will be used for |plot expression|.
+ However, this engine has been written to produce graphics and is not suitable for scientific computing. It is limited to fixed point numbers in the range $\pm 16384.00000$.
+
+ If the |fpu| is enabled (|true|, the initial configuration) the high-precision floating point library of \PGF\ written by Christian Feuersänger will be used. It offers the full range of IEEE double precision computing in \TeX. This FPU is also part of \PGFPlotstable, and it is activated by default for |create col/expr| and all other predefined mathematical methods.
+
+ Use
+\begin{codeexample}[code only]
+\pgfkeys{/pgf/fpu=false}
+\end{codeexample}
+ \noindent in order to de-activate the extended precision. If you prefer using the |fp| (fixed point) package, possibly combined with Mark Wibrows corresponding \PGF\ library, the |fpu| will be deactivated automatically. Please note, however, that |fp| has a smaller data range (about $\pm 10^{17}$) and may be slower.
+\end{key}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
index 38e4a884194..d915a4f8a1a 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
@@ -32,7 +32,7 @@
\end{codeexample}
\message{ok, passed.}%
-\PGFPlots\ relies completely on \TeX\ to do all typesetting. In uses the front-end-layer and basic layer of \PGF\ to perform all drawing operations. For complicated plots, this may take some time, and you may want to read section~\ref{sec:pgfplots:importexport} for how to write single figures to external graphics files. Externalization is the best way to reduce typesetting time.
+\PGFPlots\ relies completely on \TeX\ to do all typesetting. It uses the front-end-layer and basic layer of \PGF\ to perform all drawing operations. For complicated plots, this may take some time, and you may want to read section~\ref{sec:pgfplots:importexport} for how to write single figures to external graphics files. Externalization is the best way to reduce typesetting time.
However, for large scale plots with a lot of points, limitations of \TeX's capacities are reached easily.
@@ -72,4 +72,4 @@ stack_size = n
\end{codeexample}
The log--file usually contains information about the parameter which needs to be enlarged.
\end{enumerate}
-Unfortunately, \TeX\ does not allow arbirtrary memory limits, there is an upper bound hard coded in the executables.
+Unfortunately, \TeX\ does not allow arbitrary memory limits, there is an upper bound hard coded in the executables.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
index 36fce7596e1..bc136eeb2f2 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
@@ -20,10 +20,21 @@
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\input{pgfplots.preamble.tex}
+%\RequirePackage[english,francais]{babel}
%\usetikzlibrary{external}
%\tikzexternalize[prefix=figures/]{pgfplots}
+\title{%
+ Manual for Package \PGFPlots\\
+ {\small Version \pgfplotsversion}\\
+ {\small\href{http://sourceforge.net/projects/pgfplots}{http://sourceforge.net/projects/pgfplots}}}
+
+%\includeonly{pgfplots.reference}
+
+
+\begin{document}
+
\def\plotcoords{%
\addplot coordinates {
(5,8.312e-02) (17,2.547e-02) (49,7.407e-03)
@@ -56,16 +67,6 @@
(1496065,4.670e-05)
};
}%
-
-\title{%
- Manual for Package \PGFPlots\\
- {\small Version \pgfplotsversion}\\
- {\small\href{http://sourceforge.net/projects/pgfplots}{http://sourceforge.net/projects/pgfplots}}}
-
-%\includeonly{pgfplots.reference}
-
-
-\begin{document}
\maketitle
\begin{abstract}%
\PGFPlots\ draws high--quality function plots in normal or logarithmic scaling with a user-friendly interface directly in \TeX. The user supplies axis labels, legend entries and the plot coordinates for one or more plots and \PGFPlots\ applies axis scaling, computes any logarithms and axis ticks and draws the plots, supporting line plots, piecewise constant plots, bar plots and area plots. It is based on Till Tantau's package \PGF/\Tikz.
@@ -76,18 +77,35 @@ This package provides tools to generate plots and labeled axes easily. It draws
It is build completely on \Tikz\ and \PGF\ and may be used as \Tikz\ library.
-\section{Upgrade remarks}
-This release provides a lot of improvements which can be found in all detail in \texttt{ChangeLog} for interested readers. However, some attention is useful for upgrades, which does especially affect style options: although |\tikzstyle| is still supported, you should replace any occurance of |\tikzstyle| with |\pgfplotsset{|\meta{style name}|/.style={|\meta{key-value-list}|}}| or the associated |.append style| variant. See section~\ref{sec:styles} for more detail.
+\section[About PGFPlots: Preliminaries]{About {\normalfont\PGFPlots}: Preliminaries}
+This section contains information about upgrades, the team, the installation (in case you need to do it manually) and troubleshooting. You may skip it completely except for the upgrade remarks.
+
+\subsection{Upgrade remarks}
+This release provides a lot of improvements which can be found in all detail in \texttt{ChangeLog} for interested readers. However, some attention is useful with respect to the following changes:
+\begin{enumerate}
+ \item Due to a small math bug in \PGF\ $2.00$: you \emph{can't} write `|-x^2|' -- use `|0-x^2|' instead. The same holds for
+ `|exp(-x^2)|' -- use `|exp(0-x^2)|' instead.
+
+ \item Starting with \PGFPlots\ $1.1$, |\tizkstyle| should \emph{no longer be used} to set \PGFPlots\ options.
+
+ Although |\tikzstyle| is still supported for some older \PGFPlots\ options, you should replace any occurance of |\tikzstyle| with |\pgfplotsset{|\meta{style name}|/.style={|\meta{key-value-list}|}}| or the associated |.append style| variant. See section~\ref{sec:styles} for more detail.
+\end{enumerate}
+I apologize for any inconvenience caused by these changes.
-\section{Acknowledgements}
+This library requires at least \PGF\ version $2.00$. At the time of this writing, many \TeX-distributions still contain the older \PGF\ version $1.18$, so it may be necessary to install a recent \PGF\ prior to using \PGFPlots.
+
+\subsection{The Team}
+\PGFPlots\ has been written by Christian Feuersänger and Pascal Wolkotte as a spare time project. We hope it is useful and provides valueable plots.
+
+\subsection{Acknowledgements}
I thank God for all hours of enjoyed programming. I thank Pascal Wolkotte, author of package |pgfgraph|, who joined development and contributed code for axis lines and tick alignment. Furthermore, I thank Dr.~Schweitzer for many fruitful discussions and Dr.~Meine for his ideas and suggestions.
Last but not least, I thank Till Tantau and Mark Wibrow for their excellent graphics (and more) package \PGF\ and \Tikz\ which is the base of \PGFPlots.
-
\include{pgfplots.install}%
\include{pgfplots.intro}%
\include{pgfplots.reference}%
+\include{pgfplots.libs}%
\include{pgfplots.resources}%
\include{pgfplots.importexport}%
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsJS.djs b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsJS.djs
new file mode 100644
index 00000000000..47c30e2e85f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsJS.djs
@@ -0,0 +1,373 @@
+\begingroup
+\obeyspaces\obeylines\global\let^^M=\jsR%
+\catcode`\"=12%
+\gdef\dljspgfplotsJSiii{%
+/*********************************************************************************
+ * function sprintf() - written by Kevin van Zonneveld as part of the php to javascript
+ * conversion project.
+ *
+ * More info at: http://kevin.vanzonneveld.net/techblog/article/phpjs_licensing/
+ *
+ * This is version: 1.33
+ * php.js is copyright 2008 Kevin van Zonneveld.
+ *
+ * Portions copyright Michael White (http://crestidg.com), _argos, Jonas
+ * Raoni Soares Silva (http://www.jsfromhell.com), Legaev Andrey, Ates Goral
+ * (http://magnetiq.com), Philip Peterson, Martijn Wieringa, Webtoolkit.info
+ * (http://www.webtoolkit.info/), Carlos R. L. Rodrigues
+ * (http://www.jsfromhell.com), Ash Searle (http://hexmen.com/blog/),
+ * Erkekjetter, GeekFG (http://geekfg.blogspot.com), Johnny Mast
+ * (http://www.phpvrouwen.nl), marrtins, Alfonso Jimenez
+ * (http://www.alfonsojimenez.com), Aman Gupta, Arpad Ray
+ * (mailto:arpad@php.net), Karol Kowalski, Mirek Slugen, Thunder.m, Tyler
+ * Akins (http://rumkin.com), d3x, mdsjack (http://www.mdsjack.bo.it), Alex,
+ * Alexander Ermolaev (http://snippets.dzone.com/user/AlexanderErmolaev),
+ * Allan Jensen (http://www.winternet.no), Andrea Giammarchi
+ * (http://webreflection.blogspot.com), Arno, Bayron Guevara, Ben Bryan,
+ * Benjamin Lupton, Brad Touesnard, Brett Zamir, Cagri Ekin, Cord, David,
+ * David James, DxGx, FGFEmperor, Felix Geisendoerfer
+ * (http://www.debuggable.com/felix), FremyCompany, Gabriel Paderni, Howard
+ * Yeend, J A R, Leslie Hoare, Lincoln Ramsay, Luke Godfrey, MeEtc
+ * (http://yass.meetcweb.com), Mick@el, Nathan, Nick Callen, Ozh, Pedro Tainha
+ * (http://www.pedrotainha.com), Peter-Paul Koch
+ * (http://www.quirksmode.org/js/beat.html), Philippe Baumann, Sakimori,
+ * Sanjoy Roy, Simon Willison (http://simonwillison.net), Steve Clay, Steve
+ * Hilder, Steven Levithan (http://blog.stevenlevithan.com), T0bsn, Thiago
+ * Mata (http://thiagomata.blog.com), Tim Wiel, XoraX (http://www.xorax.info),
+ * Yannoo, baris ozdil, booeyOH, djmix, dptr1988, duncan, echo is bad, gabriel
+ * paderni, ger, gorthaur, jakes, john (http://www.jd-tech.net), kenneth,
+ * loonquawl, penutbutterjelly, stensi
+ *
+ * Dual licensed under the MIT (MIT-LICENSE.txt)
+ * and GPL (GPL-LICENSE.txt) licenses.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL KEVIN VAN ZONNEVELD BE LIABLE FOR ANY CLAIM, DAMAGES
+ * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+// ATTENTION: this method has been masked such that special characters of TeX and javascript
+// don't produce problems.
+function sprintf( ) {
+ // Return a formatted string
+ //
+ // + discuss at: http://kevin.vanzonneveld.net/techblog/article/javascript_equivalent_for_phps_sprintf/
+ // + version: 804.1712
+ // + original by: Ash Searle (http://hexmen.com/blog/)
+ // + namespaced by: Michael White (http://crestidg.com)
+ // * example 1: sprintf("\pgfplotsPERCENT01.2f", 123.1);
+ // * returns 1: 123.10
+
+ var regex = /\pgfplotsPERCENT\pgfplotsPERCENT\pgfplotsVERTBAR\pgfplotsPERCENT(\d+\$)?([-+\pgfplotsHASH0 ]*)(\*\d+\$\pgfplotsVERTBAR\*\pgfplotsVERTBAR\d+)?(\.(\*\d+\$\pgfplotsVERTBAR\*\pgfplotsVERTBAR\d+))?([scboxXuidfegEG])/g;
+ var a = arguments, i = 0, format = a[i++];
+
+ // pad()
+ var pad = function(str, len, chr, leftJustify) {
+ var padding = (str.length >= len) ? '' : Array(1 + len - str.length >>> 0).join(chr);
+ return leftJustify ? str + padding : padding + str;
+ };
+
+ // justify()
+ var justify = function(value, prefix, leftJustify, minWidth, zeroPad) {
+ var diff = minWidth - value.length;
+ if (diff > 0) {
+ if (leftJustify \pgfplotsVERTBAR\pgfplotsVERTBAR !zeroPad) {
+ value = pad(value, minWidth, ' ', leftJustify);
+ } else {
+ value = value.slice(0, prefix.length) + pad('', diff, '0', true) + value.slice(prefix.length);
+ }
+ }
+ return value;
+ };
+
+ // formatBaseX()
+ var formatBaseX = function(value, base, prefix, leftJustify, minWidth, precision, zeroPad) {
+ // Note: casts negative numbers to positive ones
+ var number = value >>> 0;
+ prefix = prefix && number && {'2': '0b', '8': '0', '16': '0x'}[base] \pgfplotsVERTBAR\pgfplotsVERTBAR '';
+ value = prefix + pad(number.toString(base), precision \pgfplotsVERTBAR\pgfplotsVERTBAR 0, '0', false);
+ return justify(value, prefix, leftJustify, minWidth, zeroPad);
+ };
+
+ // formatString()
+ var formatString = function(value, leftJustify, minWidth, precision, zeroPad) {
+ if (precision != null) {
+ value = value.slice(0, precision);
+ }
+ return justify(value, '', leftJustify, minWidth, zeroPad);
+ };
+
+ // finalFormat()
+ var doFormat = function(substring, valueIndex, flags, minWidth, _, precision, type) {
+ if (substring == '\pgfplotsPERCENT\pgfplotsPERCENT') return '\pgfplotsPERCENT';
+
+ // parse flags
+ var leftJustify = false, positivePrefix = '', zeroPad = false, prefixBaseX = false;
+ for (var j = 0; flags && j < flags.length; j++) switch (flags.charAt(j)) {
+ case ' ': positivePrefix = ' '; break;
+ case '+': positivePrefix = '+'; break;
+ case '-': leftJustify = true; break;
+ case '0': zeroPad = true; break;
+ case '\pgfplotsHASH': prefixBaseX = true; break;
+ }
+
+ // parameters may be null, undefined, empty-string or real valued
+ // we want to ignore null, undefined and empty-string values
+ if (!minWidth) {
+ minWidth = 0;
+ } else if (minWidth == '*') {
+ minWidth = +a[i++];
+ } else if (minWidth.charAt(0) == '*') {
+ minWidth = +a[minWidth.slice(1, -1)];
+ } else {
+ minWidth = +minWidth;
+ }
+
+ // Note: undocumented perl feature:
+ if (minWidth < 0) {
+ minWidth = -minWidth;
+ leftJustify = true;
+ }
+
+ if (!isFinite(minWidth)) {
+ throw new Error('sprintf: (minimum-)width must be finite');
+ }
+
+ if (!precision) {
+ precision = 'fFeE'.indexOf(type) > -1 ? 6 : (type == 'd') ? 0 : void(0);
+ } else if (precision == '*') {
+ precision = +a[i++];
+ } else if (precision.charAt(0) == '*') {
+ precision = +a[precision.slice(1, -1)];
+ } else {
+ precision = +precision;
+ }
+
+ // grab value using valueIndex if required?
+ var value = valueIndex ? a[valueIndex.slice(0, -1)] : a[i++];
+
+ switch (type) {
+ case 's': return formatString(String(value), leftJustify, minWidth, precision, zeroPad);
+ case 'c': return formatString(String.fromCharCode(+value), leftJustify, minWidth, precision, zeroPad);
+ case 'b': return formatBaseX(value, 2, prefixBaseX, leftJustify, minWidth, precision, zeroPad);
+ case 'o': return formatBaseX(value, 8, prefixBaseX, leftJustify, minWidth, precision, zeroPad);
+ case 'x': return formatBaseX(value, 16, prefixBaseX, leftJustify, minWidth, precision, zeroPad);
+ case 'X': return formatBaseX(value, 16, prefixBaseX, leftJustify, minWidth, precision, zeroPad).toUpperCase();
+ case 'u': return formatBaseX(value, 10, prefixBaseX, leftJustify, minWidth, precision, zeroPad);
+ case 'i':
+ case 'd': {
+ var number = parseInt(+value);
+ var prefix = number < 0 ? '-' : positivePrefix;
+ value = prefix + pad(String(Math.abs(number)), precision, '0', false);
+ return justify(value, prefix, leftJustify, minWidth, zeroPad);
+ }
+ case 'e':
+ case 'E':
+ case 'f':
+ case 'F':
+ case 'g':
+ case 'G':
+ {
+ var number = +value;
+ var prefix = number < 0 ? '-' : positivePrefix;
+ var method = ['toExponential', 'toFixed', 'toPrecision']['efg'.indexOf(type.toLowerCase())];
+ var textTransform = ['toString', 'toUpperCase']['eEfFgG'.indexOf(type) \pgfplotsPERCENT 2];
+ value = prefix + Math.abs(number)[method](precision);
+ return justify(value, prefix, leftJustify, minWidth, zeroPad)[textTransform]();
+ }
+ default: return substring;
+ }
+ };
+
+ return format.replace(regex, doFormat);
+}
+/*********************************************************************************/
+
+
+var lastMouseX = -1;
+var lastMouseY = -1;
+var posOnMouseDownX = -1;
+var posOnMouseDownY = -1;
+
+// preallocation.
+var tmpArray1 = new Array(2);
+var tmpArray2 = new Array(2);
+
+/**
+ * Takes an already existing TextField, changes its value to \c value and places it at (x,y).
+ * Additional \c displayOpts will be used to format it.
+ */
+function initTextField( x,y, textField, displayOpts, value )
+{
+textField.value = ""+value;
+var R = textField.rect;
+R[0] = x;
+R[1] = y;
+R[2] = R[0] + displayOpts.textSize/2*Math.max( 5,value.length );
+R[3] = R[1] - 1.5*displayOpts.textSize;
+textField.rect = R;
+textField.textFont = displayOpts.textFont;
+textField.textSize = displayOpts.textSize;
+textField.fillColor = displayOpts.fillColor;//["RGB",1,1,.855];
+textField.doNotSpellCheck = true;
+textField.readonly = true;
+if( displayOpts.printable )
+textField.display = display.visible;
+else
+textField.display = display.noPrint;
+}
+
+/**
+ * Changes all required Field values of \c plotRegionField, inserts the proper
+ * value and displays it at the pdf positions (x,y) .
+ *
+ * @param plotRegionField a reference to a Field object.
+ * @param x the x coordinate where the annotation shall be placed and which is used to determine
+ * the annotation text.
+ * @param y the corresponding y coord.
+ * @param axisAnnotObj An object containing axis references.
+ * @param displayOpts An object for display flags.
+ * @param[out] retCoords will be filled with the point in axis coordinates.
+ */
+function placeAnnot( plotRegionField, x,y, textField, axisAnnotObj, displayOpts, retCoords )
+{
+// Get and modify bounding box. The mouse movement is only accurate up to one point
+// (mouseX and mouseY are integers), so the bounding box should be an integer as well.
+var R = plotRegionField.rect;
+R[0] = Math.round(R[0]);
+R[1] = Math.round(R[1]);
+R[2] = Math.round(R[2]);
+R[3] = Math.round(R[3]);
+plotRegionField.rect= R;
+
+var w = R[2] - R[0];
+var h = R[1] - R[3];
+
+// compute position 0 <= mx <= 1, 0<= my <= 1 relative to lower(!) left corner.
+var mx = x - R[0];
+var my = h - (R[1] - y);
+
+var unitx = mx / w;
+var unity = my / h;
+
+var realx = axisAnnotObj.xmin + unitx * (axisAnnotObj.xmax - axisAnnotObj.xmin);
+var realy = axisAnnotObj.ymin + unity * (axisAnnotObj.ymax - axisAnnotObj.ymin);
+
+if( retCoords ) {
+retCoords[0] = realx;
+retCoords[1] = realy;
+}
+
+if( axisAnnotObj.xscale == "log" )
+realx = Math.exp(realx);
+if( axisAnnotObj.yscale == "log" )
+realy = Math.exp(realy);
+
+// console.println( "w = " + w + "; h = " + h );
+// console.println( "mx = " + mx + "; my = " + my );
+// console.println( "unitx = " + unitx + "; unity " + unity );
+
+initTextField( x,y, textField, displayOpts,
+//util.printf( "(\pgfplotsPERCENT.2f,\pgfplotsPERCENT.2f)", realx,realy )
+sprintf( displayOpts.pointFormat, realx,realy) );
+
+}
+
+/**
+ * @param formName the name of the clickable button. It is expected to be as large as the underlying plot.
+ * @param axisAnnotObj an object with the fields
+ * - xmin, xmax
+ * - ymin, ymax
+ * - xscale, yscale
+ * @param displayOpts an object with the fields
+ * - pointFormat an sprintf format string to format the final point coordinates.
+ * The default is "(\pgfplotsPERCENT.2f,\pgfplotsPERCENT.2f)"
+ * - fillColor the fill color for the annotation. Options are
+ * transparent, gray, RGB or CMYK color. Default is
+ * ["RGB",1,1,.855]
+ * - textFont / textSize
+ */
+function processAnnotatedPlot(formName, axisAnnotObj, displayOpts, bMouseUp )
+{
+if( !bMouseUp ) {
+posOnMouseDownX = mouseX;
+posOnMouseDownY = mouseY;
+return;
+}
+var result = this.getField( formName + "-result");
+var result2 = this.getField( formName + "-result2");
+var slope = this.getField( formName + "-slope" );
+if( !result ) {
+console.println( "WARNING: there is no TextField \"" + formName + "-result\" to display results for interactive element \"" + formName + "\"");
+return;
+}
+result2.display = display.hidden;
+slope.display = display.hidden;
+
+// clicking twice onto the same point hides it:
+if( result.display != display.hidden &&
+Math.abs(lastMouseX - mouseX) < 5 &&
+Math.abs(lastMouseY - mouseY) < 5 )
+{
+result.display = display.hidden;
+return;
+}
+lastMouseX = mouseX;
+lastMouseY = mouseY;
+
+var a = this.getField(formName);
+if( ! a ) {
+console.println( "Warning: there is no form named \"" + formName + "\"" );
+return;
+}
+if( Math.abs( lastMouseX - posOnMouseDownX ) > 6 \pgfplotsVERTBAR\pgfplotsVERTBAR
+Math.abs( lastMouseY - posOnMouseDownY ) > 6 )
+{
+// dragging the mouse results in slope computation:
+placeAnnot( a, posOnMouseDownX, posOnMouseDownY, result, axisAnnotObj, displayOpts, tmpArray1 );
+placeAnnot( a, lastMouseX, lastMouseY, result2, axisAnnotObj, displayOpts, tmpArray2 );
+
+var m = ( tmpArray2[1] - tmpArray1[1] ) / ( tmpArray2[0] - tmpArray1[0] );
+var n = tmpArray1[1] - m * tmpArray1[0];
+
+initTextField(
+0.5 * ( lastMouseX + posOnMouseDownX ),
+0.5 * ( lastMouseY + posOnMouseDownY ),
+slope,
+displayOpts,
+sprintf( displayOpts.slopeFormat, m, n ) );
+
+%--------------------------------------------------
+% var lineobj = this.getAnnot( a.page, formName + '-line' );
+% console.println( 'lineobj = ' + lineobj );
+% lineobj.points = [[lastMouseX,lastMouseY],[posOnMouseDownX,posOnMouseDownY]];
+% lineobj.display = display.visible;
+%--------------------------------------------------
+
+} else {
+placeAnnot( a, lastMouseX, lastMouseY, result, axisAnnotObj, displayOpts, null );
+}
+}
+}%
+\endgroup
+\begingroup
+\ccpdftex%
+\input{dljscc.def}%
+\immediate\pdfobj{ << /S /JavaScript /JS (\dljspgfplotsJSiii) >> }
+\xdef\objpgfplotsJSiii{\the\pdflastobj\space0 R}
+\endgroup
+\endinput
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
index 6c0214828ac..28c1fb14eb9 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.dat b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.dat
new file mode 100644
index 00000000000..c6a2c7ca618
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.dat
@@ -0,0 +1,11 @@
+dof error1 postproc1
+4 2.50000000e-01 {}
+16 6.25000000e-02 1.99998
+64 1.56250000e-02 1.99998
+256 3.90625000e-03 1.99998
+1024 9.76562500e-04 1.99998
+4096 2.44140625e-04 1.99998
+16384 6.10351562e-05 1.99998
+65536 1.52587891e-05 1.99998
+262144 3.81469727e-06 1.99998
+1048576 9.53674316e-07 1.99998
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.html b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.html
new file mode 100644
index 00000000000..e68495bbbad
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.html
@@ -0,0 +1,13 @@
+<table>
+<tr><td>level</td><td>dof</td></tr>
+<tr><td>1</td><td>4</td></tr>
+<tr><td>2</td><td>16</td></tr>
+<tr><td>3</td><td>64</td></tr>
+<tr><td>4</td><td>256</td></tr>
+<tr><td>5</td><td>1024</td></tr>
+<tr><td>6</td><td>4096</td></tr>
+<tr><td>7</td><td>16384</td></tr>
+<tr><td>8</td><td>65536</td></tr>
+<tr><td>9</td><td>262144</td></tr>
+<tr><td>10</td><td>1048576</td></tr>
+</table>
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex
index c46056ebe5a..127872722ab 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex
@@ -1 +1,13 @@
-\begin {tabular}{cc}dof&error1\\\pgfutilensuremath {4}&\pgfutilensuremath {0.25}\\\pgfutilensuremath {16}&\pgfutilensuremath {6.25\cdot 10^{-2}}\\\pgfutilensuremath {64}&\pgfutilensuremath {1.56\cdot 10^{-2}}\\\pgfutilensuremath {256}&\pgfutilensuremath {3.91\cdot 10^{-3}}\\\pgfutilensuremath {1{,}024}&\pgfutilensuremath {9.77\cdot 10^{-4}}\\\pgfutilensuremath {4{,}096}&\pgfutilensuremath {2.44\cdot 10^{-4}}\\\pgfutilensuremath {16{,}384}&\pgfutilensuremath {6.1\cdot 10^{-5}}\\\pgfutilensuremath {65{,}536}&\pgfutilensuremath {1.53\cdot 10^{-5}}\\\pgfutilensuremath {2.62\cdot 10^{5}}&\pgfutilensuremath {3.81\cdot 10^{-6}}\\\pgfutilensuremath {1.05\cdot 10^{6}}&\pgfutilensuremath {9.54\cdot 10^{-7}}\\\end {tabular}
+\begin {tabular}{cc}%
+dof&error1\\%
+\pgfutilensuremath {4}&\pgfutilensuremath {0.25}\\%
+\pgfutilensuremath {16}&\pgfutilensuremath {6.25\cdot 10^{-2}}\\%
+\pgfutilensuremath {64}&\pgfutilensuremath {1.56\cdot 10^{-2}}\\%
+\pgfutilensuremath {256}&\pgfutilensuremath {3.91\cdot 10^{-3}}\\%
+\pgfutilensuremath {1{,}024}&\pgfutilensuremath {9.77\cdot 10^{-4}}\\%
+\pgfutilensuremath {4{,}096}&\pgfutilensuremath {2.44\cdot 10^{-4}}\\%
+\pgfutilensuremath {16{,}384}&\pgfutilensuremath {6.1\cdot 10^{-5}}\\%
+\pgfutilensuremath {65{,}536}&\pgfutilensuremath {1.53\cdot 10^{-5}}\\%
+\pgfutilensuremath {2.62\cdot 10^{5}}&\pgfutilensuremath {3.81\cdot 10^{-6}}\\%
+\pgfutilensuremath {1.05\cdot 10^{6}}&\pgfutilensuremath {9.54\cdot 10^{-7}}\\%
+\end {tabular}%
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.mst b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.mst
new file mode 100644
index 00000000000..642be497a04
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.mst
@@ -0,0 +1,17 @@
+headings_flag 1
+heading_prefix "{\\bf ---~"
+heading_suffix "~---}"
+delim_0 "\\dotfill\\indexpageno{"
+delim_1 "\\dotfill\\indexpageno{"
+delim_2 "\\dotfill\\indexpageno{"
+delim_t "}"
+delim_n "}, \\indexpageno{"
+delim_r "} -- \\indexpageno{"
+suffix_2p "}f.{"
+suffix_3p "}ff.{"
+symhead_negative "Symbols"
+symhead_positive "Symbols"
+numhead_negative "Numbers"
+numhead_positive "Numbers"
+quote '+'
+line_max 255
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf
index 420896cd09c..54c36d3054d 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
index f32467d7779..5663043b17c 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
@@ -52,9 +52,10 @@
\section{Introduction}
\PGFPlotstable\ is a lightweight sub-package of \PGFPlots\ which employs its table input methods and the number formatting techniques to convert tab-separated tables into tabulars.
-Its input is a text file containing space separated rows, possibly starting with column names. Its output is a \LaTeX\ tabular\footnote{Please see the remarks in section~\ref{sec:pgfplotstable:context} for plain \TeX\ and Con\TeX t.} which contains selected columns of the text table, rounded to the desired precision, printed in the desired number format (fixed point, integer, scientific etc).
+Its input is a text file containing space separated rows, possibly starting with column names. Its output is a \LaTeX\ tabular\footnote{Please see the remarks in section~\ref{sec:pgfplotstable:context} for plain \TeX\ and Con\TeX t.} which contains selected columns of the text table, rounded to the desired precision, printed in the desired number format (fixed point, integer, scientific etc.).
It is used with
+% NO GALLERY
\begin{codeexample}[code only]
\usepackage{pgfplotstable}
% recommended:
@@ -64,10 +65,29 @@ It is used with
\end{codeexample}
\noindent and requires \PGFPlots\ and \PGF\ $ \ge 2.00$ installed.
-Knowledge of |pgfkeys| is useful for a deeper insight into this package. Please refer to the \PGF\ manual,~\cite[section pgfkeys]{tikz} if you want a deeper insight into |pgfkeys|. Otherwise, simply skip over to the examples provided in this document.
+\begin{command}{\pgfplotstableset\marg{key-value-options}}
+ The user interface of this package is based on key-value-options. They determine what to display, how to format and what to compute.
+
+ Key-value pairs can be set in two ways:
+ \begin{enumerate}
+ \item As default settings for the complete document (or maybe a part of the document), using |\pgfplotstableset|\marg{options}. For example, the document's preamble may contain
+% NO GALLERY
+\begin{codeexample}[code only]
+\pgfplotstableset{fixed zerofill,precision=3}
+\end{codeexample}
+ to configure a precision of $3$ digits after the period, including zeros to get exactly $3$ digits for all fixed point numbers.
+ \item As option which affects just a single table. This is provided as optional argument to the respective table typesetting command, for example |\pgfplotstabletypeset|\oarg{options}\marg{file}.
+ \end{enumerate}
+ Both ways are shown in the examples below.
+
+ Knowledge of |pgfkeys| is useful for a deeper insight into this package, as |.style|, |.append style| etc. are specific to |pgfkeys|. Please refer to the \PGF\ manual,~\cite[section pgfkeys]{tikz} if you want a deeper insight into |pgfkeys|. Otherwise, simply skip over to the examples provided in this document.
+
+ You will find key prefixes |/pgfplots/table/| and |/pgf/number format/|. These prefixes can be skipped if they are used in \PGFPlotstable; they belong to the ``default key path'' of |pgfkeys|.
+\end{command}
-\section{Text table input format}
-\PGFPlotstable\ works with plain text file tables in which entries (``cells'') are separated by a separation character. The initial separation character is ``white space'' which means ``at least one space or tab''. Those tables can have a header line which contains column names and most other columns typically contain numerical data.
+\section{Loading and Displaying data}
+\subsection{Text Table Input Format}
+\PGFPlotstable\ works with plain text file tables in which entries (``cells'') are separated by a separation character. The initial separation character is ``white space'' which means ``at least one space or tab'' (see option |col sep| below). Those tables can have a header line which contains column names and most other columns typically contain numerical data.
\noindent The following listing shows |pgfplotstable.example1.dat| and is used often throughout this documentation.
\begin{codeexample}[code only]
@@ -89,6 +109,75 @@ Lines starting with `|%|' or `|#|' are considered to be comment lines and are ig
There is future support for a second header line which must start with `|$flags |' (the space is obligatory, even if the column separator is \emph{not} space!). Currently, such a line is ignored. It may be used to provide number formatting options like precision and number format.
+\begin{command}{\pgfplotstabletypeset\oarg{optional arguments}\marg{file name or \textbackslash macro}}
+ Loads (or acquires) a table and typesets it using the current configuration of number formats and table options.
+
+ In case the first argument is a file name, the table will be loaded from disk. Otherwise, it is assumed to be an already loaded table (see |\pgfplotstableread| or |\pgfplotstablenew|).
+\begin{codeexample}[]
+\pgfplotstabletypeset{pgfplotstable.example1.dat}
+\end{codeexample}
+
+ \noindent The configuration can be customized with \meta{optional arguments}. Configuration can be done for the complete table or for particular columns (or rows).
+
+\begin{codeexample}[]
+\pgfplotstableset{% global config, for example in the preamble
+ columns/dof/.style={int detect,column type=r,column name=\textsc{Dof}},
+ columns/error1/.style={
+ sci,sci zerofill,sci sep align,precision=1,sci superscript,
+ column name=$e_1$,
+ },
+ columns/error2/.style={
+ sci,sci zerofill,sci sep align,precision=2,sci 10e,
+ column name=$e_2$,
+ },
+ columns/{grad(log(dof),log(error2))}/.style={
+ string replace={0}{}, % erase '0'
+ column name={$\nabla e_2$},
+ dec sep align,
+ },
+ columns/{quot(error1)}/.style={
+ string replace={0}{}, % erase '0'
+ column name={$\frac{e_1^{(n)}}{e_1^{(n-1)}}$}
+ },
+ empty cells with={--}, % replace empty cells with '--'
+ every head row/.style={before row=\toprule,after row=\midrule},
+ every last row/.style={after row=\bottomrule}
+}
+\pgfplotstabletypeset[ % local config, applies only for this table
+ 1000 sep={\,},
+ columns/info/.style={
+ fixed,fixed zerofill,precision=1,showpos,
+ column type=r,
+ }
+]
+{pgfplotstable.example1.dat}
+\end{codeexample}
+\noindent All of these options are explained in the following sections.
+
+Technical note: every opened file will be protocolled into your log file.
+\end{command}
+
+\begin{command}{\pgfplotstabletypesetfile\oarg{optional arguments}\marg{file name}}
+ Loads the table \marg{file name} and typesets it. As of \PGFPlotstable\ 1.2, this command is an alias to |\pgfplotstabletypeset|, that means the first argument can be either a file name or an already loaded table.
+\end{command}
+
+
+\begin{command}{\pgfplotstableread\marg{file name}\marg{\textbackslash macro}}
+ Loads the table \marg{file name} into a \TeX-macro \meta{\textbackslash macro}. This macro can than be used several times.
+\begin{codeexample}[]
+\pgfplotstableread{pgfplotstable.example1.dat}\table
+\pgfplotstabletypeset[columns={dof,error1}]\table
+\hspace{2cm}
+\pgfplotstabletypeset[columns={dof,error2}]\table
+\end{codeexample}
+
+Technical note: every opened file will be protocolled into your log file.
+\end{command}
+
+\begin{command}{\pgfplotstablegetrowsof\marg{file name or \textbackslash loadedtable}}
+ Defines |\pgfmathresult| to be the number of rows in a table. The argument may be either a file name or an already loaded table (the \meta{\textbackslash macro} of |\pgfplotstableread|).
+\end{command}
+
\begin{key}{/pgfplots/table/col sep=\mchoice{space,comma,semicolon,colon,braces} (initially space)}
Specifies the column separation character for table reading. The initial choice, |space| means ``at least one white space''. White spaces are tab stops or spaces (newlines always delimit lines).
@@ -110,7 +199,7 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
\end{codeexample}
Thus, we need to specify |col sep=comma| when we read it.
\begin{codeexample}[]
-\pgfplotstabletypesetfile[col sep=comma]{pgfplotstable.example1.csv}
+\pgfplotstabletypeset[col sep=comma]{pgfplotstable.example1.csv}
\end{codeexample}
You may call |\pgfplotstableset{col sep=comma}| once in your preamble if all your tables use commas as column separator.
@@ -118,36 +207,9 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Furthermore, if you need empty cells in case |col sep=space|, you have to provide |{}| to delimit such a cell since |col sep=space| uses \emph{at least} one white space (consuming all following ones).
- The value |col sep=braces| is special since it actually uses two separation characters. Every single cell entry is delimited by an opening and a closing brace, \marg{entry}, for this choice. Furthermore, any wite spaces (spaces and tabs) between cell entries are \emph{skipped} in case |braces| until the next \marg{entry} is found.
+ The value |col sep=braces| is special since it actually uses two separation characters. Every single cell entry is delimited by an opening and a closing brace, \marg{entry}, for this choice. Furthermore, any white spaces (spaces and tabs) between cell entries are \emph{skipped} in case |braces| until the next \marg{entry} is found.
\end{key}
-\begin{command}{\pgfplotstabletypesetfile\oarg{optional arguments}\marg{file name}}
- This command loads the table file \marg{file name} and typesets it using the current configuration of number formats and table options.
-\begin{codeexample}[]
-\pgfplotstabletypesetfile{pgfplotstable.example1.dat}
-\end{codeexample}
-
- \noindent The configuration can be customized with \meta{optional arguments}.
-
-\begin{codeexample}[]
-\pgfplotstabletypesetfile[sci subscript,sci zerofill]{pgfplotstable.example1.dat}
-\end{codeexample}
-\end{command}
-
-\begin{command}{\pgfplotstableread\marg{file name}\marg{\textbackslash macro}}
- Loads the table \marg{file name} into a \TeX-macro \meta{\textbackslash macro}. This macro can than be used several times.
-\begin{codeexample}[]
-\pgfplotstableread{pgfplotstable.example1.dat}\table
-\pgfplotstabletypeset[columns={dof,error1}]\table
-\hspace{2cm}
-\pgfplotstabletypeset[columns={dof,error2}]\table
-\end{codeexample}
-\end{command}
-
-\begin{command}{\pgfplotstabletypeset\oarg{optional arguments}\marg{\textbackslash macro}}
- Works in the same way as |\pgfplotstabletypesetfile|, but it accepts an already loaded table.
-\end{command}
-
\begin{key}{/pgfplots/table/header=\marg{boolean} (initially true)}
Configures if column names shall be identified during input operations.
@@ -158,13 +220,13 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Use |header=false| to force this last case, i.e. even if the first line contains strings, they won't be recognised as column names.
\end{key}
-\section{Selecting columns}
-\begin{key}{/pgfplots/table/columns=\marg{comma-separated-list} (initially all available ones)}
- Selects particular columns the table. If this option is missing, all available columns will be selected.
+\subsection{Selecting Columns}
+\begin{key}{/pgfplots/table/columns=\marg{comma-separated-list}}
+ Selects particular columns the table. If this option is empty (has not been provided), all available columns will be selected.
- Inside of \marg{comma-separated-list}, column names as they appear in the table's header are expected. If there is no header, simply use column names. If there are column names, the special syntax |[index]|\meta{integer} can be used to select columns by index. The first column has index~$0$.
+ Inside of \marg{comma-separated-list}, column names as they appear in the table's header are expected. If there is no header, simply use column indices. If there are column names, the special syntax |[index]|\meta{integer} can be used to select columns by index. The first column has index~$0$.
\begin{codeexample}[]
-\pgfplotstabletypesetfile[columns={dof,level,[index]4}]{pgfplotstable.example1.dat}
+\pgfplotstabletypeset[columns={dof,level,[index]4}]{pgfplotstable.example1.dat}
\end{codeexample}
\end{key}
@@ -182,7 +244,7 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Sets all options in \marg{key-value-list} exclusively for \marg{column name}.
\begin{codeexample}[]
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
columns/error1/.style={
column name=$L_2$,
sci,sci zerofill,sci subscript,
@@ -200,7 +262,7 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
\end{codeexample}
If your column name contains commas `|,|', slashes `|/|' or equal signs `|=|', you need to enclose the column name in braces.
\begin{codeexample}[narrow]
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
columns={dof,error1,{grad(log(dof),log(error2))}},
columns/error1/.style={
column name=$L_2$,
@@ -229,6 +291,12 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Display column styles override input column styles.
\end{pgfplotstabledisplaycolumnkey}
+\begin{stylekey}{/pgfplots/table/every col no \meta{index}}
+ A style which is identical with |display columns/|\meta{index}: it applies exclusively to the column at position \meta{index} in the output table.
+
+ See |display columns/|\meta{index} for details.
+\end{stylekey}
+
\begin{key}{/pgfplots/table/column type=\marg{tabular column type} (initially c)}
Contains the column type for |tabular|.
@@ -236,7 +304,7 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Use |\pgfplotstableset{column type/.add=|\marg{before}\marg{after}|}| to \emph{modify} a value instead of overwriting it. The |.add| key handler works for other options as well.
\begin{codeexample}[narrow]
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
columns={dof,error1,info},
column type/.add={|}{}% results in '|c'
]
@@ -266,12 +334,12 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
The first argument determines the alignment of the header column.
- The style |dec sep align| actually introduces two new |tabular| columns, namely |r@{}l|. It introduces multicolumns for column names accordingly and handles numbers which do not have a decimal separator.
+ The style |dec sep align| actually introduces two new |tabular| columns\footnote{Unfortunately, \texttt{dec sep align} is currently not very flexible when it comes to column type modifications. In particular, it is not possible to use colored columns or cells in conjunction with \texttt{dec sep align}. The \texttt{\textbackslash rowcolor} command works properly; the color hangover introduced by \texttt{colortbl} is adjusted automatically.}, namely |r@{}l|. It introduces multicolumns for column names accordingly and handles numbers which do not have a decimal separator.
Please note that you need |\usepackage{array}| for this style.
\begin{codeexample}[]
% requires \usepackage{array}
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
columns={dof,error1,error2,info,{grad(log(dof),log(error2))}},
columns/error1/.style={dec sep align},
columns/error2/.style={sci,sci subscript,sci zerofill,dec sep align},
@@ -284,7 +352,7 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Or with comma as decimal separator:
\begin{codeexample}[]
% requires \usepackage{array}
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
use comma,
columns={dof,error1,error2,info,{grad(log(dof),log(error2))}},
columns/error1/.style={dec sep align},
@@ -318,7 +386,7 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
\begin{stylekey}{/pgfplots/table/every first column}
A style which is installed for every first column only.
\begin{codeexample}[narrow]
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
every head row/.style={before row=\hline,after row=\hline\hline},
every last row/.style={after row=\hline},
every first column/.style={
@@ -370,7 +438,7 @@ A style which is installed for every column with even column index (starting wit
\begin{codeexample}[narrow,graphic=white]
% requires \usepackage{colortbl}
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
every even column/.style={
column type/.add={>{\columncolor[gray]{.8}}}{}
}]
@@ -400,7 +468,7 @@ A style which is installed for every column with odd column index (starting with
\end{command}
-\section{Configuring row appearance}
+\subsection{Configuring Row Appearance}
The following styles allow to configure the final table code \emph{after any cell contents have been assigned}.
\begin{key}{/pgfplots/table/before row=\marg{\TeX\ code}}
@@ -446,7 +514,7 @@ The following styles allow to configure the final table code \emph{after any cel
\begin{codeexample}[narrow,graphic=white]
% requires \usepackage{booktabs}
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
every head row/.style={
before row=\toprule,after row=\midrule},
every last row/.style={
@@ -457,7 +525,7 @@ The following styles allow to configure the final table code \emph{after any cel
\begin{codeexample}[narrow,graphic=white]
% requires \usepackage{booktabs,colortbl}
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
every even row/.style={
before row={\rowcolor[gray]{0.9}}},
every head row/.style={
@@ -487,201 +555,11 @@ The following styles allow to configure the final table code \emph{after any cel
A style which is installed for each last \emph{data} row.
\end{stylekey}
-\section{Determining cell contents}
-The conversion from an unprocessed input table to a final typesetted |tabular| code uses three stages for every cell,
-\begin{enumerate}
- \item Preprocessing,
- \item Typesetting,
- \item Postprocessing.
-\end{enumerate}
-The main idea is to select one typesetting algorithm (for example ``format my numbers with the configured number style''). This algorithm usually doesn't need to be changed. Fine tuning can then be done using zero, one or more preprocessors and postprocessors. Preprocessing can mean to select only particular rows or to apply some sort of operation before the typesetting algorithm sees the content. Postprocessing means to apply fine-tuning to the resulting \TeX\ output -- for example to deal with empty cells or to insert unit suffixes or modify fonts for single cells.
-
-\subsection{Typesetting cells}
-\begin{codekey}{/pgfplots/table/assign cell content}
- Allows to redefine the algorithm which assigns cell contents. The argument |#1| is the (unformatted) contents of the input table.
-
- The resulting output needs to be written to |/pgfplots/table/@cell content|.
-
- Please note that you may need special attention for |#1=|\marg{}, i.e. the empty string. This may happen if a column has less rows than the first column. \PGFPlotstable\ will balance columns automatically in this case, inserting enough empty cells to match the number of rows of the first column.
-
- Please note further that if any column has more entries than the first column, these entries will be skipped and a warning message will be issued into the log file.
-
- This key is evaluated inside of a local \TeX\ group, so any local macro assignments will be cleared afterwards.
-\end{codekey}
-
-\begin{key}{/pgfplots/table/assign cell content as number}
- This here is the default implementation of |assign cell contents|.
-
- It invokes |\pgfmathprintnumberto| and writes the result into |@cell content|.
-\end{key}
-
-\begin{stylekey}{/pgfplots/table/string type}
- A style which redefines |assign cell contents| to simply return the ``raw'' input data, that means as text column. This assumes input tables with valid \LaTeX\ content (verbatim printing is not supported).
-\end{stylekey}
-
-
-\subsection{Preprocessing cells}
-\begin{codekey}{/pgfplots/table/preproc cell content}
- Allows to \emph{modify} the contents of cells \emph{before} |assign cell contents| is called.
-
- The semantics is as follows: before the preprocessor, |@cell content| contains the raw input data (or, maybe, the result of another preprocessor call). After the preprocessor, |@cell content| is filled with a -- possibly modified -- value. The resulting value is then used as input to |assign cell contents|.
-
- In the default settings, |assign cell contents| expects numerical input. So, the preprocessor is expected to produce numerical output.
-
- It is possible to provide multiple preprocessor directives using |.append code| or |.append style| key handlers.
-
- In case you don't want (or need) stackable preprocessors, you can also use `|#1|' to get the raw input datum as it is found in the file.
-\end{codekey}
-
-\begin{stylekey}{/pgfplots/table/multiply -1}
- Appends code to current |preproc cell content| value which multiplies every cell with $-1$.
-\begin{codeexample}[]
-\pgfplotstableset{
- columns={dof,error2,slopes2},
- columns/error2/.style={sci,sci zerofill},
- columns/slopes2/.style={dec sep align,empty cells with={\ensuremath{-}}},
- create on use/slopes2/.style=
- {create col/gradient loglog={dof}{error2}}}
-
-\pgfplotstabletypesetfile{pgfplotstable.example1.dat}
-
-\pgfplotstabletypesetfile[columns/slopes2/.append style={multiply -1}]
- {pgfplotstable.example1.dat}
-\end{codeexample}
-\end{stylekey}
-
-\begin{codekey}{/pgfplots/table/row predicate}
- A boolean predicate which allows to select particular rows of the input table. The argument |#1| contains the current row's index (starting with~$0$, not counting comment lines or column names).
-
- The return value is assigned to the \TeX-if |\ifpgfplotstableuserow|. If the boolean is not changed, the return value is true.
-\begin{codeexample}[narrow]
-% requires \usepackage{booktabs}
-\pgfplotstabletypesetfile[
- every head row/.style={
- before row=\toprule,after row=\midrule},
- every last row/.style={
- after row=\bottomrule},
- row predicate/.code={%
- \ifnum#1>4\relax
- \ifnum#1<8\relax
- \pgfplotstableuserowfalse
- \fi
- \fi}
-]
- {pgfplotstable.example1.dat}
-\end{codeexample}
- Please note that |row predicate| is applied \emph{before} any other option which affects row appearance. It is evaluated before |assign cell contents|. For example, the even/odd row styles refer to those rows for which the predicate returns |true|. In fact, you can use |row predicate| to truncate the complete table before it as actually processed.
-
- During |row predicate|, the macro |\pgfplotstablerows| contains the total number of \emph{input} rows.
-
- Furthermore, |row predicate| applies only to the typeset routines, not the read methods. If you want to plot only selected table entries with |\addplot table|, use the \PGFPlots\ coordinate filter options.
-\end{codekey}
-
-\begin{stylekey}{/pgfplots/table/skip rows between index=\marg{begin}\marg{end}}
- A style which appends an |row predicate| which discards selected rows. The selection is done by index where indexing starts with~$0$. Every row with index $\meta{begin} \le i < \meta{end}$ will be skipped.
-\begin{codeexample}[narrow]
-% requires \usepackage{booktabs}
-\pgfplotstabletypesetfile[
- every head row/.style={
- before row=\toprule,after row=\midrule},
- every last row/.style={
- after row=\bottomrule},
- skip rows between index={2}{4},
- skip rows between index={7}{9}
-]
- {pgfplotstable.example1.dat}
-\end{codeexample}
-\end{stylekey}
-
-\begin{stylekey}{/pgfplots/table/select equal part entry of=\marg{part no}\marg{part count}}
- A style which overwrites |row predicate| with a subset selection predicate. The idea is to split the current column into \marg{part count} equally sized parts and select only \marg{part no}.
-
- This can be used to simulate multicolumn tables.
-\begin{codeexample}[]
-% requires \usepackage{booktabs}
-\pgfplotstableset{
- every head row/.style={before row=\toprule,after row=\midrule},
- every last row/.style={after row=\bottomrule}}
-
-\pgfplotstabletypesetfile[string type]{pgfplotstable.example2.dat}
-
-\pgfplotstabletypesetfile[
- display columns/0/.style={select equal part entry of={0}{2},string type},
- display columns/1/.style={select equal part entry of={0}{2},string type},
- display columns/2/.style={select equal part entry of={1}{2},string type},
- display columns/3/.style={select equal part entry of={1}{2},string type},
- columns={A,B,A,B}
-]
- {pgfplotstable.example2.dat}
-\end{codeexample}
- The example above shows the original file as-is on the left side. The right side shows columns A,B,A,B~-- but only half of the elements are shown, selected by indices \#0 or \#1 of \#2. The parts are equally large, up to a remainder.
-
- If the available number of rows is not dividable by \marg{part count}, the remaining entries are distributed equally among the first parts.
+\begin{stylekey}{/pgfplots/table/every row no \meta{index}}
+ A style which is installed for the row with index \meta{index}.
\end{stylekey}
-
-\subsection{Postprocessing cells}
-\begin{codekey}{/pgfplots/table/postproc cell content}
- Allows to \emph{modify} assigned cell content \emph{after} it has been assigned, possibly content-dependend. Ideas could be to draw negative numbers in red, typeset single entries in bold face or insert replacement text.
-
- This key is evaluated \emph{after} |assign cell content|. Its semantics is to modify an existing |@cell content| value.
-
- There may be more than one |postproc cell content| command, if you use |.append code| or |.append style| to define them:
-\begin{codeexample}[]
-% requires \usepackage{eurosym}
-\pgfplotstabletypesetfile[
- column type=r,
- columns={dof,info},
- columns/info/.style={
- postproc cell content/.append style={
- /pgfplots/table/@cell content/.add={$\bf}{$}},
- postproc cell content/.append style={
- /pgfplots/table/@cell content/.add={}{\EUR{}}}
- }]
- {pgfplotstable.example1.dat}
-\end{codeexample}
- The code above modifies |@cell content| successively. First, ``|$\bf ... $|'' is inserted, then ``|...\EUR|''. It should be noted that |pgfkeys| handles |.style| and |.code| in (quasi) the same way -- both are simple code keys and can be used as such. You can combine both with |.append style| and |.append code|. Please refer to~\cite[section about pgfkeys]{tikz} for details.
-
- As in |assign cell contents|, the code can evaluate helper macros like |\pgfplotstablerow| to change only particular entries. Furthermore, the argument ``|#1|'' expands to the \emph{unformatted} input argument which was found in the input table. This allows complete context based formatting options. Please remember that empty strings may appear due to column balancing -- introduce special treatment if necessary.
-
- There is one special case which occurs if |@cell content| itsself contains the cell separation character `|&|'. In this case, |postproc cell contents| is invoked \emph{separately} for each part before and after the ampersand and the ampersand is inserted afterwards. This allows compatibility with special styles which create artificial columns in the output (which is allowed, see |dec sep align|). To allow separate treatment of each part, you can use the macro |\pgfplotstablepartno|. It is defined only during the evaluation of |postproc cell content| and it evaluates to the current part index (starting with~$0$). If there is no ampersand in your text, the value will always be~$0$.
-
- This key is evaluated inside of a local \TeX\ group, so any local macro assignments will be cleared afterwards.
-
- The following example can be used to insert a dash, $-$, in a slope column:
-\begin{codeexample}[]
-\pgfplotstableset{
- create on use/slopes1/.style=
- {create col/gradient loglog={dof}{error1}}}
-
-\pgfplotstabletypesetfile[
- columns={dof,error1,slopes1},
- columns/error1/.style={sci,sci zerofill},
- columns/slopes1/.style={
- postproc cell content/.append code={%
- \ifnum\pgfplotstablerow=0
- \pgfkeyssetvalue{/pgfplots/table/@cell content}{\ensuremath{-}}%
- \fi
- }%
- }]
- {pgfplotstable.example1.dat}
-\end{codeexample}
-Since this may be useful in a more general context, it is available as |empty cells with| style.
-\end{codekey}
-
-\begin{stylekey}{/pgfplots/table/empty cells with=\marg{replacement}}
- Appends code to |postproc cell content| which replaces any empty cell with \marg{replacement}.
-
- If |dec sep align| is active, the replacement will be inserted only for the part before the decimal separator.
-\end{stylekey}
-
-\begin{stylekey}{/pgfplots/table/set content=\marg{content}}
- A style which redefines |postproc cell contents| to always return the value \marg{content}.
-\end{stylekey}
-
-
-
-\section{Customizing and getting the tabular code}
+\subsection{Customizing and Getting the Tabular Code}
\begin{stylekey}{/pgfplots/table/every table=\marg{file name}}
A style which is installed at the beginning of every |\pgfplotstabletypeset| command.
@@ -695,30 +573,93 @@ Since this may be useful in a more general context, it is available as |empty ce
\begin{key}{/pgfplots/table/begin table=\marg{code} (initially \textbackslash begin\{tabular\})}
Contains \marg{code} which is generated as table start.
\end{key}
+
+\begin{codekey}{/pgfplots/table/typeset cell}
+ A code key which assigns |/pgfplots/table/@cell content| to the final output of the current cell.
+
+ The first argument, |#1|, is the final cell's value. After this macro, the value of |@cell content| will be written to the output.
+
+ The default implementation is
+\begin{codeexample}[code only]
+\ifnum\pgfplotstablecol=\pgfplotstablecols
+ \pgfkeyssetvalue{/pgfplots/table/cell content}{#1\\}%
+\else
+ \pgfkeyssetvalue{/pgfplots/table/cell content}{#1&}%
+\fi
+\end{codeexample}
+ \paragraph{Attention:} The value of |\pgfplotstablecol| is now in the range $1,\dotsc,n$ where $n=$ |\pgfplotstablecols|. This simplifies checks whether we have the last column.
+\end{codekey}
+
\begin{key}{/pgfplots/table/end table=\marg{code} (initially \textbackslash end\{tabular\})}
Contains \marg{code} which is generated as table end.
\end{key}
\begin{key}{/pgfplots/table/outfile=\marg{file name} (initially empty)}
+\label{page:outfile}
Writes the generated tabular code into \marg{file name}. It can then be used with |\input|\marg{file name}, \PGFPlotstable\ is no longer required since it contains a completely normal |tabular|.
\begin{codeexample}[]
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
columns={dof,error1},
outfile=pgfplotstable.example1.out.tex]
{pgfplotstable.example1.dat}
\end{codeexample}
and |pgfplotstable.example1.out.tex| contains
-\lstdefineformat{inp}{\\\\=\string\newline}%
-\lstinputlisting[basicstyle=\ttfamily\footnotesize,format=inp]{pgfplotstable.example1.out.tex}
+%\lstdefineformat{inp}{\\\\=\string\newline}%
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{pgfplotstable.example1.out.tex}
The command |\pgfutilensuremath| checks whether math mode is active and switches to math mode if necessary\footnote{Please note that \lstinline{\\pgfutilensuremath} needs to be replaced by \lstinline{\\ensuremath} if you want to use the output file independent of \PGF. That can be done by \lstinline{\\let\\pgfutilensuremath=\\ensuremath} which enables the \LaTeX-command \lstinline{\\ensuremath}.}.
\end{key}
+\begin{key}{/pgfplots/table/include outfiles=\marg{boolean} (initially false)}
+ If enabled, any already existing outfile will be |\input| instead of overwritten.
+\begin{codeexample}[code only]
+\pgfplotstableset{include outfiles} % for example in the document's preamble
+\end{codeexample}
+ This allows to place any corrections manually into generated output files.
+\end{key}
+\begin{key}{/pgfplots/table/force remake=\marg{boolean} (initially false)}
+ If enabled, the effect of |include outfiles| is disabled. As all key settings only last until the next brace (or |\end|\meta{}), this key can be used to re-generate some output files while others are still included.
+\end{key}
+
+\begin{key}{/pgfplots/table/write to macro=\marg{\textbackslash macroname}}
+ If the value of |write to macro| is not empty, the completely generated (tabular) code will be written into the macro \marg{\textbackslash macroname}.
+\end{key}
+
+\begin{key}{/pgfplots/table/skip coltypes=\mchoice{true,false} (initially false)}
+ Allows to skip the \marg{coltypes} in |\begin{tabular}|\marg{coltypes}. This allows simplifications for other table types which don't have \LaTeX's table format.
+\end{key}
+
+\begin{key}{/pgfplots/table/typeset=\mchoice{true,false} (initially true)}
+ A boolean which disables the final typesetting stage. Use |typeset=false| in conjunction with |write to macro| if only the generated code is of interest and \TeX\ should not attempt to produce any content in the output |pdf|.
+\end{key}
+
\begin{key}{/pgfplots/table/debug=\marg{boolean} (initially false)}
If enabled, will write every final tabular code to your log file.
\end{key}
-\section{Defining column types for \texttt{tabular}}
+\begin{key}{/pgfplots/table/TeX comment=\marg{comment sign} (initially \%)}
+ The comment sign which is inserted into outfiles to suppress trailing white spaces.
+\end{key}
+
+\noindent As last example, we use \PGFPlotstable\ to write an |.html| (without number formatting, however):
+\begin{codeexample}[width=8cm]
+\pgfplotstabletypeset[
+ begin table={<table>}, end table={</table>},
+ typeset cell/.style={
+ /pgfplots/table/@cell content={<td>#1</td>}
+ },
+ before row=<tr>,after row=</tr>,
+ skip coltypes, typeset=false, string type,
+ TeX comment=,
+ columns={level,dof},
+ outfile=pgfplotstable.example1.out.html,
+]{pgfplotstable.example1.dat}
+\lstinputlisting
+ [basicstyle=\ttfamily\footnotesize]
+ {pgfplotstable.example1.out.html}
+\end{codeexample}
+
+\subsection{Defining Column Types for \texttt{tabular}}
Besides input of text files, it is sometimes desireable to define column types for existing \texttt{tabular} environments.
\begin{command}{\newcolumntype\marg{letter}\oarg{number of arguments}$>$\marg{before column}\meta{column type}$<$\marg{after column}}
@@ -777,9 +718,9 @@ Now, the environment |pgfplotstablecoltype| can be used in \marg{before column}
\end{codeexample}
\end{command}
-\section{Number formatting options}
+\subsection{Number Formatting Options}
\label{sec:number:printing}%
-The following extract of \cite{tikz} explains how to configure number formats.
+The following extract of \cite{tikz} explains how to configure number formats. The common option prefix |/pgf/number format| can be omitted; it will be recognised automatically.
\begin{command}{\pgfmathprintnumber\marg{x}}
Generates pretty-printed output for the (real) number \marg{x}. The input number \marg{x} is parsed using |\pgfmathfloatparsenumber| which allows arbitrary precision.
@@ -906,7 +847,7 @@ Truncates every number to integers (discards any digit after the period).
Sets the desired rounding precision for any display operation. For scientific format, this affects the mantisse.
\end{key}
-\subsection{Changing display styles}%
+\subsubsection{Changing Number Format Display Styles}%
\label{sec:number:styles}%
You can change the way how numbers are displayed. For example, if you use the `\texttt{fixed}' style, the input number is rounded to the desired precision and the current fixed point display style is used to typeset the number. The same is applied to any other format: first, rounding routines are used to get the correct digits, afterwards a display style generates proper \TeX-code.
@@ -968,6 +909,33 @@ The last example employs commas and disables the default comma-spacing.
Just another name for |set thousands separator|.
\end{key}
+\begin{key}{/pgf/number format/min exponent for 1000 sep=\marg{number} (initially 0)}
+ Defines the smalles exponent in scientific notation which is required to draw thousand separators. The exponent is the number of digits minus one, so $\meta{number}=4$ will use thousand separators starting with $1e4 = 10000$.
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ int detect,
+ 1000 sep={\,},
+ min exponent for 1000 sep=0}
+\pgfmathprintnumber{5000}; \pgfmathprintnumber{1000000}
+\end{codeexample}
+
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ int detect,
+ 1000 sep={\,},
+ min exponent for 1000 sep=4}
+\pgfmathprintnumber{1000}; \pgfmathprintnumber{5000}
+\end{codeexample}
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ int detect,
+ 1000 sep={\,},
+ min exponent for 1000 sep=4}
+\pgfmathprintnumber{10000}; \pgfmathprintnumber{1000000}
+\end{codeexample}
+\noindent A value of |0| disables this feature (negative values are ignored).
+\end{key}
+
\begin{key}{/pgf/number format/use period}
A predefined style which installs periods `\texttt{.}' as decimal separators and commas `\texttt{,}' as thousands separators. This style is the default.
@@ -1075,6 +1043,15 @@ Typesets the exponent as subscript for any number displayed in scientific format
\end{codeexample}
\end{key}
+\begin{key}{/pgf/number format/sci superscript}
+Typesets the exponent as superscript for any number displayed in scientific format. This style requires very few space.
+
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,sci superscript}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+\end{key}
+
\begin{key}{/pgf/number format/@dec sep mark=\marg{text}}
Will be placed right before the place where a decimal separator belongs to. However, \marg{text} will be inserted even if there is no decimal separator. It is intented as place-holder for auxiliary routines to find alignment positions.
@@ -1093,15 +1070,356 @@ Typesets the exponent as subscript for any number displayed in scientific format
The initial setting installs a |\pgfutilensuremath| around each final number to change to math mode if necessary. Use |assume math mode=true| if you know that math mode is active and you don't want |\pgfutilensuremath|.
\end{key}
-\section{Changing tables}
-After tables have been loaded from disk, it is possible to change their contents. The methods are limited up to now and they reflect mostly what I needed in my applications. Nevertheless, the approaches are quite general and can be customized.
+
+
+\section{Fine Tuning of Loaded Data}
+The conversion from an unprocessed input table to a final typesetted |tabular| code uses four stages for every cell,
+\begin{enumerate}
+ \item Loading the table,
+ \item Preprocessing,
+ \item Typesetting,
+ \item Postprocessing.
+\end{enumerate}
+The main idea is to select one typesetting algorithm (for example ``format my numbers with the configured number style''). This algorithm usually doesn't need to be changed. Fine tuning can then be done using zero, one or more preprocessors and postprocessors. Preprocessing can mean to select only particular rows or to apply some sort of operation before the typesetting algorithm sees the content. Postprocessing means to apply fine-tuning to the resulting \TeX\ output -- for example to deal with empty cells or to insert unit suffixes or modify fonts for single cells.
+
+\subsection{Loading the table}
+This first step to typeset a table involves the obvious input operations. Furthermore, the ``new column creation'' operations explained in section~\ref{pgfplotstable:createcol} are processed at this time. The table data is read (or acquired) as already explained earlier in this manual. Then, if columns are missing, column alias and |create on use| specifications will be processed as part of the loading procedure. See section~\ref{pgfplotstable:createcol} for details about column creation.
+
+\subsection{Typesetting Cell Content}
+Typesetting cells means to take their value and ``do something''. In many cases, this involves number formatting routines. For example, the ``raw'' input data |12.56| might become |1.235| |\cdot| |10^1|. The result of this stage is no longer useful for content-based computations. The typesetting step follows the preprocessing step.
+
+\begin{codekey}{/pgfplots/table/assign cell content}
+ Allows to redefine the algorithm which assigns cell contents. The argument |#1| is the (unformatted) contents of the input table.
+
+ The resulting output needs to be written to |/pgfplots/table/@cell content|.
+
+ Please note that you may need special attention for |#1=|\marg{}, i.e. the empty string. This may happen if a column has less rows than the first column. \PGFPlotstable\ will balance columns automatically in this case, inserting enough empty cells to match the number of rows of the first column.
+
+ Please note further that if any column has more entries than the first column, these entries will be skipped and a warning message will be issued into the log file.
+
+ This key is evaluated inside of a local \TeX\ group, so any local macro assignments will be cleared afterwards.
+\end{codekey}
+
+\begin{key}{/pgfplots/table/assign cell content as number}
+ This here is the default implementation of |assign cell contents|.
+
+ It invokes |\pgfmathprintnumberto| and writes the result into |@cell content|.
+\end{key}
+
+\begin{stylekey}{/pgfplots/table/string type}
+ A style which redefines |assign cell contents| to simply return the ``raw'' input data, that means as text column. This assumes input tables with valid \LaTeX\ content (verbatim printing is not supported).
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/date type=\marg{date format}}% (initially \year-\month-\day)}
+ A style which expects ISO dates of the form |YYYY-MM-DD| in each cell and produces pretty-printed strings on output. The output format is given as \marg{date format}. Inside of \marg{date format}, several macros which are explained below can be used.
+\begin{codeexample}[]
+% Requires
+% \usepackage{pgfcalendar}
+\pgfplotstableset{columns={date,account1}}
+
+\pgfplotstabletypeset[
+ columns/date/.style={string type}
+]{plotdata/accounts.dat}
+\hspace{1cm}
+\pgfplotstabletypeset[
+ columns/date/.style={date type={\monthname\ \year}}
+]{plotdata/accounts.dat}
+\end{codeexample}
+ This style \textbf{requires} to load the \PGF\ \textbf{calendar package}:
+\begin{codeexample}[code only]
+\usepackage{pgfcalendar}
+\end{codeexample}
+\end{stylekey}
+
+\begin{command}{\year}
+ Inside of \marg{date format}, this macro expands to the year as number (like |2008|).
+\end{command}
+\begin{command}{\month}
+ Inside of \marg{date format}, this macro expands to the month as number, starting with~$1$ (like |1|).
+\end{command}
+\begin{command}{\monthname}
+ Inside of \marg{date format}, this macro expands to the month's name as set in the current language (like |January|).
+ See below for how to change the language.
+\end{command}
+\begin{command}{\monthshortname}
+ Inside of \marg{date format}, this macro expands to the month's short name as set in the current language (like |Jan|).
+ See below for how to change the language.
+\end{command}
+\begin{command}{\day}
+ Inside of \marg{date format}, this macro expands to the day as number (like |31|).
+\end{command}
+\begin{command}{\weekday}
+ Inside of \marg{date format}, this macro expands to the weekday number ($0$ for Monday, $1$ for Tuesday etc.).
+\end{command}
+\begin{command}{\weekdayname}
+ Inside of \marg{date format}, this macro expands to the weekday's name in the current language (like |Wednesday|).
+ See below for how to change the language.
+\end{command}
+\begin{command}{\weekdayshortname}
+ Inside of \marg{date format}, this macro expands to the weekday's short name in the current language (like |Wed|).
+ See below for how to change the language.
+\end{command}
+\subsubsection*{Changing the language for dates}
+The date feature is implemented using the \PGF\ calendar module. This module employs the package |translator| (if it is loaded). I don't have more detail yet, sorry. Please refer to \cite{tikz} for more details.
+
+\subsection{Preprocessing Cell Content}
+The preprocessing step allows to change cell contents \emph{before} any typesetting routine (like number formatting) has been applied. The data is available in numerical format and math operations can be applied. Furthermore, cells can be erased depending on their numerical value. The preprocess step follows the data acquisition step (``loading step''). This means in particular that you can create (or copy) columns and apply operations on them.
+
+\begin{codekey}{/pgfplots/table/preproc cell content}
+ Allows to \emph{modify} the contents of cells \emph{before} |assign cell contents| is called.
+
+ The semantics is as follows: before the preprocessor, |@cell content| contains the raw input data (or, maybe, the result of another preprocessor call). After the preprocessor, |@cell content| is filled with a -- possibly modified -- value. The resulting value is then used as input to |assign cell contents|.
+
+ In the default settings, |assign cell contents| expects numerical input. So, the preprocessor is expected to produce numerical output.
+
+ It is possible to provide multiple preprocessor directives using |.append code| or |.append style| key handlers.
+
+ In case you don't want (or need) stackable preprocessors, you can also use `|#1|' to get the raw input datum as it is found in the file.
+\end{codekey}
+
+\begin{stylekey}{/pgfplots/table/string replace=\marg{pattern}\marg{replacement}}
+ Appends code to the current |preproc cell content| value which replace every occurence of \marg{pattern} with \marg{replacement}. No expansion is performed during this step; \marg{pattern} must match literally.
+\begin{codeexample}[]
+\pgfplotstabletypeset[columns={level,dof}]
+ {pgfplotstable.example1.dat}
+
+
+\pgfplotstabletypeset[
+ columns={level,dof},
+ columns/level/.style={string replace={A}{B}}, % does nothing because there is no 'A'
+ columns/dof/.style={string replace={256}{-42}}] % replace '256' with '-42'
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/clear infinite}
+ Appends code to the current |preproc cell content| value which replaces every infinite number with the empty string. This clears any cells with $\pm \infty$ and NaN.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/multiply with=\marg{real number}}
+ Appends code to the current |preproc cell content| value which multiplies every cell with \marg{real number}. Arithmetics are carried out in floating point.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/divide by=\marg{real number}}
+ Appends code to the current |preproc cell content| value which divides every cell by \marg{real number}. Arithmetics are carried out in floating point.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/sqrt}
+ Appends code to the current |preproc cell content| value which applies $\sqrt{x}$ to every non-empty cell. Arithmetics are carried out in floating point.
+
+ The following example copies the column |error1| and applies |sqrt| to the copy.
+\begin{codeexample}[]
+\pgfplotstableset{
+ columns={error1,sqrterror1},
+ create on use/sqrterror1/.style={create col/copy=error1},
+ columns/error1/.style={column name=$\epsilon$},
+ columns/sqrterror1/.style={sqrt,column name=$\sqrt \epsilon$},
+ sci,sci 10e,precision=3,sci zerofill
+}
+\pgfplotstabletypeset{pgfplotstable.example1.dat}
+\end{codeexample}
+ Please take a look at section~\ref{pgfplotstable:createcol} for details about |create on use|.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/multiply -1}
+ Appends code to current |preproc cell content| value which multiplies every cell with $-1$. This style does the same job as |multiply with=-1|, it is just faster because only the sign changes.
+\begin{codeexample}[]
+\pgfplotstableset{
+ columns={dof,error2,slopes2},
+ columns/error2/.style={sci,sci zerofill},
+ columns/slopes2/.style={dec sep align,empty cells with={\ensuremath{-}}},
+ create on use/slopes2/.style=
+ {create col/gradient loglog={dof}{error2}}}
+
+\pgfplotstabletypeset{pgfplotstable.example1.dat}
+
+\pgfplotstabletypeset[columns/slopes2/.append style={multiply -1}]
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+\end{stylekey}
+
+\begin{codekey}{/pgfplots/table/row predicate}
+ A boolean predicate which allows to select particular rows of the input table. The argument |#1| contains the current row's index (starting with~$0$, not counting comment lines or column names).
+
+ The return value is assigned to the \TeX-if |\ifpgfplotstableuserow|. If the boolean is not changed, the return value is true.
+\begin{codeexample}[narrow]
+% requires \usepackage{booktabs}
+\pgfplotstabletypeset[
+ every head row/.style={
+ before row=\toprule,after row=\midrule},
+ every last row/.style={
+ after row=\bottomrule},
+ row predicate/.code={%
+ \ifnum#1>4\relax
+ \ifnum#1<8\relax
+ \pgfplotstableuserowfalse
+ \fi
+ \fi}
+]
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+ Please note that |row predicate| is applied \emph{before} any other option which affects row appearance. It is evaluated before |assign cell contents|. For example, the even/odd row styles refer to those rows for which the predicate returns |true|. In fact, you can use |row predicate| to truncate the complete table before it as actually processed.
+
+ During |row predicate|, the macro |\pgfplotstablerows| contains the total number of \emph{input} rows.
+
+ Furthermore, |row predicate| applies only to the typeset routines, not the read methods. If you want to plot only selected table entries with |\addplot table|, use the \PGFPlots\ coordinate filter options.
+\end{codekey}
+
+\begin{stylekey}{/pgfplots/table/skip rows between index=\marg{begin}\marg{end}}
+ A style which appends an |row predicate| which discards selected rows. The selection is done by index where indexing starts with~$0$. Every row with index $\meta{begin} \le i < \meta{end}$ will be skipped.
+\begin{codeexample}[narrow]
+% requires \usepackage{booktabs}
+\pgfplotstabletypeset[
+ every head row/.style={
+ before row=\toprule,after row=\midrule},
+ every last row/.style={
+ after row=\bottomrule},
+ skip rows between index={2}{4},
+ skip rows between index={7}{9}
+]
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/select equal part entry of=\marg{part no}\marg{part count}}
+ A style which overwrites |row predicate| with a subset selection predicate. The idea is to split the current column into \marg{part count} equally sized parts and select only \marg{part no}.
+
+ This can be used to simulate multicolumn tables.
+\begin{codeexample}[]
+% requires \usepackage{booktabs}
+\pgfplotstableset{
+ every head row/.style={before row=\toprule,after row=\midrule},
+ every last row/.style={after row=\bottomrule}}
+
+\pgfplotstabletypeset[string type]{pgfplotstable.example2.dat}
+
+\pgfplotstabletypeset[
+ display columns/0/.style={select equal part entry of={0}{2},string type},
+ display columns/1/.style={select equal part entry of={0}{2},string type},
+ display columns/2/.style={select equal part entry of={1}{2},string type},
+ display columns/3/.style={select equal part entry of={1}{2},string type},
+ columns={A,B,A,B}
+]
+ {pgfplotstable.example2.dat}
+\end{codeexample}
+ The example above shows the original file as-is on the left side. The right side shows columns A,B,A,B~-- but only half of the elements are shown, selected by indices \#0 or \#1 of \#2. The parts are equally large, up to a remainder.
+
+ If the available number of rows is not dividable by \marg{part count}, the remaining entries are distributed equally among the first parts.
+\end{stylekey}
+
+
+\subsection{Postprocessing Cell Content}
+The postprocessing step is applied after the typesetting stage, that means it can't access the original input data. However, it can apply final formatting instructions which are not content based.
+
+\begin{codekey}{/pgfplots/table/postproc cell content}
+ Allows to \emph{modify} assigned cell content \emph{after} it has been assigned, possibly content-dependend. Ideas could be to draw negative numbers in red, typeset single entries in bold face or insert replacement text.
+
+ This key is evaluated \emph{after} |assign cell content|. Its semantics is to modify an existing |@cell content| value.
+
+ There may be more than one |postproc cell content| command, if you use |.append code| or |.append style| to define them:
+\begin{codeexample}[]
+% requires \usepackage{eurosym}
+\pgfplotstabletypeset[
+ column type=r,
+ columns={dof,info},
+ columns/info/.style={
+ postproc cell content/.append style={
+ /pgfplots/table/@cell content/.add={$\bf}{$}},
+ postproc cell content/.append style={
+ /pgfplots/table/@cell content/.add={}{\EUR{}}}
+ }]
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+ The code above modifies |@cell content| successively. First, ``|$\bf ... $|'' is inserted, then ``|...\EUR|''. It should be noted that |pgfkeys| handles |.style| and |.code| in (quasi) the same way -- both are simple code keys and can be used as such. You can combine both with |.append style| and |.append code|. Please refer to~\cite[section about pgfkeys]{tikz} for details.
+
+ As in |assign cell contents|, the code can evaluate helper macros like |\pgfplotstablerow| to change only particular entries. Furthermore, the argument ``|#1|'' expands to the \emph{unformatted} input argument which was found in the input table. This allows complete context based formatting options. Please remember that empty strings may appear due to column balancing -- introduce special treatment if necessary.
+
+ There is one special case which occurs if |@cell content| itsself contains the cell separation character `|&|'. In this case, |postproc cell contents| is invoked \emph{separately} for each part before and after the ampersand and the ampersand is inserted afterwards. This allows compatibility with special styles which create artificial columns in the output (which is allowed, see |dec sep align|). To allow separate treatment of each part, you can use the macro |\pgfplotstablepartno|. It is defined only during the evaluation of |postproc cell content| and it evaluates to the current part index (starting with~$0$). If there is no ampersand in your text, the value will always be~$0$.
+
+ This key is evaluated inside of a local \TeX\ group, so any local macro assignments will be cleared afterwards.
+
+ The following example can be used to insert a dash, $-$, in a slope column:
+\begin{codeexample}[]
+\pgfplotstableset{
+ create on use/slopes1/.style=
+ {create col/gradient loglog={dof}{error1}}}
+
+\pgfplotstabletypeset[
+ columns={dof,error1,slopes1},
+ columns/error1/.style={sci,sci zerofill},
+ columns/slopes1/.style={
+ postproc cell content/.append code={%
+ \ifnum\pgfplotstablerow=0
+ \pgfkeyssetvalue{/pgfplots/table/@cell content}{\ensuremath{-}}%
+ \fi
+ }%
+ }]
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+Since this may be useful in a more general context, it is available as |empty cells with| style.
+\end{codekey}
+
+\begin{stylekey}{/pgfplots/table/empty cells with=\marg{replacement}}
+ Appends code to |postproc cell content| which replaces any empty cell with \marg{replacement}.
+
+ If |dec sep align| is active, the replacement will be inserted only for the part before the decimal separator.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/set content=\marg{content}}
+ A style which redefines |postproc cell contents| to always return the value \marg{content}.
+\end{stylekey}
+
+
+\section{Generating Data in New Tables or Columns}
+\label{pgfplotstable:createcol}
+It is possible to create new tables from scratch or to change tables after they have been loaded from disk.
+
+\subsection{Creating New Tables From Scratch}
+\begin{command}{\pgfplotstablenew\oarg{options}\marg{row count}\marg{\textbackslash table}}
+ Creates a new table from scratch.
+
+ The new table will contain all columns listed in the |columns| key
+ which needs to be provided in \oarg{options}\footnote{Currently, you need to provide at least one column here: the implementation gets confused for completely empty tables. If you do not provide any column name, a dummy column will be created.}.
+
+ Furthermore, there must be |create on use| statements (see the next subsection) for every
+ column which shall be generated. Columns are generated
+ independently, in the order of appearance in |columns|.
+
+ The table will contain exactly \marg{row count} rows. If \marg{row count} is an |\pgfplotstablegetrowsof| statement, that statement will be executed and the resulting number of rows be used. Otherwise, \marg{row count} will be evaluated as number.
+\begin{codeexample}[]
+% this key setting could be provided in the document's preamble:
+\pgfplotstableset{
+ % define how the 'new' column shall be filled:
+ create on use/new/.style={create col/set list={4,5,6,7,...,10}}}
+% create a new table with 11 rows and column 'new':
+\pgfplotstablenew[columns={new}]{11}\table
+% show it:
+\pgfplotstabletypeset[empty cells with={---}]\table
+\end{codeexample}
+
+\begin{codeexample}[]
+% create a new table with 11 rows and column 'new':
+\pgfplotstablenew[
+ % define how the 'new' column shall be filled:
+ create on use/new/.style={create col/expr={factorial(15+\pgfplotstablerow)}},
+ columns={new}]
+ {11}
+ \table
+% show it:
+\pgfplotstabletypeset\table
+\end{codeexample}
+\end{command}
+
+\subsection{Creating New Columns From Existing Ones}
\begin{command}{\pgfplotstablecreatecol\oarg{options}\marg{new col name}\marg{\textbackslash table}}
-Creates a new column named \marg{new col name} and appends it to table \marg{\textbackslash table}.
+Creates a new column named \marg{new col name} and appends it to an already existing table \marg{\textbackslash table}.
-This command is technical, but it offers a flexible framework to generate new columns. It has been designed to create new columns using the already existing values -- for example using logical or numerical methods to combine existing values. It provides fast access to a row's value and the next row's value.
+End users probably don't need to use |\pgfplotstablecreatecol| directly at all -- there is the high--level framework |create on use| which invokes it internally and can be used with simple key--value assignments (see below). However, this documentation explains how to use values of existing columns to fill new cells.
-The following documentation is for all who want to \emph{write} specialised columns. It is not particularly difficult; it is just technical and it requires some knowledge of |pgfkeys|. If you don't like it, you can resort to some predefined column generation styles - and enable those styles in \marg{options}.
+This command offers a flexible framework to generate new columns. It has been designed to create new columns using the already existing values -- for example using logical or numerical methods to combine existing values. It provides fast access to a row's value, the previous row's value and the next row's value.
+
+The following documentation is for all who want to \emph{write} specialised columns. It is not particularly difficult; it is just technical and it requires some knowledge of |pgfkeys|. If you don't like it, you can resort to predefined column generation styles - and enable those styles in \marg{options}.
The column entries will be created using the command key |create col/assign|. It will be invoked for every row of the table.
It is supposed to assign contents to |create col/next content|.
@@ -1110,9 +1428,11 @@ expands to the current row's value of the column identified by \marg{col name}.
Furthermore, |\nextrow|\marg{col name} expands to the \emph{next} row's
value of the designated column and |\prevrow|\marg{col name} expands to the value of the \emph{previous} row.
+So, the idea is to simply redefine the command key |create col/assign| in such a way that it fills new cells as desired.
+
Two special |assign| routines are available for the first and last row: The contents for the \emph{last} row is computed with |create col/assign last|. Its semantics is the same. The contents for the \emph{first} row is computed with |create col/assign first| to simplify special cases here. These first and last commands are optional, their default is to invoke the normal |assign| routine.
-The evaluation of the |assign| keys is done in local \TeX\ groups.
+The evaluation of the |assign| keys is done in local \TeX\ groups (i.e. any local definitions will be cleared afterwards).
The following macros are useful during cell assignments:
\begin{enumerate}
@@ -1130,7 +1450,8 @@ The following macros are useful during cell assignments:
\item |\pgfplotstablerow| and |\pgfplotstablerows| which contain the current row's index and the total number of rows, respectively. See page~\pageref{pgfplotstable:page:tablerow} for details.
\item |\pgfmathaccuma| and |\pgfmathaccumb| can be used to transport intermediate results.
- Both maintain their value from one call to the next. All other local variables will be deleted after leaving the assignment routines.
+ Both maintain their value from one column assignment to the next. All other local variables will be deleted after leaving the assignment routines. The initial value is the empty string for both of them unless they are already initialised by column creation styles.
+ \item commands which are valid throughout every part of this package, for example |\pgfplotstablerow| to get the current row index or |\pgfplotstablerows| to get the total number of rows.
\end{enumerate}
The \marg{col name} is expected to be a \emph{physical} column name, no alias or column index is allowed (unless column indices and column names are the same).
@@ -1166,52 +1487,157 @@ The default implementation of |assign| is to produce empty strings. The default
\begin{codeexample}[narrow]
% requires \usepackage{array}
-\pgfplotstableset{
+\pgfplotstableset{% could be used in preamble
create on use/quot1/.style=
{create col/quotient={error1}}}
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[
columns={error1,quot1},
columns/error1/.style={sci,sci zerofill},
columns/quot1/.style={dec sep align}]
{pgfplotstable.example1.dat}
\end{codeexample}
- The example above queries |quot1| which does not yet exist in the input file. Therefor, it is checked whether a |create on use| style for |quot1| exists. This is the case, so it is used to create the missing column.
+ The example above queries |quot1| which does not yet exist in the input file. Therefor, it is checked whether a |create on use| style for |quot1| exists. This is the case, so it is used to create the missing column. The |create col/quotient| key is discussed below; it computes quotients of successive rows in column |error1|.
A |create on use| specification is translated into
- |\pgfplotstablecreatecol[|\meta{create options}|]|\marg{col name}\marg{the table}.
+ |\pgfplotstablecreatecol[|\meta{create options}|]|\marg{col name}\marg{the table},
+
+ or, equivalently, into
- This feature allows some lazyness, because you can omit the lengthy table modifications. However, lazyness may cost something: in the example above, the generated column will be \emph{lost} after returning from |\pgfplotstabletypesetfile|.
+ |\pgfplotstablecreatecol[|create on use/\meta{col name}|]|\marg{col name}\marg{the table}.
+
+ This feature allows some lazyness, because you can omit the lengthy table modifications. However, lazyness may cost something: in the example above, the generated column will be \emph{lost} after returning from |\pgfplotstabletypeset|.
The |create on use| has higher priority than |alias|.
In case \meta{col name} contains characters which are required for key settings, you need to use braces around it: ``|create on use/{name=wi/th,special}/.style={...}|''.
+
+ More examples for |create on use| are shown below while discussing the available column creation styles.
\end{pgfplotstablecreateonusekey}
+\subsection{Predefined Column Generation Methods}
+The following keys can be used in both |\pgfplotstablecreatecol| and the easier |create on use| frameworks.
+
+\subsubsection{Acquiring Data Somewhere}
+\begin{stylekey}{/pgfplots/table/create col/set=\marg{value}}
+ A style for use in column creation context which creates a new column and writes \marg{value} into each new cell. The value is written as string (verbatim).
+\begin{codeexample}[]
+\pgfplotstableset{
+ create on use/my new col/.style={create col/set={--empty--}},
+ columns/my new col/.style={string type}
+}
+
+\pgfplotstabletypeset[
+ columns={level,my new col},
+]{pgfplotstable.example1.dat}
+\end{codeexample}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/create col/set list=\marg{comma-separated-list}}
+ A style for use in column creation context which creates a new column consisting of the entries in \marg{comma-separated-list}. The value is written as string (verbatim).
+
+ The \marg{comma-separated-list} is processed via \Tikz's |\foreach| command, that means you can use |...| expressions to provide number (or character) ranges.
+\begin{codeexample}[]
+\pgfplotstableset{
+ create on use/my new col/.style={
+ create col/set list={A,B,C,4,50,55,...,100}},
+ columns/my new col/.style={string type}
+}
+
+\pgfplotstabletypeset[
+ columns={level,my new col},
+]{pgfplotstable.example1.dat}
+\end{codeexample}
+ \noindent The new column will be padded or truncated to the required number of rows. If the list does not contain enough elements, empty cells will be produced.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/create col/copy=\marg{column name}}
+ A style for use in column creation context which simply copies the existing column \marg{column name}.
+\begin{codeexample}[]
+\pgfplotstableset{
+ create on use/new/.style={create col/copy={level}}
+}
+
+\pgfplotstabletypeset[
+ columns={level,new},
+ columns/new/.style={column name=Copy of level}
+]{pgfplotstable.example1.dat}
+\end{codeexample}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/create col/copy column from table=\marg{file name or \textbackslash macro}\marg{column name}}
+ A style for use in column creation context which creates a new column consisting of the entries in \marg{column name} of the provided table. The argument may be either a file name or an already loaded table (i.e. a \meta{\textbackslash macro} as returned by |\pgfplotstableread|).
+
+ You can use this style, possibly combined with |\pgfplotstablenew|, to merge one common sort of column from different tables into one large table.
+
+ The cell values are written as string (verbatim).
+
+ \noindent The new column will be padded or truncated to the required number of rows. If the list does not contain enough elements, empty cells will be produced.
+\end{stylekey}
+
+
+\subsubsection{Mathematical Operations}
+
+\begin{key}{/pgf/fpu=\marg{true,false}}
+\index{Precision}
+ Before we start to describe the column generation methods, one word about the math library. The core is always the \PGF\ math engine written by Mark Wibrow and Till Tantau. However, this engine has been written to produce graphics and is not suitable for scientific computing.
+
+ I added a high-precision floating point library to \PGF\ which will be part of releases newer than \PGF\ $2.00$. It offers the full range of IEEE double precision computing in \TeX. This FPU is also part of \PGFPlotstable, and it is activated by default for |create col/expr| and all other predefined mathematical methods.
+
+ The FPU won't be active for newly defined numerical styles. If you want to add own routines or styles, you will need to use
+\begin{codeexample}[code only]
+\pgfkeys{/pgf/fpu=true}
+\end{codeexample}
+ \noindent in order to activate the extended precision. The standard math parser is limited to fixed point numbers in the range $\pm 16384.00000$.
+\end{key}
+
\begin{stylekey}{/pgfplots/table/create col/expr=\marg{math expression}}
A style for use in |\pgfplotstablecreatecol| which uses \marg{math expression} to assign contents for the new column.
\begin{codeexample}[]
-\pgfplotstableread{pgfplotstable.example1.dat}\table
-\pgfplotstablecreatecol[
- create col/expr={\thisrow{level}*2}]
- {new}\table
+\pgfplotstableset{
+ create on use/new/.style={
+ create col/expr={\thisrow{level}*2}}
+}
\pgfplotstabletypeset[
columns={level,new},
columns/new/.style={column name=$2\cdot $level}
-]\table
+]{pgfplotstable.example1.dat}
\end{codeexample}
The macros |\thisrow|\marg{col name} and |\nextrow|\marg{col name} can be used to use values of the existing table.
Please see |\pgfplotstablecreatecol| for more information.
- \paragraph{Attention:} Currently, |expr| uses the math parser of \PGF. Although very powerful, it has never been intended for scientific applications. Its $5.5$ fixed point arithmetic has its limitations.
+ \paragraph{Accumulated columns:} The |expr| style initialises |\pgfmathaccuma| to |0| before its first column. Whenever it computes a new column value, it redefines |\pgfmathaccuma| to be the result. That means you can use |\pgfmathaccuma| inside of \marg{math expression} to accumulate columns. See |create col/expr accum| for more details.
+
+ \paragraph{About the precision and number range:}\index{Precision}\index{Floating Point Unit} Starting with version 1.2, |expr| 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.
+
+ \paragraph{Accepted operations:} The math parser of \PGF, combined with the FPU, provides the following function and operators:
+
+ |+|, |-|, |*|, |/|, |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 constanst |pi| and |e|, |^| (power operation), |factorial|\footnote{Starting with \PGF\ versions newer than $2.00$, you can use the postfix operator \texttt{!} instead of \texttt{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~\cite{tikz}, the FPU routines have been developed as part of \PGFPlots. The documentation for both parts can be found in~\cite{tikz}. \textbf{Attention:} Trigonometric functions work with degrees, not with radians!
+
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/create col/expr accum=\marg{math expression}\marg{accum initial}}
+ A variant of |create col/expr| which also allows to define the initial value of |\pgfmathaccuma|. The case \marg{accum initial}=|0| is \emph{equivalent} to |expr=|\marg{math expression}.
- There is limited support for float point arithmetics, but that is far from complete and every elementary operation needs to be programmed by hand. Some of the following numerical styles employ these routines, they have been included into the \PGF\ math library (but not into the parser).
+\begin{codeexample}[]
+\pgfplotstableset{
+ create on use/new/.style={
+ create col/expr={\pgfmathaccuma + \thisrow{level}}},
+ create on use/new2/.style={
+ create col/expr accum={\pgfmathaccuma - \thisrow{level}}{100}}
+}
- Furthermore, you can create new columns using the |fp| package which allows precise fixed point arithmetics.
+\pgfplotstabletypeset[
+ columns={level,new,new2},
+ columns/new/.style={column name=$\sum$level},
+ columns/new2/.style={column name=$\prod$level}
+]{pgfplotstable.example1.dat}
+\end{codeexample}
+The example creates two columns: the |new| column is just the sum of each value in the \meta{level} column (it employs the default |\pgfmathaccuma=0|). The |new2| column initialises |\pgfmathaccuma=100| and then successively subtracts the value of \meta{level}.
\end{stylekey}
\begin{stylekey}{/pgfplots/table/create col/quotient=\marg{column name}}
@@ -1219,19 +1645,19 @@ The default implementation of |assign| is to produce empty strings. The default
\begin{codeexample}[]
% requires \usepackage{array}
-\pgfplotstableread{pgfplotstable.example1.dat}\table
-\pgfplotstablecreatecol[create col/quotient=error1]
- {quot1}\table
-\pgfplotstablecreatecol[create col/quotient=error2]
- {quot2}\table
-
-\pgfplotstabletypeset[
+\pgfplotstableset{% configuration, for example, in preamble:
+ create on use/quot1/.style={create col/quotient=error1},
+ create on use/quot2/.style={create col/quotient=error2},
columns={error1,error2,quot1,quot2},
+ %
+ % display styles:
columns/error1/.style={sci,sci zerofill},
columns/error2/.style={sci,sci zerofill},
columns/quot1/.style={dec sep align},
- columns/quot2/.style={dec sep align}]
-\table
+ columns/quot2/.style={dec sep align}
+}
+
+\pgfplotstabletypeset{pgfplotstable.example1.dat}
\end{codeexample}
This style employs methods of the floating point unit, that means it works with a relative precision of about $10^{-7}$ ($7$ significant digits in the mantisse).
\end{stylekey}
@@ -1247,7 +1673,7 @@ The default implementation of |assign| is to produce empty strings. The default
\begin{codeexample}[]
% requires \usepackage{array}
-\pgfplotstabletypesetfile[
+\pgfplotstabletypeset[% here, configuration options apply only to this single statement:
create on use/rate1/.style={create col/dyadic refinement rate={error1}},
create on use/rate2/.style={create col/dyadic refinement rate={error2}},
columns={error1,error2,rate1,rate2},
@@ -1275,42 +1701,141 @@ The default implementation of |assign| is to produce empty strings. The default
\begin{codeexample}[]
% requires \usepackage{array}
-\pgfplotstableread{pgfplotstable.example1.dat}\table
-\pgfplotstablecreatecol[create col/gradient loglog={dof}{error1}]
- {slopes1}\table
-\pgfplotstablecreatecol[create col/gradient loglog={dof}{error2}]
- {slopes2}\table
-
-\pgfplotstabletypeset[
+\pgfplotstableset{% configuration, for example in preamble:
+ create on use/slopes1/.style={create col/gradient loglog={dof}{error1}},
+ create on use/slopes2/.style={create col/gradient loglog={dof}{error2}},
columns={dof,error1,error2,slopes1,slopes2},
+ % display styles:
columns/dof/.style={int detect},
columns/error1/.style={sci,sci zerofill},
columns/error2/.style={sci,sci zerofill},
columns/slopes1/.style={dec sep align},
- columns/slopes2/.style={dec sep align}]
-\table
+ columns/slopes2/.style={dec sep align}
+}
+\pgfplotstabletypeset{pgfplotstable.example1.dat}
\end{codeexample}
\begin{codeexample}[]
% requires \usepackage{array}
-\pgfplotstableread
- {pgfplotstable.example1.dat}\table
-\pgfplotstablecreatecol
- [create col/gradient semilogy={level}{error1}]
- {slopes1}\table
-
-\pgfplotstabletypeset[
+\pgfplotstableset{% configuration, for example in preamble:
+ create on use/slopes1/.style={create col/gradient semilogy={level}{error1}},
columns={level,error1,slopes1},
+ % display styles:
columns/level/.style={int detect},
- columns/error1/.style=
- {sci,sci zerofill,sci subscript},
- columns/slopes1/.style={dec sep align}]
-\table
+ columns/error1/.style={sci,sci zerofill,sci subscript},
+ columns/slopes1/.style={dec sep align}
+}
+\pgfplotstabletypeset{pgfplotstable.example1.dat}
\end{codeexample}
This style employs methods of the floating point unit, that means it works with a relative precision of about $10^{-6}$ ($6$ significant digits in the mantisse).
\end{keylist}
-\section{Plain \TeX\ and Con\TeX t support}
+\begin{stylekey}{/pgfplots/table/create col/function graph cut y=\marg{cut value}\marg{common options}\marg{one key-value set for each plot}}
+ A specialized style for use in |create on use| statements which computes cuts of (one or more) discrete plots $y(x_1), \dotsc, y(x_N)$ with a fixed \marg{cut value}. The $x_i$ are written into the table's cells.
+
+ In a cost--accuracy plot, this feature allows to extract the cost for fixed accuracy. The dual feature with |cut x| allows to compute the accuracy for fixed cost.
+
+ \pgfplotsset{anchor=center,/tikz/baseline}
+\begin{codeexample}[]
+\pgfplotstablenew[
+ create on use/cut/.style={create col/function graph cut y=
+ {2.5e-4}% search for fixed L2 = 2.5e-4
+ {x=Basis,y=L2,ymode=log,xmode=log}% double log, each function is L2(Basis)
+% now, provide each single function f_i(Basis):
+{{table=plotdata/newexperiment1.dat},{table=plotdata/newexperiment2.dat}}
+ },
+ columns={cut}]
+ {2}
+ \table
+\pgfplotstabletypeset{\table}
+
+\begin{tikzpicture}
+\begin{loglogaxis}
+ \addplot table[x=Basis,y=L2] {plotdata/newexperiment1.dat};
+ \addplot table[x=Basis,y=L2] {plotdata/newexperiment2.dat};
+ \draw[blue!30!white] (axis cs:1,2.5e-4) -- (axis cs:1e5,2.5e-4);
+ \node[pin=-90:{$x=53.66$}] at (axis cs:53.66,2.5e-4) {};
+ \node[pin=45:{$x=601.83$}] at (axis cs:601.83,2.5e-4) {};
+\end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+ In the example above, we are searching for $x_1$ and $x_2$ such that $f_1(x_1) = \pgfmathprintnumber{2.5e-4}$ and $f_2(x_2) =\pgfmathprintnumber{2.5e-4}$. On the left is the automatically computed result. On the right is a problem illustration with proper annotation.
+ The \marg{cut value} is set to |2.5e-4|. The \marg{common options} contain the problem setup; in our case logarithmic scales and column names. The third argument is a comma-separated-list. Each element $i$ is a set of keys describing how to get $f_i(\cdot)$.
+
+ During both, \marg{common options} and the key sets, the following keys can be used:
+ \begin{itemize}
+ \item |table|: either a file name or an already loaded table where to get the data points,
+ \item |x|: the column name of the $x$ axis,
+ \item |y|: the column name of the $y$ axis.
+ \end{itemize}
+ The keys |xmode| and |ymode| can take either |log| or |linear|. All mentioned keys have the common key path
+
+ \textcolor{red!75!black}{\texttt{/pgfplots/table/create col/function graph cut/}}.
+\end{stylekey}
+\begin{stylekey}{/pgfplots/table/create col/function graph cut x=\marg{cut value}\marg{common options}\marg{one key-value set for each plot}}
+ As above, just with $x$ and $y$ exchanged.
+\end{stylekey}
+
+\section{Miscellaneous}
+\subsection{Writing (Modified) Tables To Disk}
+\begin{key}{/pgfplots/table/outfile=\marg{file name} (initially empty)}
+ Writes the completely processed table as \TeX\ file to \marg{file name}. This key is described in all detail on page~\pageref{page:outfile}.
+\end{key}
+
+\begin{command}{\pgfplotstablesave\oarg{options}\marg{\textbackslash macro or input file name}\marg{output file name}}
+ This command takes a table and writes it to a new data file (without performing any typesetting).
+
+ If the first argument is a file name, that file is loaded first.
+
+ This command simply invokes |\pgfplotstabletypeset| with cleared output parameters. That means any of the column creation methods apply here as well, including any postprocessing steps (without the final typesetting).
+
+ |\pgfplotstablesave| uses the keys |reset styles| and |disable rowcol styles| to clear any typesetting related options. Furthermore, it sets |string type| to allow verbatim output.
+\begin{codeexample}[]
+\pgfplotstablesave[
+ create on use/postproc1/.style={create col/dyadic refinement rate=error1},
+ columns={dof,error1,postproc1}
+]
+ {pgfplotstable.example1.dat}
+ {pgfplotstable.example1.out.dat}
+\end{codeexample}
+Now, |pgfplotstable.example1.out.dat| is
+\lstinputlisting[basicstyle=\ttfamily\footnotesize,tabsize=8]{pgfplotstable.example1.out.dat}
+
+You can use the |col sep| key inside of \meta{options} to define a column separator for the output file. In case you need a different input column separator, use |in col sep| instead of |col sep|.
+
+\paragraph{Remarks}
+\begin{itemize}
+ \item
+Empty cells will be filled with |{}| if |col sep=space|. Use the |empty cells with| style to change that.
+ \item Use |disable rowcol styles=false| inside of \meta{options} if you need to change column/row based styles.
+\end{itemize}
+\end{command}
+
+\subsection{Miscellaneous Keys}
+\begin{key}{/pgfplots/table/disable rowcol styles=\mchoice{true,false} (initially false)}
+ Set this to |true| if |\pgfplotstabletypeset| shall \emph{not} set any styles which apply only to specific columns or only to specific rows.
+
+ This disables the styles
+ \begin{itemize}
+ \item |columns/|\meta{column name},
+ \item |display columns/|\meta{column index},
+ \item |every col no |\meta{column index},
+ \item |every row no |\meta{row index}.
+ \end{itemize}
+\end{key}
+
+\begin{key}{/pgfplots/table/reset styles}
+ Resets all table typesetting styles which do not explicitly depend on column or row names and indices. The affected styles are
+ \begin{itemize}
+ \item |every table|,
+ \item |every even row|, |every odd row|, |every even column|, |every odd column|,
+ \item |every first column|, |every last column|, |every first row|, |every last row|,
+ \item |every head row|.
+ \end{itemize}
+ In case you want to reset all, you should also consider the key |disable rowcol styles|.
+\end{key}
+
+\subsection{Plain \TeX\ and Con\TeX t support}
\label{sec:pgfplotstable:context}
The table code generator is initialised to produce \LaTeX\ |tabular| environments. However, it only relies on~`|&|' being the column separator and~`|\\|' the row terminator. The |column type| feature is more or less specific to |tabular|, but you can disable it completely. Replace |begin table| and |end table| with appropriate \TeX- or Con\TeX t commands to change it. If you have useful default styles (or bug reports), let me know.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment1.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment1.dat
new file mode 100644
index 00000000000..9a346a82afa
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment1.dat
@@ -0,0 +1,14 @@
+Basis L2 L2/r ref_L2 maxlevel
+5 2.97101314e-02 5.59380138e-02 5.31125962e-01 2
+5 2.97101314e-02 5.59380138e-02 5.31125962e-01 2
+13 5.26652234e-03 9.91576898e-03 5.31125962e-01 4
+15 3.79838856e-03 7.15157764e-03 5.31125962e-01 5
+29 8.40740227e-04 1.58293943e-03 5.31125962e-01 6
+37 5.01257065e-04 9.43763063e-04 5.31125962e-01 6
+83 1.10546226e-04 2.08135609e-04 5.31125962e-01 7
+117 5.41319568e-05 1.01919245e-04 5.31125962e-01 8
+243 1.24678404e-05 2.34743569e-05 5.31125962e-01 9
+359 6.00916462e-06 1.13140103e-05 5.31125962e-01 10
+839 1.11358143e-06 2.09664282e-06 5.31125962e-01 11
+1159 5.90008838e-07 1.11086424e-06 5.31125962e-01 11
+2583 1.03238273e-07 1.94376251e-07 5.31125962e-01 12
diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment2.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment2.dat
new file mode 100644
index 00000000000..2bf049df8d8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment2.dat
@@ -0,0 +1,14 @@
+Basis L2 L2/r ref_L2 maxlevel
+9 1.24298689e-01 5.23997221e-01 2.37212496e-01 1
+9 1.24298689e-01 5.23997221e-01 2.37212496e-01 1
+21 3.92062884e-02 1.65279187e-01 2.37212496e-01 2
+25 1.87518223e-02 7.90507358e-02 2.37212496e-01 3
+117 2.67078613e-03 1.12590449e-02 2.37212496e-01 5
+129 2.22236154e-03 9.36865293e-03 2.37212496e-01 5
+361 5.03665412e-04 2.12326678e-03 2.37212496e-01 7
+481 3.78427622e-04 1.59531066e-03 2.37212496e-01 8
+1273 6.25699533e-05 2.63771743e-04 2.37212496e-01 9
+1917 3.23577823e-05 1.36408423e-04 2.37212496e-01 9
+4689 7.29465016e-06 3.07515426e-05 2.37212496e-01 11
+6741 4.10049305e-06 1.72861596e-05 2.37212496e-01 11
+16761 8.28799652e-07 3.49391228e-06 2.37212496e-01 12
diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment3.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment3.dat
new file mode 100644
index 00000000000..b1e82795f60
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/newexperiment3.dat
@@ -0,0 +1,14 @@
+Basis L2 L2/r ref_L2 maxlevel
+27 5.50720207e-02 6.18174259e-01 8.90881817e-02 1
+27 5.50720207e-02 6.18174259e-01 8.90881817e-02 1
+27 5.50720207e-02 6.18174259e-01 8.90881817e-02 1
+27 5.50720207e-02 6.18174259e-01 8.90881817e-02 1
+117 9.92745366e-03 1.11434014e-01 8.90881817e-02 3
+225 8.98732438e-03 1.00881219e-01 8.90881817e-02 4
+683 1.82403693e-03 2.04745107e-02 8.90881817e-02 5
+959 9.61978751e-04 1.07980512e-02 8.90881817e-02 6
+3017 3.85075698e-04 4.32241056e-03 8.90881817e-02 8
+4421 1.47321463e-04 1.65365888e-03 8.90881817e-02 8
+12211 5.60095626e-05 6.28698010e-04 8.90881817e-02 10
+19029 1.83972055e-05 2.06505568e-04 8.90881817e-02 11
+51407 4.47833372e-06 5.02685500e-05 8.90881817e-02 12
diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment1.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment1.dat
new file mode 100644
index 00000000000..de4fe964587
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment1.dat
@@ -0,0 +1,13 @@
+Basis L2 L2/r ref_L2 maxlevel
+3 2.60508254e-01 4.90482999e-01 5.31125962e-01 1
+5 5.66241980e-02 1.06611618e-01 5.31125962e-01 2
+9 3.96350405e-02 7.46245586e-02 5.31125962e-01 3
+17 1.03555656e-02 1.94973817e-02 5.31125962e-01 4
+33 2.61539205e-03 4.92424065e-03 5.31125962e-01 5
+65 6.55520492e-04 1.23420909e-03 5.31125962e-01 6
+129 1.63984908e-04 3.08749561e-04 5.31125962e-01 7
+257 4.10027722e-05 7.71997136e-05 5.31125962e-01 8
+513 1.02510486e-05 1.93005978e-05 5.31125962e-01 9
+1025 2.56253402e-06 4.82471994e-06 5.31125962e-01 10
+2049 6.38710772e-07 1.20255988e-06 5.31125962e-01 11
+4097 1.46570173e-07 2.75961228e-07 5.31125962e-01 12
diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment2.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment2.dat
new file mode 100644
index 00000000000..09153af54f4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment2.dat
@@ -0,0 +1,16 @@
+Basis L2 L2/r ref_L2 maxlevel
+9 1.98638983e-01 8.37388363e-01 2.37212496e-01 1
+21 5.64326131e-02 2.37898990e-01 2.37212496e-01 2
+49 2.92574780e-02 1.23338688e-01 2.37212496e-01 3
+113 1.22483110e-02 5.16343414e-02 2.37212496e-01 4
+257 4.49960253e-03 1.89686573e-02 2.37212496e-01 5
+577 1.99398950e-03 8.40592102e-03 2.37212496e-01 6
+1281 7.23795581e-04 3.05125402e-03 2.37212496e-01 7
+2817 2.38389007e-04 1.00495974e-03 2.37212496e-01 8
+6145 7.40547620e-05 3.12187441e-04 2.37212496e-01 9
+13313 2.21347558e-05 9.33119303e-05 2.37212496e-01 10
+28673 6.43912576e-06 2.71449687e-05 2.37212496e-01 11
+61441 1.83662857e-06 7.74254562e-06 2.37212496e-01 12
+131073 5.08287160e-07 2.14275036e-06 2.37212496e-01 13
+278529 1.34832867e-07 5.68405415e-07 2.37212496e-01 14
+589825 1.44807933e-07 6.10456597e-07 2.37212496e-01 15
diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment3.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment3.dat
new file mode 100644
index 00000000000..def06e749d8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/oldexperiment3.dat
@@ -0,0 +1,16 @@
+Basis L2 L2/r ref_L2 maxlevel
+27 1.09332286e-01 1.22723670e+00 8.90881817e-02 1
+81 5.01947271e-02 5.63427451e-01 8.90881817e-02 2
+225 1.73080188e-02 1.94279628e-01 8.90881817e-02 3
+593 8.27911552e-03 9.29316926e-02 8.90881817e-02 4
+1505 3.07418413e-03 3.45072047e-02 8.90881817e-02 5
+3713 1.50713390e-03 1.69173270e-02 8.90881817e-02 6
+8961 6.74034243e-04 7.56592210e-03 8.90881817e-02 7
+21249 2.80328651e-04 3.14664241e-03 8.90881817e-02 8
+49665 1.15461176e-04 1.29603247e-03 8.90881817e-02 9
+114689 4.47345923e-05 5.02138347e-04 8.90881817e-02 10
+262145 1.63023256e-05 1.82990890e-04 8.90881817e-02 11
+593921 5.64639994e-06 6.33798987e-05 8.90881817e-02 12
+1335297 1.88007387e-06 2.11035160e-05 8.90881817e-02 13
+2981889 5.97852515e-07 6.71079489e-06 8.90881817e-02 14
+6619137 2.63533023e-07 2.95811429e-06 8.90881817e-02 15
diff --git a/Master/texmf-dist/doc/latex/pgfplots/todo.txt b/Master/texmf-dist/doc/latex/pgfplots/todo.txt
index 23880977b8f..0c9e581e428 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/todo.txt
+++ b/Master/texmf-dist/doc/latex/pgfplots/todo.txt
@@ -1,11 +1,237 @@
-------------------------------------------------------------
-BUGS
+TODO pgfplots release 1.2
-------------------------------------------------------------
++ redefine domain and samples key: the current implementation doesn't accept the
+ extended number range if provided outside of plot expression or plot gnuplot.
++ -> but it is now slightly incompatible FIXED
++ search for 'pt' suffixes which produce log message warnings
++ verify that plot expression and the fpu works with pgf 2.00 (which is not trivial)
+X the unary '-' operator has the wrong precedence in both, pgf 2.00 and pgf CVS.
+ (can't be solved)
++ eliminate some of the dimen registers which are not absolutely necessary
++ check manual for missing features and updates
++ update manual: authors section
++ manual should contain more 'plot expression' than 'plot gnuplot'
++ there is a bug with 'axis equal' -> see manual examples
++ clean .table files from repository (at least the unused ones)
++ run all tests:
+ PGF 2.00 PGF CVS
+ FPU 2009-02-01 2009-02-01
+ example plain 2009-02-01 2009-02-01
+ example latex 2009-02-01 2009-02-01
+ example context 2009-02-01 2009-02-01
+ tests latex 2009-02-01 2009-02-01
+ tests context 2009-02-01 2009-02-01
+ clickable lib 2009-02-01 2009-02-01
+ manual 2009-02-01 2009-02-01
++ compile manuals
++ fix latest bugs
+- submit ZIP files
+- further features should be either very stable or should wait
+
+
+
+-------------------------------------------------------------
+BUGS / FIXES
+-------------------------------------------------------------
+
++ something with the table package appears to be buggy!?
+
++ the plot table[] search path is not good - it should include /pgfplots
+
+- introduce backwards compatibility with old pgfmathfloat.code.tex file
+ [ not interesting for pgfplots 1.2, only for pgfplots 1.1 !]
+
++ there is a bug related with empty axes - I suppose in conjunction with the
+ tickmin/max feature (it won't be reset properly)
+
+- the arguments to plot file[#1] and plot table[#1] are not consistent with
+ rest. They need to be treated as behavior options (maybe in a different key
+ path).
+
+
+- there is a space too much in some behavior messages (occured in test
+ processing)
+
+X introduce backwards compatibility with old pgfmathfloat.code.tex file
+
+- the pgf math parser has wrong precedence for '-' prefix op:
+ exp(-x^2) is wrong.
+
+- the auto-generated tick labels for non-unit-distance log axes could be better.
+
++ verify that the domain key always accepts the extended data range
+
++ I observed problems with opacity set for just one plot which was used for
+ every plot in the axes!?
+
+
++ the stacked plots impl is not yet in logical coords - that means it
+ won't work with non-standard unit vectors!
+
+- fix version stuff in package header
+- introduce CVS Header Variables in every sourcefile
+
++ The floating point math routines should be put into a separate library.
+ Provide compatibility support for that in pgfplots!
+
++ empty plots cause bugs.
++ empty plots and the named nodes may not work correctly -> check that
+
++ newlines in plot coordinates cause an error.
+ + provide sanity checking and correct error messages!
+
++ 'domain' can't be used to increase the data range, even when combined with fp.
++ huge 'domain' arguments for 'plot function' lead to an 'dimension too large' error
+ although everything works fine
+
++ the float math methods should be affected by the fixedpoint library, but they
+ are (because the underlying pgf math routines are exchanged).
+
+X scaled ticks is not properly implemented for log axes
+ + it is not available for log axes, so that's ok
+
++ pgfplotstable and \rowcolor and 'sci sep align' in conjunction produces
+ overwritten digits! The color seems to be on top of the numbers left of the
+ sci separator.
+ -> This is caused by the left/right overhang of the colortbl package and my
+ implementation of 'sci sep align' as an extra column. That's bad.
+ -> Idea:
+ - manually overwrite \rowcolor/\columncolor/\cellcolor in a portable way such
+ that overhangs are made properly.
+ Maybe there is a macro in colortbl?
+ [fixed for \rowcolor]
+
+
++ stacked plots + error bars don't work correctly together: I need to shift the
+ error bars
+
++ error bars should be drawn on top of the plot to avoid conflicts with filling.
+
++ [xy]ticklabel pos values 'top' and 'bottom' are somewhat inconsistent with
+ the actual placement
+
++ the auto-disable-feature for logarithmic minor ticks can be overruled (of
+ minor grid lines) which should not be possible
+ -> provide a good policy how to deal with user inputs:
+ 1. draw minor tick/grids if requested
+ 2. provide error message
+
++ scatter is disabled if no default mark has been set.
+
++ filter warnings are broken because they don't output the input coordinates
+
++ tick align=center is broken since last revision. Possibly tick align=outside
+ as well.
+
++ clickable lib is broken somehow
+
++ check for clickable lib if multiple axes are in the same tikzpicture
+ -> doesn't work. Why!?
+ - I can't reproduce that bug. Maybe it is fixed in the meantime?
+
++ the case
+ ymin=629.65,
+ ymax=629.70,
+ FAILS with math errors because the affine data transformation is deactivated
+ for the automatic tick computation! Providing tick labels manually works.
+ -> FIX THAT! Ticks should be computed without this restriction (if necessary,
+ in float arithmetics)!
+
++ it is not possible to provide '[xy]mode' in styles.
+ -> ok, provided error message.
+
++ check whether there are any plots before processing something like
+ 'xtick=data' or so
+
++ the clipping of tick/grid lines is currently disabled due to the change to
+ logical coordinates and needs attention.
+
+- In 3D case axis [xyz] line != box, there is just ONE hyperplane.
+ My implementation works only if either ALL are box or ALL are 'middle'.
+
+- 3D case : which hyperplane gets tick LABELS?
+ The current implementation based on '[xzy]ticklabel pos' is not sufficient
+
+- 3D case: something fails with disabledatascaling
+
+- 3D case : grid lines work correctly, but they are not satisfactory.
+ I'd like grid lines in the background only.
+
+- 3D case : tick/grid lines are on top of the axis lines. This leads to
+ poor quality.
+
++ '\coordinate (<aname>) at (axis cs:0,0);' does NOT work;
+ '\node[name=<aname>] at ... ' DOES work.
+ -> I can't hook into the 'at' syntax; I can only override the 'name'
+ key.
+
++ check whether the \label/\ref construction requires \protect\tikz and
+ \protect\path etc. if it is placed inside of \caption...
+ -> no; it has catcode 12
+
++ check whether named nodes are still ok. Since the 'fill opacity' bugfix, these
+ may be broken...
+ maybe the scoping needs to be improved
+ -> there is still need for scopes in case 'clip markers'!
+
++ error messages if the PGF version is wrong should be added
+ -> check for \pgfkeys
+ -> I should also check whether the float routines are available!
+ Maybe they will migrate to a tikz library someday.
+
+
++ \addplot [fill opacity=...] is not scoped properly!
++ I suppose the same problem holds true for dotted line styles.
++ setting mark options to dashed also changes the legend's appearance
+
+
++ the clickable library does *not* work inside of figure environments
+
+
+
++ renormalization bug in
+ log(9.999998e-01) = 4.70201 != 0
+
+X Bug in table input: if colnames contain (some?) UTF8 characters, \csname <colname>\endcsname FAILS.
+ That means table column names can't use UTF8 characters.
+ Possible solution: for each character in <colname>, check whether it is active. If yes, change its meaning.
+ I am not sure if that's acceptable...
+
+X error recovery: it is sometimes almost impossible to find errors in
+ key-value-settings because \end{axis} or \pgfplotstabletypesetfile does not
+ is NOT the correct context.
+ -> possibly with \errorcontextlines=10?
+
++ the error message for gnuplot invocation is wrong; gnuplot should be called on
+ the '.gnuplot' file instead of the '.table' file
+
++ there are still plain TeX loops in the legend code!?
+
++ javascript stuff is incompatible with a lot of active characters,
+ for example the german package:
+ + bug in insdljs: workaround introduced.
+ + bug in my code fixed
+
+- javascript stuff does not work if the complete figure is rotated (sidewaysfigure).
+
+- javascript: incompatiblity with external library:
+ 1. filenames: \jobname contains characters with incompatible catcodes and
+ that funny insdljs package tries to assemble macros with these
+ characters.
+ -> fixed; I simply use pgfplotsJS as temporary file name.
+ 2. the images as such have corrupted forms
+ -> Can be fixed if
+ \usepackage{eforms}
+ is used BEFORE loading pgf. The reason: \begin{Form} and the shipout-hackery
+ of the pgf externalization bite each other.
+ \begin{Form} must come before the shipout hackery of pgf.
+ 3. \includegraphics does not preserve PDF forms.
- the interrupt bounding box feature should still update the data bounding box.
Otherwise, transformations may fail.
-- to check: it *could* be possible that errorbars + stacked plots are
++ to check: it *could* be possible that errorbars + stacked plots are
incompatible.
+ the 'alias' and 'create on use' features may lead to errors. Check it!
@@ -55,7 +281,7 @@ X active semicolons may be a problem
+ handle 'nan' and +-inf in plots
-- 'every axis plot post' is not reflected in legend (at least not properly)
++ 'every axis plot post' is not reflected in legend (at least not properly)
+ plot function: incompatibility with 'german' package and " catcodes
@@ -84,7 +310,7 @@ X active semicolons may be a problem
+ specifying axis limits for X should also limit those for Y (some sort of
clipping)
-- the text height of every axis x tick should be adjusted to allow tick scale
+X the text height of every axis x tick should be adjusted to allow tick scale
labels on the same vertical alignment
-> bug in pgf: text height does not properly respect to the current font!?
@@ -172,7 +398,219 @@ X verschiebung des ylabels ist komisch, wegen der rotate option
FEATURES
-------------------------------------------------------------
-- it would be interesting to get an high-level coordinate mapping
+- the FPU uninstall command can be assembled ONCE (globally). No need to do that
+ multiple times.
+
+- What about something like '/pgfplots/table/x expr={<math expression>}' ?
+ -> I could still use the lazy eval framework of pgfplotstable, i.e.
+ \thisrow{} commands, \pgfplotstablerow, \pgfplotstablecol etc.
+ The \prevrow and \nextrow features won't be possible (?)
+
+- improve support for multiple ordinates
+- improve support for negative axes
+
++ improve plot expression
+ + accuracy
+ + UI
+
+- it would be useful if the clipping could be disabled for certain parts of the
+ axis. Is that possible?
+ -> yes.
+ Idea: start clipping for every axis element separately! Shouldn't be
+ much more expensive than a single marker path.
+ - should work in the same way as before, there is no difference!
+ - scopes should introduce no further problems
+ - I could eliminate the nasty marker list
+
++ what about an optimized version of plot expression which does not need the
+ brace hack (\x,{sin(\x r)}) ?
+
+- allow math expressions for axis limits etc. Idea: try float parsing routine;
+ if it fails: use math parser first.
+
++ plot expression for log plots would be more valueable, if it could sample
+ points exponentially, i.e. linear between log(xmin) ... log(xmax):
+ x_i = exp( log(xmin) + i * ( log(xmax)-log(xmin) )/(N-1) )
+
+- what about a feature like 'draw[xmin=...,xmax=...] fitline between points (a)
+ (b)'?
+
+- define a 'cycle list' style which simply inserts different colors into the
+ predefined style (thus, markers are fixed, colors vary). One could also think
+ about a complementary style.
+ -> even better: I could prodive up to three different lists which can be
+ combined.
+ Example: colorlist, markerlist, linespeclist
+ -> iterate through all possible combinations!
+
+- cycle list should be implemented using an array structure. That's faster.
+
+
++ create public key alias for '/pgfplots/domain' -> '/tikz/domain'
+
+X the coordinate preparation routines should assign global registers. This would
+ deal properly with grouped '\addplot' commands and it allows several
+ optimizations in the coordinate processing (elimination of list allocations).
+
+- document 'bar interval shift' and 'bar interval width'
+
++ document line styles with arrows
+
+- think about quiver plots
+
+- interpolate missing coordinates for stacked plots.
+
+- think about a low-level contour plot interface in which PREPARED contours are
+ provided as input. The contours as such could be computed with an external
+ program (so far).
+
+- the error bar implementation is relatively inefficient. Think about something like
+ '/pgfplots/error bars/prepare drawing'
+ which sets common style keys for every error bar
+
+- think about using a combination of the visualization engine of pgf CVS and my
+ prepared-list-structure. Maybe I can adjust the list format for the current
+ plot type? I need
+ - scatter/line plots 2D
+ - meta coords
+ - quiver may need extra vectors
+ - matrix plots may need twodimensional structure
+ - error bars could be handled more consistently
+ - ...
+ -> implement a visualization class which provides methods
+ - prepare()
+ - visualize()
+ - serialize()
+ - visualizestream()
+ and provide protected pgfplots methods
+ - axis->preprocesscoordinate (filters, logs)
+ - visualizer->prepare()
+ - axis->processcoordinate()
+ - visualizer->serialize()
+ - axis->postprocesscoordinate()
+ The markers as they are implememted now don't really fit into this framework.
+ The clipping region is not really what I want here...
+ Idea: enable/disable clipping separately for each drawing command!
+
+
+- provide 'only each nth coordinate' or so as style on top of 'x filter'.
+
+- 3D axes: my axis is "heavy weighted".
+ Possible improvements:
+ - draw exactly 3 axis lines (unless one really wants the complete box).
+ - draw only one tick line per tick, in a direction which "looks well"
+ (one of the two possible directions).
+ this would also avoid double placing of tick labels in corners.
+ - attach tick labels generally at the end of tick lines. Provide a
+ distance option configuring the distance.
+ -> my idea:
+ - for "normal" orthogonal axes (i.e. view={0,0}), the tick labels
+ are positioned directly at tick positions using proper anchors.
+ - for "non-standard" axes (skewed, rotated, 3D), tick labels are placed
+ at anchor 'center'; but the 'at' position it computed by pgfplots:
+ it is positioned parallel to the surfaces 'b' axes at a predefined
+ distance.
+ - user interface: [xy]ticklabel pos in
+ {left,right,top,bottom,auto,paraxial:<distance>}
+ -> 'auto' implements the behavior above; all other choices are user
+ defined.
+ - automatically decide WHICH axis lines shall be drawn.
+ - see http://mathworld.wolfram.com/EulerAngles.html
+
++ implement simply style 'scatter classes'.
+ + sanity checking feature: try if 'pgfmathfloattofixed' results in a known
+ class! -> but catch exceptions if the value is no number!
+
++ allow symbolic meta data
+
++ provide input options for 'meta' data
+ + plot file
+ + plot table
+ + plot coordinates
+ - document that stuff
+
+- I could extend the clickable library such that a click into a TABLE
+ opens a marker into one (or more) designated plots.
+
++ Optimization: normalize *internal* preprocessed stored point coordinate lists,
+ for example as 'x1,y1,z1,x2,y2,z2,x3,y2,z3,' -> I have 100% control!
+ Maybe it is even faster to re-use these lists for markers than to create a new
+ one.
+
+- I could compute maximum PGF logical coordinates which are then inserted just
+ before qpointxy
+
++ optimize the new code by re-defining \pgfqpointxy for the case of scaled
+ standard unit vectors.
+
+X perhaps I can use pdf line annotations to improve clickable lib?
+ -> no: there are right restrictions when using latex.
+
+- there is a possibility to get that \label/\ref construction to work in
+ conjunction with image externalization: I only need to write those commands
+ into a separate AUX file and make sure they will remain ... even if the
+ generating source has been externalized.
+ The same could be done for javascript features; but that also requires bounding
+ box control.
+
+
+- asymmetric error bars
+
+- Store the axis limits into the axis' node as saved macros. This would allow
+ - 'use [xy] limits of=<axis name>'
+ - access to axis limits from other macros.
+ -> provide a command
+ \pgfplotslimits{current axis}{x}{min}
+ which expands to the 'xmin' limit.
+ PROBLEM: to WHICH limit: the untransformed one? The transformed one? The
+ logarithmized one?
+ -> I can't compute exp(xmin) in log plots!
+ - Ideas:
+ - provide both, if possible. It is NOT possible for log axes.
+ - use log-limits ( possibly combined with 'logxmin=' option ?)
+ - The operation requires several operations because floats need to
+ be converted. Idea: do that only for NAMED AXES.
+ -> all user-interface macros must be expandable!
+ - I don't want to spent time for number format conversions
+ unnecessarily here!
+ - provide \pgfplotslimits and \pgfplotstransformedlimits
+ combined with simpler key-value interfaces
+ - I could also provide access to the unit lengths (they are
+ available as macro anyway)
+ - ALTERNATIVE: implement access to axis limits as a math function
+ which simply defines \pgfmathresult.
+ -> that is probably the most efficient way to do it. I only need to
+ register the new function(s) to PGF MATH.
+ -> PGF 2.00: use \csname pgfmath@parsefunction@\pgfmath@parsedfunctionname\endcsname
+ -> PGF > 2.00: use \pgfmathdeclarefunction
+ Is it possible to provide 'string' arguments which are not
+ parsed? No.
+- I could provide public macros for the data transformations (and inverse
+ transformations). This would also allow relatively simple access to axis
+ limits.
+
+
+
++ I could optimize the number parser with '\csname ...#1\endcsname'
+ constructions where '#1' is the currently identified character.
+ If #1 in {0-9,e,E,+-} etc., I could save a lot of macro assignments and
+ \ifx character comparisons.
+
++ Speaking about optimiziation: I always wanted to test \pgfmathln inside of the
+ log code (combined with float support).
+
++ the 1000sep character should be placed for numbers >= 10000, not before.
+
+- provide predefined style for raised dots as 1000 seps.
+
++ improve scaled ticks: allow manual control over the automatic tick scaling.
+ Idea: accept '[xy]scaled ticks=[false,true,auto,10^<k>,<real>]'
+ + true = auto: as it is now.
+ + false: as it is now.
+ + 10^k : accept an integer shift base 10. Should pose no impl. problem
+ + <real>: use float math and quotients
+
++ it would be interesting to get an high-level coordinate mapping
X : K -> \R
X(k) \in \R is the x-coordinate.
Idea: K can be any type of input, for example
@@ -184,6 +622,42 @@ FEATURES
all output (tick labels) are given in K as well (requires X^{-1}).
-> that's not difficult.
++ a scatter plot feature in which each mark gets its own set of options would be nice.
+ More precisely, a general feature which sets keys according to the current value should be
+ added -> this would also allow a (very early) visualisation of twodimensional functions.
+ Ideas:
+ + linearly map data range to colormap as in matlab. Could use the result of
+ the scaling trafo; no need to work with float here (?)
+ + scope around each marker
+ + The colormap thing is generally useful and may be used in other contexts
+ as well. Ideas:
+ + specification of colormap. An array of colors of size K? A color expression?
+ + providing color coordinates. Use the y coord? Or the z coord? Or
+ an expression of one of them? Maybe I still need high-level math
+ here?
+ + I guess the best is to use the same syntax as for pgfshadings.
+ Then, I will need to map linearly into a shading specification.
+ Technically, it is nothing but piecewise linear interpolation on
+ a non-equidistant grid. To improve lookup speed, I could
+ normalize the input to an equidistant grid. The interpolation
+ procedure involves one lookup operation and one interpolation step
+ between two adjacent color specs (given as RGB).
+ -> FIRST STEP:
+ + define normalized format (RGB, equidistant etc.).
+ + provide lookup + interpolation routine.
+ + force normalized input. Auto-normalizations (conversions) are
+ a second step.
+ + Implement scatter plots based on this spec.
+ + provide a 'color data source' key which is one of
+ 1. 'xyz' (copy coordinate)
+ 2. f(T(x),T(y),T(z)) as expression in transformed range
+ 3. f(x,y,z) as expression in untransformed range (float
+ required)
+ 4. explicit color spec 'c'
+ the cases 3. and 4. need changes in the coordinate preparation
+ routines.
+
+
+ styles are named very unintuitively. I should add something more convenient
(for example like the 'legend style={}' command). Idea: use the *same* name
@@ -199,7 +673,7 @@ FEATURES
- It would be useful to get access to axis coordinates, for example in 'circle (XXX)'
-- axis equal option
++ axis equal option
- consider 'plot image[xmin=,xmax=,ymin=,ymax=] {<graphics>};
-> load external plot image!? Only useful for matlab, if matlab would allow 100%
@@ -234,7 +708,7 @@ X re-implement 'dec sep align' of table package natively, not as high-level
Technical thing: map the CLIPPED data range or the TOTAL data range?
What advantages/disadvantes appear?
-- [Tikz] document how to use internal registers can be used in libraries.
++ [Tikz] document how to use internal registers can be used in libraries.
+ [Tikz] add an 'every plot mark' option and adjust 'mark options' accordingly
@@ -281,7 +755,7 @@ X re-implement 'dec sep align' of table package natively, not as high-level
+ copy my personal' homepages short images to pgfplots website
-- interrupt single plots at discontinuities (for example tan(x))
++ interrupt single plots at discontinuities (for example tan(x))
-> don't draw from +infty to -infty
- optimize plot expression
@@ -295,7 +769,7 @@ X re-implement 'dec sep align' of table package natively, not as high-level
+ the non-boxed axis lines are placed at 'ZERO'. Maybe this zero level should
get an anchor!? -> allows to place axis labels above it
-- default style for axis lines to: {thin, black!25} ?
++ default style for grid lines to: {thin, black!25} ?
X implement an axis as path-command
@@ -401,10 +875,10 @@ X implement an axis as path-command
+ read just strings, no parsing
- optimal: '\t' as separator. How can I teach TeX to use '\t' as
separator!?
- - would allow
+ + would allow
+ \addplot plot table[x=X,y=Z] {\table}
and
- - \typesettable[columns=...,format=sci,...,formatting options=...] {\table}
+ + \typesettable[columns=...,format=sci,...,formatting options=...] {\table}
+ implementation: simple run through column lists
-> CONSISTENT data representation, powerful display options