summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-07-16 23:47:14 +0000
committerKarl Berry <karl@freefriends.org>2010-07-16 23:47:14 +0000
commit0c242425bcb89cc3af3064b8b895608a7f5ec3bb (patch)
treec9e2e2a0cd90b875325b6ef0cc06edada1b5f4ec /Master/texmf-dist/doc/latex/pgfplots
parenta77f52d8c904326838bc0523faffdc79bdff0f6e (diff)
pgfplots 1.4 (14jul10)
git-svn-id: svn://tug.org/texlive/trunk@19488 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/ChangeLog366
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/Makefile11
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdfbin196787 -> 318823 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp1
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex25
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex11
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist1
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex29
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex2
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex118
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex12
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile3
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdfbin3931334 -> 4478260 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex23
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex13
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex5
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex301
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex138
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex479
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex23
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex146
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex38
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex9
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex25
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex1
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex9
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex15
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex2
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.dat0
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.script1
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.table0
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdfbin0 -> 36006 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example5.dat4
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdfbin409499 -> 615434 bytes
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex448
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/texmf.cnf2
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/todo.txt631
37 files changed, 2572 insertions, 320 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
index e39a4175aba..ff3097dc1a4 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
+++ b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
@@ -1,7 +1,211 @@
+2010-07-14 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - RELEASED VERSION 1.4 Release notes:
+ - Added support for detached legends and detached colorbars
+ - ybar (and similar plots) can now be mixed with other plot types
+ like line plots.
+ - improved legend formatting
+ - added 'restrict x to domain*' which cups coordinates outside of a specified domain (same for y and z)
+ - Added support for linear regression
+ - Inline tables,
+ - Lots of bug fixes
+
+
+2010-07-14 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - added sanity checking for empty colorbars.
+ - using colorbar source now implies 'point meta rel=per plot' to get
+ consistency between the plot's colors and the colorbar.
+
+2010-07-10 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - fixed bug: 'xlabels at=edge top' and 'ylabels at=edge right' did not
+ adjust the ticklabel pos.
+ - improved error messages when \usepackage{pgfplotstable} is required
+ - documented (briefly) how '\addplot table[x={create col/.....}] works in the reference
+ for \addplot table
+ - documented and improved 'trim left' / 'trim right' feature (EXPERIMENTAL
+ PGF CVS VERSION REQUIRED)
+ - improved docs for alignment section.
+ - improved docs for 'legend image post style'
+
+2010-07-09 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - fixed bug: the check whether lists are terminated by '\\' failed if '\\'
+ occured within the list. This affected mainly legends and tick label
+ lists.
+ - improved and documented customized legends, including optional
+ appearance keys for specific legend texts
+ |\addlegendentry[<options>]{<text>}| and documentation for multiline
+ legend entries.
+
+2010-07-06 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - the 'colorbar to name' and 'legend to name' features are now implemented
+ using \label. Thus, the common way to insert the resulting pictures is to
+ use \ref -- it works in the same way as any other latex label.
+ - fixed bug: 'clip=false' did not apply to markers.
+
+2010-07-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - groupplots: added support for 'xlabels at=edge top',
+ 'ylabel at=edge right' and adjusted the 'xdescriptions at=edge top' and
+ 'ydescriptions at=edge right' accordingly.
+
+
+2010-07-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - documented linear regression feature in pgfplots.pdf
+
+
+2010-06-29 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - ybar now also supports line plots.
+ - added 'update limits' boolean as shortcut for \pgfplotsinterruptdatabb
+ - wrote \numplotsofactualtype and \plotnumofactualtype (allows to combined
+ bar plots with other plot types (like line plots) --> tests to check
+ combination of bar plots with other plot types would be good)
+ - implemented ybar with these macros
+ - reimplemented key filter such that it allows plot handlers. (might break
+ compatibility with existing images; recompile many old documents to check
+ it)
+
+2010-06-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - fixed bug: 'point meta=f(x)' was evaluated too early. Now it is
+ evaluated inside of \addplot in the survey phase.
+
+2010-06-25 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - fixed bug: 'each nth point' worked only for #1<10
+
+2010-06-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - nodes near coords align now accepts some standard anchor names and
+ appends 'anchor=<value>' automatically.
+
+2010-06-17 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - legend to name: now supports \numplots
+ - added support for \scope/\endscope inside of an axis.
+ - added preliminary support for 'ycomb' and 'ybar'
+
+2010-06-16 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - fixed bug: plot graphics and legends did not work.
+ - fixed bug: providing a colormap inside of \addplot resulted in problems
+ with dimen parsing.
+ - fixed bug: 'every extra [xyz] tick' did not allow all tikz options (I
+ introduced a scope to fix it)
+ - \ref, \pgfplotslegendfromname, \pgfplotscolorbarfromname etc now support
+ separate file names when used with the external library.
+ - fixed bug: colorbars and french babel have been incompatible.
+
+2010-06-11 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - optimized runtime of colormap serialized from O(N^2) to O(N)
+
+2010-06-09 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - fixed bug: the 'every table' style now has higher precedence than
+ options provided in square brackets (the old variant yielded either problems with
+ row sep,col sep keys or with '/.add={}{}' inside of options)
+ - improved compatibility of detached legends/colorbar/\ref legends with
+ external lib
+ - fixed sanity checking for 'table/unique' style and provided meaningful error messages
+
+2010-06-08 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - fixed bug: 'ybar,every node near coord/.append style={scale=0.7}'
+ did not work properly.
+ To do so, I eliminated unnecessary key family assignments
+ - fixed bug: 'nodes near coords' and stacked plots did not work
+ - fixed bug: 'point meta' and stacked plots did not work
+
+2010-05-28 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - reduced save stack usage
+ - linear regression: x value is now determined from context
+ - \addplot table: allowed simple in-line create-on-use specifications
+ like \addplot table[y=create col/linear regression]
+
+2010-05-26 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - added key aliases 'legend reversed' = 'reverse legend' and 'legend
+ transposed' = 'transpose legend'
+ - generation of .dep files is now postponed until it is clear that the
+ file exists.
+ - fixed bug: shader=interp and mesh/ordering=y varies produced corrupted
+ results.
+ - fixed bug: shader=interp consumed too much stack save space.
+
+2010-05-19 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - table package: during lazy column creation, the macro \pgfplotstablename
+ expands to the currently processed table. This is now used as default for
+ linear regression.
+ - \addplot table: read completely now has the default value `auto' which
+ checks for 'create on use'. Thus, you can provide 'create on use' columns
+ in plot sources.
+ - linear regression: the scaling (linear/log) is now taken automatically
+ from an embedding axis.
+ - added 'transpose legend' style
+
+2010-05-10 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added 'legend cell align=left|right|center' styles to reduce the amount
+ of typing for this task.
+
+2010-05-06 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - table package: improved accuracy during gradient loglog.
+ - added possibility to exchange \includegraphics in plot graphics.
+
+2010-05-05 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed handling of colormap mesh width + reinterpolation. It seems it was
+ broken or at least not fully functional.
+ Now it appears to work, is more robust and provides more information on error.
+
+2010-05-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed bug: \addplot table (without '[]') sets 'x index=0,y index=1'
+ instead of using their actual value.
+
+2010-04-29 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - implemented missing \thisrowno (and \nextrowno and \prevrowno) macros
+ inside of \pgfplotstablecreatecol.
+
+2010-04-25 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed bug: named nodes inside of groupplots produced infinite loop
+
+2010-04-22 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed bug: 'enlargelimits' did not properly update axis fields; leading
+ to wrong automatically generated ticks.
+
+2010-04-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - table package: Fixed bug in 'unique' style. It worked only for the first
+ column.
+ - fixed bug: named nodes did not function properly in conjunction with pgf 2.00
+
+2010-04-12 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - added 'restrict x to domain*' which truncates to domain boundaries
+ instead of assigning -inf or +inf.
+
+2010-04-10 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - legend to name and colorbar to name: Improved compatibility with context by introducing proper \protect ion
+
+2010-04-08 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed bug: setting ticklabel pos and axis lines to an incompatible
+ choice discarded tick lines.
+ - colorbar data ranges (point meta min/max) is now provided in scientific
+ notation, not as low level float.
+ - Fixed bug: |colorbar sampled line| and |colorbar left| where
+ incompatible.
+
+2010-04-06 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Added 'colorbar source' feature
+
+2010-04-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed 3D axis scaling inaccuracies (by using float arithmetics)
+
2010-03-31 Christian Feuersaenger <ludewich@users.sourceforge.net>
- Released version 1.3.1
+2010-03-30 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Added 'colorbar sampled' and 'colorbar sampled line'
+
2010-03-25 Christian Feuersaenger <ludewich@users.sourceforge.net>
- Imported all patches to PGF written by Christian Feuersaenger.
@@ -13,11 +217,173 @@
- Fixed bug: overlay did not work properly
- Fixed bug: grids worked only for boxed axes
+ - Now, anchor can also be the value of a named node inside of the axis.
2010-03-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
- Fixed bug: \pgfplotstablesave did not reset 'postproc cell content'
+2010-03-12 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - removed spurious spaces in table package
+
+2010-03-09 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Added |sort| key for tabletypeset.
+
+2010-02-24 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed bug: the auto-generation of .dep files could fail.
+ Now, it will only be generated (automatically) if we are currently
+ externalizing.
+
+2010-02-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added \pgfplotsutilstrcmp
+ - rewrote API for 'iflessthan' of the array sort. It is now a general
+ utility function.
+ - added a lot if styles for comparison functions, among them
+ 'fixed <', 'float <', 'int <', 'string <', 'date <' and corresponding '>'
+ variations.
+ - Fixed bug: the 'date type' was broken due to a missing comma
+
+2010-02-22 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed bug: providing a point meta expression twice as in 'point meta=<expr>, point meta=<expr>' yielded an infinite recursion
+ - Provided first rudimentary version for \pgfplotstablesort
+
+2010-02-18 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - number printing: added 'sci generic' style to customize the appearance
+ of scientific format and a 'verbatim' style which doesn't use TeX macros
+ for the formatted numbers.
+
+2010-02-16 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added 'variance list' to regression feature
+ - added |trim cells| to table input.
+ - the table typesetting routines are now in a separate file.
+ It is now necessary to use \usepackage{pgfplotstable} to use them (as
+ documented).
+
+2010-02-12 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed problem with table prepare catcodes and argument parsing
+ - finished user interface and continued implementation for 'linear
+ regression'
+
+2010-02-10 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - implemented col sep=& (or col sep=ampersand)
+ - added support for 'linear regression'
+
+2010-02-09 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Added support for inline data as argument to
+ \pgfplotstableread{
+ row
+ row2
+ }{\macro}
+ - inline tables are now accepted directly for \addplot table and
+ \pgfplotstabletypeset
+
+2010-02-08 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Added choice 'point meta={TeX Code={\def\pgfplotspointmeta{42}}}' and
+ 'TeX code symbolic'.
+
+2010-02-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed problem with spurious white space occuring during table input command
+
+2010-02-02 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Added 'numeric type' to table package to switch back from string type or
+ data type.
+ - added 'numeric as string type' to table package.
+
+2010-01-26 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Introduced 'compat=1.3' . The name 'compat=newest' was not not such a
+ good idea since it might introduce a problem for following releases.
+ - Emphasized key names in references to show that /pgfplots/, /tikz/ and
+ similar prefixes are unnecessary.
+ - Fixed the 'xticklabels' key such that it also accepts '\\' terminated
+ lists. This fixes strange bugs with dots '.' as last characters in
+ entries.
+
+2010-01-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added sanity checks such that 'xmin/max' and friends can't be invoked
+ within an \addplot.
+ - plot gnuplot: added user customizable styles to change the dummy
+ variables. The initial config will now use 'x' for 1d, 'x,y' for 2d, 't'
+ for 1d parametric and 'u,v' for 2d parametric plots.
+ - fixed bug: one couldn't use different log/normal scalings in a group
+ plot. Relaxed sanity checking here.
+ - added docs for |variable| and |variable y| which appeared to be missing.
+
+2010-01-14 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed that '\addlegendimage' did not respect the every plot styles.
+ - added 'every legend image post' style.
+
+2010-01-26 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Introduced 'compat=1.3' . The name 'compat=newest' was not not such a
+ good idea since it might introduce a problem for following releases.
+ - Emphasized key names in references to show that /pgfplots/, /tikz/ and
+ similar prefixes are unnecessary.
+ - Added character lists |table/ignore chars| and |table/white space chars|
+ to handle special characters in input files.
+ - Fixed the 'xticklabels' key such that it also accepts '\\' terminated
+ lists. This fixes strange bugs with dots '.' as last characters in
+ entries.
+
+2010-01-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+ - added sanity checks such that 'xmin/max' and friends can't be invoked
+ within an \addplot.
+ - plot gnuplot: added user customizable styles to change the dummy
+ variables. The initial config will now use 'x' for 1d, 'x,y' for 2d, 't'
+ for 1d parametric and 'u,v' for 2d parametric plots.
+ - fixed bug: one couldn't use different log/normal scalings in a group
+ plot. Relaxed sanity checking here.
+ - added docs for |variable| and |variable y| which appeared to be missing.
+
+2010-01-15 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - added support to generate makefile dependencies for pgfplots input files
+ automatically
+
+2010-01-14 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - fixed that '\addlegendimage' did not respect the every plot styles.
+ - added 'every legend image post' style.
+
+
+>>>>>>>
+2010-03-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed bug: \pgfplotstablesave did not reset 'postproc cell content'
+
+2010-03-22 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed bug: \pgfplotstablesave did not reset 'include outfiles'
+ - Added 'colorbar to name' feature: no, colorbars can be placed
+ independently of an axis, even into the document's main text.
+
+2010-03-19 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - changed 'legend to macro' to 'legend to name'.
+
+2010-03-18 Christian Feuersaenger <ludewich@users.sourceforge.net>
+
+ - Fixed bug: axis descriptions for |small| and |footnotesize| styles were
+ too large
+ - added |tiny| style
+ - added |legend to macro|, a method to export the legend to a macro which
+ can be used *outside* of the axis where it belongs to.
+
2010-03-16 Christian Feuersaenger <ludewich@users.sourceforge.net>
- Fixed bug: 'draw=none' wasn't handled correctly.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/Makefile b/Master/texmf-dist/doc/latex/pgfplots/Makefile
index 576def59f2f..daed5651ffe 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/Makefile
+++ b/Master/texmf-dist/doc/latex/pgfplots/Makefile
@@ -8,18 +8,23 @@ notes: TeX-programming-notes.pdf
pgfplots: pgfplots.pdf
pgfplotstable: pgfplotstable.pdf
-%.pdf: update-git-hooks FORCE
+include pgfplots.makefile
+
+%.pdf: FORCE
mkdir -p gnuplot
@export TEXMFCNF=.: && $(PDFLATEX) $(@:.pdf=.tex)
@bibtex $(@:.pdf=) || exit 0
@makeindex $(@:.pdf=) || exit 0
@echo ""
@echo "$@ compiled successfully. You may need to re-run make several times to get all cross-references right."
+
+pgfplots.pdf: $(ALL_FIGURES)
+
+pgfplots.makefile:
+ @export TEXMFCNF=.: && $(PDFLATEX) pgfplots
clean:
rm -f *.aux *.ind *.idx *.toc *.out *.log *.ilg *.dvi pgfplots.pdf pgfplotstable.pdf *.djs *.bbl *.blg figures/expensiveexample*
-update-git-hooks:
- @
FORCE:
diff --git a/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf
index adc6b7268fa..fb1a4b62ce7 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp
new file mode 100644
index 00000000000..8cea9808f2c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp
@@ -0,0 +1 @@
+gnuplot 4.2 patchlevel 6
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
index 037fd69d3eb..92a024a6035 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
@@ -21,7 +21,6 @@
\makeatother
}%
-
\makeatletter
\def\pgfplotsmakefilelinkifuseful#1#2{%
\protect\pgfplotsmakefilelinkifuseful@{#1}{#2}%
@@ -255,6 +254,30 @@
{
\end{pgfmanualentry}
}
+\newenvironment{codeargskey}[2]{%
+ \begin{pgfmanualentry}
+ {\toks0={#2}%
+ \xdef\argpattern{\the\toks0 }%
+ }%
+ \pgfmanual@command@to@string\argpattern\argpattern
+ \pgfmanualentryheadline{{\ttfamily\declarekey{#1}\textcolor{gray}{/\pgfmanualpdfref{/handlers/.code}{.code args}}=\texttt{\{\argpattern\}}\marg{...}}\hfill}%
+ \def\mykey{#1}%
+ \def\mypath{}%
+ \def\myname{}%
+ \firsttimetrue%
+ \decompose#1/\nil%
+ \pgfmanualbody
+}
+{
+ \end{pgfmanualentry}
+}
+\def\pgfmanual@command@to@string#1#2{%
+ \expandafter\pgfmanual@command@to@string@@\meaning#1\pgfmanual@EOI{#2}%
+}%
+\xdef\pgfmanual@glob@TMPa{\meaning\pgfutil@empty}%
+\expandafter\def\expandafter\pgfmanual@command@to@string@@\pgfmanual@glob@TMPa#1\pgfmanual@EOI#2{%
+ \def#2{#1}%
+}%
\newenvironment{pgfplotscodekey}[1]{%
\begin{codekey}{/pgfplots/#1}%
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
index bb705ef1831..a51bcaed5b8 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
@@ -127,12 +127,19 @@ Generates pretty--printed output\footnote{This method was previously \texttt{\te
The number is printed using the current number printing options, see the manual of \PGFPlotstable\ which comes with this package for the different number styles, rounding precision and rounding methods.
\end{command}
+\begin{command}{\numplots}
+ Inside of any of the axis environments, associated style, option or command, |\numplots| expands to the total number of plots.
+\end{command}
+\begin{command}{\numplotsofactualtype}
+ Like |\numplots|, this macro returns the total number of plots which have the same plot handler. Thus, if you have |sharp plot| active, it returns the number of all |sharp plots|. If you have |ybar| active, it returns the number of |ybar| plots and so on.
+\end{command}
+
\begin{command}{\plotnum}
Inside of |\addplot| or any associated style, option or command, |\plotnum| expands to the current plot's number, starting with~$0$.
\end{command}
-\begin{command}{\numplots}
- Inside of any of the axis environments, associated style, option or command, |\numplots| expands to the total number of plots.
+\begin{command}{\plotnumofactualtype}
+ Like |\plotnum|, but it returns the number among all plots of the same type (see |\numplotsofactualtype|).
\end{command}
\begin{command}{\coordindex}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist
index acc4eee1e0f..cea2b0e7b56 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist
@@ -45,3 +45,4 @@ figures/expensiveexamplepgfplots-figure43
figures/expensiveexamplepgfplots-figure44
figures/expensiveexamplepgfplots-figure45
figures/expensiveexamplepgfplots-figure46
+figures/expensiveexamplepgfplots-figure47
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
index ac8b4ba4bcb..87c87058fc1 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
@@ -190,6 +190,12 @@ pdflatex -shell-escape main
\end{codeexample}
\end{command}
+\begin{command}{\tikzappendtofigurename\marg{suffix}}
+ Appends \meta{suffix} to the actual value of |figure name|.
+
+ It is a shortcut for |\tikzset{external/figure name/.add={}|\marg{suffix}|}| (a shortcut which is also supported if \tikzname\ is not installed, see below).
+\end{command}
+
\begin{key}{/tikz/external/system call=\marg{template}}
\label{extlib:systemcall:option}
@@ -217,6 +223,29 @@ pdflatex -shell-escape main
Contains the command line option for |latex| which enables the |\write18| feature. For \TeX-Live, this is |-shell-escape|. For Mik\TeX, you should use |\tikzexternalize[shell escape=-enable-write18]|.
\end{key}
+\paragraph{Support for Labels and References In External Files}
+The |external| library comes with extra support for |\label| and |\ref| (and other commands which usually store information in the |.aux| file) inside of external files.
+
+There are, however, some points which need your attention when you try to use
+\begin{enumerate}
+ \item[a)] |\ref| to something in the main document inside of an externalized graphics or
+ \item[b)] |\label| in the externalized graphics which is referenced in the main document.
+\end{enumerate}
+
+For point a), a |\ref| inside of an externalized graphics works \emph{only} if you issue the required system call \emph{manually} or by |make|. The initial configuration |mode=convert with system call| does \emph{not} support |\ref|. But you can copy--paste the system call generated by |mode=convert with system call| and issue it manually. The reason is that |\ref| information is stored in the main |.aux| file -- but this auxiliary file is not completely written when |mode=convert with system call| is invoked (there is a race condition). Note that |\pageref| is not supported (sorry). Thus: if you have |\ref| inside of external graphics, consider using |mode=list and make| or copy--paste the system call for the image(s) and issue it manually.
+
+Point b) is realized automatically by the external library. In detail, a |\label| inside of an externalized graphics causes the external library to generate separate auxiliary files for every external image. These files are called \meta{imagename}|.dpth|. The extension |.dpth| indicates that the file also contains the image's depth (the |baseline| key of \tikzname). Furthermore, anything which would have been written to an |.aux| file will be redirected to the |.dpth| file -- but only things which occur inside of the externalized |tikzpicture| environment. When the main document loads the image, it will copy the |.dpth| file into the main |.aux| file. Then, successive compilations of the main document contain the external |\label| information. In other words, a |\label| in an external graphics needs the following work flow:
+\begin{enumerate}
+ \item The external graphics needs to be generated together with its |.dpth| (usually automatically by \tikzname).
+ \item The main document includes the external graphics and copies the |.dpth| content into its main |.aux| file.
+ \item The main document needs to be translated one further time to re-read its |.aux| file\footnote{Note that it is not possible to activate the content of an auxiliary file after \texttt{\textbackslash begin\{document\}} in \LaTeX.}.
+\end{enumerate}
+There is just one special case which occurs if a |\label|/|\ref| combination is realized itsself by a |tikzpicture|. This is, for example, the case for the legend |\ref| images or for the |\pgfplotslegendfromname| feature. In such cases, you need to proceed as for case a) since |mode=convert with system call| can't handle that stuff on its own.
+
+In other words: a |\label| in an external document works automatically, just translate the main document often enough. A |\ref| might need manual adjustments as described for case a) above.
+
+
+\paragraph{Operation Modes}
\begin{key}{/tikz/external/mode=\mchoice{convert with system call,list and make,$\dotsc$} (initially convert with system call)}
This allows to change the default operation mode. There are a handful of choices possible, all of them are described in detail in~\cite[section ``Externalization Library'']{tikz}. The most useful ones are probably the initial configuration |convert with system call| and the specialized choice |list and make|.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
index ec1686dadfb..a66239c4b25 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
@@ -271,7 +271,7 @@ then we can plot |Cost| versus |Error| using
The first plot employs inline coordinates; the second one reads numerical data from file and plots column `|Cost|' versus `|Error|'.
\noindent
-Besided the environment ``|loglogaxis|'' you can use
+Besides the environment ``|loglogaxis|'' you can use
\begin{itemize}
\item |\begin{axis}...\end{axis}| for normal plots,
\item |\begin{semilogxaxis}...\end{semilogxaxis}| for plots which have a normal~$y$ axis and a logarithmic~$x$ axis,
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex
index 056f80c7334..ed18c1a5ffe 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex
@@ -1,15 +1,18 @@
\subsection{Grouping plots}
+{
\label{sec:group:plot}
{\noindent {\emph{by Nick Papior Andersen}}}
\index{Group library!Subplots}%
+\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/group/,}{}}
+
\begin{pgfplotslibrary}{groupplots}
A library which allows the user to typeset several plots in a matrix like structure.
Often one has to compare two plots to one another, or you simply need to display two plots in conjunction with each other. Either way the following
- section describes this library which makes this typesetting easy.
+ section describes this library which makes matrix structure easier than alternative methods discussed in Section~\ref{sec:pgfplots:arrayform}.
\end{pgfplotslibrary}
\begin{environment}{{groupplot}\oarg{options}}
@@ -53,11 +56,11 @@ With such an environment one can typeset plots in matrix like styles
The equivalent code is seen as the second example and it is clear that you have to type a lot less. So how do you use it?
First of all you need to utilize the new environment |groupplot|. Within this environment the following command works.
-\begin{command}{\nextgroupplot\oarg{options} \meta{normal plot commands}}
+\begin{command}{\nextgroupplot\oarg{axis options} \meta{normal plot commands}}
\label{cmd:pgfplots:nextgroupplot}
This command shifts the placement of the plot. Therefore one should always start the environment |groupplot| with the command
-\textbackslash|nextgroupplot| in order to create the first plot. The \oarg{options} are the options that are supplied to the following plot commands until
-the next \textbackslash|nextgroupplot| command is seen by \TeX.
+|\nextgroupplot| in order to create the first plot. The \oarg{axis options} are the options that are supplied to the following axes until
+the next |\nextgroupplot| command is seen by \TeX.
The order in which figures are typeset are as seen in the next example.
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
@@ -131,17 +134,19 @@ Or for instance zooming in on data as in the next example.
\subsubsection{Grouping options}
\label{sec:pgfplots:group:options}
-Here the various available options of the library resides.
+Here the various available options of the library reside.
+
+\begin{pgfplotskey}{group style=\marg{options with {\normalfont\texttt{group/}} prefix}}
+ This key sets all \meta{options} using the |/pgfplots/group/| prefix.
+
+ Note that the distinction between |group/| and normal options is important has some of them are quite similar.
-\begin{pgfplotskey}{group style=group/.cd,\marg{options}}
- This key allows one to faster reach the group options. Some of the options are very similar to the normal commands so they are supplied in another
- subdirectory |group|. So the following are equivalent.
+ For example, the following statements are all equivalent:
\begin{codeexample}[code only]
\pgfplotsset{group style={a=2,b=3}}
\pgfplotsset{group/a=2,group/b=3}
\pgfplotsset{group/.cd,a=2,b=3}
\end{codeexample}
-It can thus decrease the size of your options with out destroying the clearness of where options belong.
\end{pgfplotskey}
All the following keys are in the subdirectory |group|.
@@ -149,7 +154,7 @@ All the following keys are in the subdirectory |group|.
group/columns=\meta{columns} (initially 1),
group/rows=\meta{rows} (initially 1)}
These keys determines the total number of plots that can be in one environment |groupplot|. It is thus important not to add more
- \textbackslash|nextgroupplot| in the environment than \meta{columns}$\times$\meta{rows}. This is critical to set if one uses more than 1 more plot. As
+ |\nextgroupplot| in the environment than \meta{columns}$\times$\meta{rows}. This is critical to set if one uses more than 1 more plot. As
the key |group size| uses |columns| and |rows| you should stick to either |group size| or both |columns| and |rows|.
\end{pgfplotskeylist}
@@ -163,8 +168,46 @@ All the following keys are in the subdirectory |group|.
This style is used on every plot as the first style. It is thus equivalent as \meta{options} in the |groupplot| environment.
\end{pgfplotskey}
-\begin{pgfplotskeylist}{group/xticklabels at=\mchoice{all,edge top,edge bottom} (initially all),%
- group/yticklabels at=\mchoice{all,edge left,edge right} (initially all)}
+\begin{pgfplotskeylist}{%
+ group/xlabels at=\mchoice{all,edge bottom,edge top} (initially all),%
+ group/ylabels at=\mchoice{all,edge left,edge right} (initially all)}
+ In order to determine which plots get labels typeset one can use these keys. By default all axis gets typeset normally and thus have both $x$ and
+ $y$ axis labels.
+% \usepgfplotslibrary{groupplots}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{groupplot}[
+ group style={
+ group name=my plots,
+ group size=2 by 2,
+ xlabels at=edge bottom,
+ ylabels at=edge left,
+ },
+ footnotesize,
+ width=4cm,
+ height=4cm,
+ %
+ xlabel=time $t$ / h,
+ ylabel=$c$ / mol/L,
+ ]
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \end{groupplot}
+\end{tikzpicture}
+\end{codeexample}
+In the example above, only the bottom row gets the label defined in the beginning |groupplot|-environment on the $x$ axis and only the first column of plots gets labels on the
+$y$ axis on their left side. These keys are especially handy when using \textit{glued} plots.
+\end{pgfplotskeylist}
+
+\begin{pgfplotskeylist}{%
+ group/xticklabels at=\mchoice{all,edge top,edge bottom} (initially all),%
+ group/yticklabels at=\mchoice{all,edge left,edge right} (initially all)}
In order to determine which plots get tick labels typeset one can use these keys. By default all axis gets typeset normally and thus have both $x$ and
$y$ axis tick labels. If one sets
@@ -173,6 +216,52 @@ All the following keys are in the subdirectory |group|.
\end{codeexample}
only the bottom row gets tick labels on the $x$ axis and only the last column gets tick labels on the $y$ axis on their right side. These keys are
specially handy when using \textit{glued} plots.
+
+ Keep in mind that this is implies the same ticks for all plots.
+\end{pgfplotskeylist}
+
+\begin{pgfplotskeylist}{%
+ group/x descriptions at=\mchoice{all,edge top,edge bottom} (initially all),%
+ group/y descriptions at=\mchoice{all,edge left,edge right} (initially all)}
+ These are simply a short hand for both using both |xticklabels at| and |xlabels at| simultaneously:
+
+% \usepgfplotslibrary{groupplots}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{groupplot}[
+ group style={
+ group name=my plots,
+ group size=2 by 2,
+ %
+ x descriptions at=edge bottom,
+ y descriptions at=edge right,
+ horizontal sep=0.5cm,
+ vertical sep=0.5cm,
+ },
+ footnotesize,
+ width=4cm,
+ height=4cm,
+ %
+ xlabel=time $t$ / h,
+ ylabel=$c$ / mol/L,
+ ]
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \nextgroupplot
+ \addplot coordinates{(0,0) (1,2) (2,1)};
+ \end{groupplot}
+\end{tikzpicture}
+\end{codeexample}
+
+Here, |x descriptions at=edge bottom| yields that $x$ descriptions (|xlabel| and |xticklabel|) are only used for the lowest row. Furthermore, |y descriptions at=edge right| places $y$ descriptions only for the rightmost column. Consider modifying the |horizontal sep| and |vertical sep| for your needs.
+
+ As for |xticklabels at|, usage of this key implies the same ticks for all plots.
+
+ This might \emph{require} |compat=1.3| (or newer).
\end{pgfplotskeylist}
\begin{pgfplotskey}{group/group name=\marg{name} (initially group)}
@@ -205,7 +294,7 @@ specially handy when using \textit{glued} plots.
\end{pgfplotskey}
\begin{pgfplotskey}{group/empty plot/.style=\marg{style} (initially /pgfplots/hide axis)}
- This key can be used as an option to the command \textbackslash|nextgroupplot|. This makes the next plot invisible (only the axes) but maintains it anchors and
+ This key can be used as an option to the command |\nextgroupplot|. This makes the next plot invisible (only the axes) but maintains it anchors and
name. If you want it to behave in another style then you can redefine it. Consider the same example as before.
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
@@ -231,5 +320,6 @@ specially handy when using \textit{glued} plots.
circle (3pt) node {North west};
\end{tikzpicture}
\end{codeexample}
-Notice that you need to call a \textbackslash|nextgroupplot| again after to jump to the next plot.
+Notice that you need to call a |\nextgroupplot| again after to jump to the next plot.
\end{pgfplotskey}
+}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex
index 0049ec089bf..fb3692ea979 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex
@@ -67,10 +67,16 @@ This section describes some libraries which come with \PGFPlots, but they are mo
\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 together with the |external| library and other image externalization methods of section~\ref{sec:pgfplots:importexport}.
+ \item Up to now, it is \emph{not} possible to use this library together with the |external| library and other 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.
+ To be more precise, you can (with two extra preamble lines, see below) get correctly annotated, exported \pdf\ documents, but the |\includegraphics| command does not import the dynamic features.
+
+ In case you decide to use this work--around, you need to insert
+\begin{codeexample}[code only]
+% \maxdeadcycles=10000 % in case you get the error `Output loop---<N> consecutive dead cycles.'
+\usepackage[pdftex]{eforms}
+\end{codeexample}
+ \noindent \emph{before} loading \pgfname, \Tikz\ or \PGFPlots. The |\maxdeadcycles| appears to be necessary for large documents, try it out.
As long as you are working on a draft version of your document, you might want to use
\begin{codeexample}[code only]
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile
index 1f9688988df..5d37416311e 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile
@@ -152,3 +152,6 @@ figures/expensiveexamplepgfplots-figure45.pdf:
figures/expensiveexamplepgfplots-figure46.pdf:
pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure46" "pgfplots"
+figures/expensiveexamplepgfplots-figure47.pdf:
+ pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure47" "pgfplots"
+
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf
index 238d646785b..ffa57bd68ab 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 8d2bf40ada7..f062f124be0 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
@@ -53,6 +53,25 @@
\let\@wrindex=\@old@wrindex
\makeatother
+
+\makeatletter
+% disables colorlinks for all following \ref commands
+\def\pgfplotsmanualdisablecolorforref{%
+ \pgfutil@ifundefined{pgfplotsmanual@oldref}{%
+ \let\pgfplotsmanual@oldref=\ref
+ }{}%
+ \def\ref##1{%
+ \begingroup
+ \let\Hy@colorlink=\pgfplots@disabled@Hy@colorlink
+ \let\Hy@endcolorlink=\pgfplots@disabled@Hy@endcolorlink
+ \pgfplotsmanual@oldref{##1}%
+ \endgroup
+ }%
+}%
+\def\pgfplots@disabled@Hy@colorlink#1{\begingroup}%
+\def\pgfplots@disabled@Hy@endcolorlink{\endgroup}%
+\makeatother
+
% Formatiere Seitennummern im Index:
\newcommand{\indexpageno}[1]{%
{\bfseries\hyperpage{#1}}%
@@ -92,6 +111,7 @@
\fi
%\def\pgfsysdriver{pgfsys-pdftex.def}
\usepackage{pgfplots}
+\usepackage{pgfplotstable}
\ifpdf
% this allows to disable the clickable lib from command line using
@@ -115,6 +135,7 @@
\usepackage[latin1]{inputenc}
\usepackage{amsmath}
\usepackage{eurosym}
+\usepackage{nicefrac}
\input{pgfplots-macros}
\usepackage{nicefrac}
@@ -155,7 +176,7 @@
\pgfqkeys{/codeexample}{%
every codeexample/.append style={
width=8cm,
- /pgfplots/every axis/.append style={legend style={fill=graphicbackground}}
+ /pgfplots/legend style={fill=graphicbackground}
},
tabsize=4,
}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex
index cb55235b94d..1eccd01e5c9 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex
@@ -161,9 +161,9 @@ The style is defined as follows.
/pgf/bar shift={%
% total width = n*w + (n-1)*skip
% i.e. subtract half for centering
- -0.5*(\numplots*\pgfplotbarwidth + (\numplots-1)*#1) +
+ -0.5*(\numplotsofactualtype*\pgfplotbarwidth + (\numplotsofactualtype-1)*#1) +
% the '0.5*w' is for centering
- (.5+\plotnum)*\pgfplotbarwidth + \plotnum*#1%
+ (.5+\plotnumofactualtype)*\pgfplotbarwidth + \plotnumofactualtype*#1%
},
},
}
@@ -207,11 +207,16 @@ The formular for |bar shift| assigns shifts dependent on the total number of plo
\addplot
coordinates {(1930,15e6) (1940,12e6)
(1950,13e6) (1960,25e6) (1970,35e6)};
-\legend{Far,Near,Here}
+
+\addplot[red,sharp plot,update limits=false]
+ coordinates {(1910,4.3e7) (1990,4.3e7)}
+ node[above] at (axis cs:1950,4.3e7) {Houses};
+
+\legend{Far,Near,Here,Annot}
\end{axis}
\end{tikzpicture}
\end{codeexample}
-Here |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not to a single plot.
+Here |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not to a single plot. The style affects the first three |\addplot| commands. Note that it shifts them horizontally around the plot coordinates. The fourth |\addplot| command is some kind of annotation which doesn't |update limits|.
As for |xbar|, the bar width and shift can be configured with |bar width| and |bar shift|. However, the bar shift is better provided as argument to |/pgfplots/ybar| since this style will overwrite the bar shift. Thus, prefer |/pgfplots/ybar=4pt| to set the bar shift.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex
index 05c431c0588..d518cddce4b 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex
@@ -313,6 +313,7 @@ A more sophisticated example is to draw the approximated function as a |surf| pl
% `pgfplotsexample4.dat' contains similar data as in
% `pgfplotsexample4_grid.dat', but it uses a uniform
% matrix structure (same number of points in every scanline).
+ % See examples above for extracts.
\addplot3[surf,mesh/ordering=y varies]
table {plotdata/pgfplotsexample4.dat};
\addplot3[scatter,scatter src=\thisrow{f(x)},only marks, z filter/.code={\def\pgfmathresult{1.4}}]
@@ -328,7 +329,7 @@ A more sophisticated example is to draw the approximated function as a |surf| pl
\noindent to get exactly the same effect. Choose whatever you like best. The |z filter| works for every coordinate input routine, the |z expr| feature is only available for |plot table|.
-The following example uses |mark=cube*| and |z buffer=sort| to place boxes at each input coordinate. Each boxes color is determines by |point meta={x+y+3}|, so the sum of the input coordinates determines the colors. The remaining keys are just for pretty printing.
+The following example uses |mark=cube*| and |z buffer=sort| to place boxes at each input coordinate. The color for each box is determined by |point meta={x+y+3}|. The remaining keys are just for pretty printing.
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
@@ -566,7 +567,7 @@ The following example uses |mark=cube*| and |z buffer=sort| to place boxes at ea
\end{description}
The choice |flat| is actually the same as |flat mean|. Please note that |shader=flat mean| and |shader=flat corner| also influence mesh plots -- the choices determine the mesh segment color.
- Another choice is |shader=interp| which uses Goraud shading (bilinear interpolation) to fill the segments.
+ Another choice is |shader=|\declareandlabel{interp} which uses Goraud shading (smooth linear interpolation of two triangles approximating rectangles) to fill the segments.
\pgfplotsexpensiveexample
\begin{codeexample}[]
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex
index 9386714999c..593f7961b80 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex
@@ -128,7 +128,37 @@ And finally, we have origin anchors which are especially useful when axis lines
\showit{origin}{135}
\end{tikzpicture}
\end{center}
-The default value is |anchor=south west|. You can use anchors in conjunction with the \Tikz\ |baseline| option and/or |\begin{pgfinterruptboundingbox}| to perform alignment.
+
+ \noindent There is a fifth anchor which is not directly related to the axis: you can provide the anchor of \emph{a named inner node}. Thus, you can define your own anchor, by writing |\node (|\meta{name}|) at |\parg{point coordinate}| {};| as follows (using the |baseline| option described below):
+\begin{codeexample}[]
+Aligning at .......
+\begin{tikzpicture}[baseline]
+\begin{axis}[small,anchor=aninnernode.center]
+ \addplot {sin(deg(x))};
+ \node
+ [pin=-90:(aninnernode),fill=black,circle,scale=0.3]
+ (aninnernode) at (axis cs:-2,0.75) {};
+ \draw[help lines] (axis cs:-6,0.75) -- (axis cs:6,0.75);
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent What happens is that a node is placed at |(axis cs:-2,0.75)|. Note that the options |[pin=...]| are merely to show the |\node| (the pin style has been defined by the \PGFPlots\ manual). Since a name can also be assigned using |name=|\meta{node's name} and since any \PGFPlots\ description is also a |\node|, you can align your plot at selected axis descriptions:
+\begin{codeexample}[]
+Aligning at .......
+\begin{tikzpicture}[baseline]
+\begin{axis}[
+ small,
+ title={The function $\sin x$ is very pretty.},
+ title style={name=MyTitleNode},
+ anchor=MyTitleNode.base,
+]
+ \addplot {sin(deg(x))};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+The default value is |anchor=south west|.
+You can use anchors in conjunction with the \Tikz\ |baseline| option and/or |\begin{pgfinterruptboundingbox}| to perform alignment.
\paragraph{Remarks:} Each of the anchors on the axis rectangle has an equivalent to a coordinate in the |axis description cs| described in section~\ref{pgfplots:sec:axis:description:cs}. That means the first set of anchors actually lives on the \emph{tight bounding box around the axis} (without any ticks or descriptions). The |south west| anchor will always be the lower left corner of this bounding box, even in case of a rotated or skewed coordinate system\footnote{Note that this is only true for versions since 1.3.}. Similar statements hold for the other anchors.
}
@@ -180,7 +210,14 @@ The |baseline| key is related to |\begin{minipage}|\oarg{align how} or |\begin{t
\subsubsection{Horizontal Alignment}
\label{sec:halign}%
-If you place multiple |axes| into a single |tikzpicture| and use the `|anchor|'-option, you can control horizontal alignment:
+Horizontal alignment can be done in two ways:
+\begin{enumerate}
+ \item Using separate |tikzpicture| environments which have reduced bounding boxes or
+ \item A single |tikzpicture| environment in which the complete alignment is done.
+\end{enumerate}
+The first approach requires the use of reduced bounding boxes and is discussed in Section~\ref{sec:bb}.
+
+The second approach, a single |tikzpicture| environment, employs the |at| and |anchor| keys to align parts of the images. For example, if you place multiple |axes| into a single |tikzpicture| and use the `|anchor|'-option, you can control horizontal alignment:
\begin{codeexample}[]
\begin{tikzpicture}
\pgfplotsset{every axis/.append style={
@@ -202,11 +239,8 @@ cycle list={
(0.109967, 1.000027)};
\end{axis}
-% introduce named coordinate:
-\path (main plot.below south west) ++(0,-0.1cm)
- coordinate (lower plot position);
-
-\begin{axis}[at={(lower plot position)},
+\begin{axis}[
+ at={(main plot.below south west)},yshift=-0.1cm,
anchor=north west,
width=4cm,scale only axis,height=0.8cm,
ytick=\empty]
@@ -220,13 +254,153 @@ cycle list={
\end{codeexample}
+\subsubsection{Alignment In Array Form (Subplots)}
+\label{sec:pgfplots:arrayform}
+\index{Subplots}%
+\index{Alignment!Subplots}%
+\index{Alignment!Array}%
+\index{array!Array Alignment}%
+\pgfmanualpdflabel{\textbackslash matrix}{}%
+Sometimes multiple alignment axes in array form are desired. \PGFPlots\ supports this task in several ways which are described in the following. There are basically three related, yet different, approaches:
+\begin{enumerate}
+ \item Simply place |\begin{tikzpicture}...\end{tikzpicture}| into a \LaTeX\ table.
+ This is straight--forward; you would do the very same thing with |\includegraphics|.
+
+ In addition to |\includegraphics|, the |baseline| feature allows simple yet effective vertical alignment. At the time of this writing, the experimental \PGF\ version available from |texexample.net| also supports the |trim left| and |trim right| features which allow simple yet effective horizontal alignment (see below).
+
+ \item Use a \emph{single} picture which contains an array of axes, i.e.\ a pattern like
+
+ |\begin{tikzpicture} \matrix{ |\meta{multiple axes}|}; \end{tikzpicture}|.
+
+ This allows considerably simpler alignment! Alas, it needs special handling for |legend entries| due to a weakness of |\matrix|. If you use the |external| library (which is recommended), it takes more time since the picture gets larger.
+
+ \item Use the |groupplots| library shipped with \PGFPlots. It is specialized on axes in array form with particular strength if the axes are closely related (for example if they share axis descriptions like |xlabel| or even tick labels). Note, however, that the other approaches are better when it comes to automatic handling of bounding boxes.
+\end{enumerate}
+The |groupplots| library is discussed in all detail in Section~\ref{sec:group:plot}. This section discusses the other two approaches.
+
+
+\paragraph{Array Alignment using \LaTeX\ Tables}
+The idea is simple: use a \LaTeX\ table and provide one |tikzpicture| for every cell. You are probably familiar with this sort of alignment, perhaps together with |\includegraphics|. It works in the very same way for \PGFPlots. The approach is the simplest one since it doesn't need special knowledge. Its disadvantage, however, is more difficulty to control positions \emph{inside} of the image (like differently sized axis descriptions).
+
+Is is strongly recommended to employ the |baseline| option for each cell picture, which simplifies vertical alignment considerably. If you want a simple solution to place separate axes in array form, and you prefer to use one |tikzpicture| for every axis, the probably most simple and most effective way to realize horizontal alignment is the |trim left| and |trim right| feature. Unfortunately, it will only be available as part of the \emph{next} stable \PGF\ release (or available as part of the experimental \PGF\ version from |texample.net|). Since I am aware of many users who downloaded the experimental \PGF\ version, I document it here as well.
+
+The |trim left| feature can be used to exclude axis descriptions on the left from the bounding box, and the |trim right| can exclude axis descriptions on the right from the bounding box. Thus, alignment is done using the vertical axis lines. Since both keys effectively modify the bounding box, they are documented in Section~\ref{sec:bb} ``Bounding Box Restrictions''. Here is just a small example for array alignment by means of |tabular|, |baseline| and the |trim| features:
+
+\begin{codeexample}[vbox]
+\pgfplotsset{
+ small,
+ title=Requires experimental PGF!
+}
+\begin{center}
+\begin{tabular}{rl}
+ \begin{tikzpicture}[baseline,trim axis left]
+ \begin{axis}
+ \addplot {x};
+ \end{axis}
+ \end{tikzpicture}
+ &
+ \begin{tikzpicture}[baseline,trim axis right]
+ \begin{axis}[
+ ylabel={$f(x)=x^2$},
+ yticklabel pos=right,
+ ylabel style={font=\Huge}]
+ \addplot {x^2};
+ \end{axis}
+ \end{tikzpicture}
+ \\
+ %
+ \begin{tikzpicture}[baseline,trim axis left]
+ \begin{axis}[xlabel=$x$,xlabel style={font=\Huge}]
+ \addplot {x^3};
+ \end{axis}
+ \end{tikzpicture}%
+ &
+ \begin{tikzpicture}[baseline,trim axis right]
+ \begin{axis}[yticklabel pos=right]
+ \addplot {x^4};
+ \end{axis}
+ \end{tikzpicture}%
+ \\
+\end{tabular}%
+\end{center}
+\end{codeexample}
+\noindent The example has $2 \times 2$ axes. The |baseline| feature controls the vertical alignment: the lower axis lines are always on the same height. The |trim axis left| key is a style which tells \Tikz\ to trim everything which is left of the left axis line. Similarly, the |trim axis right| key does not include picture parts right of the right axis line. Together with |\begin{center}| and the |yticklabel pos=right| key, we get correct horizontal and vertical alignment together with centering at the left- and right axis lines (without descriptions).
+
+A strong advantage is that this type of alignment requires almost no changes to your pictures. Thus, you can copy--paste existing images (\TeX\ code) relatively simple.
+
+Note that the approach is fully compatible with the image |external|ization library: each picture is exported separately, and the bounding box restrictions (and the |baseline| offset) are stored in separate |.dpth| files. The |trim left| / |trim right| approach for horizontal alignment is the \emph{only} supported way for reduced bounding boxes and image externalization.
+
+Unfortunately, |trim left| and |trim right| are not shipped with \PGFPlots\ and will be part of the next stable \Tikz\ release.
+
+
+\paragraph{Array Alignment using \Tikz\ Matrices}
+While it is possible to use (for example) |tabular| combined with the vertical and horizontal alignment methods discussed above, it might be better to use a \Tikz\ |matrix| since it automatically handles the size of axis descriptions.
+
+A \Tikz\ matrix is some sort of ``graphical'' table. It knows everything about picture alignment and it has more flexibility than |tabular| when it comes to graphics. The idea is to pack the complete array into a \emph{single} picture.
+
+The complete documentation of a \Tikz\ matrix is beyond the scope of this manual, please refer to \cite{tikz} for details. But we provide an example here:
+\pgfmanualpdflabel{/tikz/matrix}{}%
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \pgfplotsset{small}
+ \matrix {
+ \begin{axis}
+ \addplot {x};
+ \end{axis}
+ &
+ % differently large labels are aligned automatically:
+ \begin{axis}[ylabel={$f(x)=x^2$},ylabel style={font=\Huge}]
+ \addplot {x^2};
+ \end{axis}
+ \\
+ %
+ \begin{axis}[xlabel=$x$,xlabel style={font=\Huge}]
+ \addplot {x^3};
+ \end{axis}
+ &
+ \begin{axis}
+ \addplot {x^4};
+ \end{axis}
+ \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\noindent So, a matrix is a picture element inside of |tikzpicture|. Its cells are separated by `|&|' as in tabular (or, if `|&|' causes problems, with |\pgfmatrixnextcell|). Its rows are separated by `|\\|'. Each cell is aligned using the cells' anchor. Since, by default, the anchor of an axis is placed at the lower left corner, the example above is completely aligned, without the need for any bounding box modifications -- even the labels are aligned correctly. If another anchor shall be used, simply place
+\begin{codeexample}[code only]
+\pgfplotsset{anchor=....}
+\matrix {
+ ...
+};
+\end{codeexample}
+\noindent in front of the matrix. This will use the same configuration for every sub-plot.
+
+\paragraph{Attention:} Unfortunately, the array alignment with |\matrix| need special \emph{attention with legends}. A legend is also a |\matrix| and \Tikz\ matrizes can't be nested. You will need to use the |legend to name| feature (or to assemble a legend by means of |\label| and |\ref|) to overcome this weakness (see Section~\ref{pgfplots:legend:labelref} for details).
+
+
+\subsubsection{Miscellaneous for Alignment}
+
+\begin{predefinednode}{current axis}
+ A node which refers to the current axis or the last typeset axis.
+
+ You can use this node in axis descriptions, for example to place axis labels or titles.
+
+ \paragraph{Remark:} If you use |current axis| inside of axis descriptions, the ``current axis'' is not yet finished. That means you \emph{can't use any outer anchor} inside of axis descriptions.
+
+ It is also possible to use |current axis| in any drawing or plotting commands inside of an axis (but no outer anchor as these are not defined when drawing commands are processed). This usage is similar to the |axis description cs|.
+\end{predefinednode}
+
\subsubsection{Bounding box restrictions}
+\label{sec:bb}
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.
+ \item The |\pgfresetboundingbox| command,
+ \item The |\useasboundingbox| path,
+ \item The |trim left| and |trim right| feature (which is the \emph{only} supported way of restricted bounding boxes and image externalization; at least for pdf output).
\end{enumerate}
+Note that image externalization (the |external| library) is more or less incompatible with methods (1.)--(4.). The problem is that |pdflatex| crops everything outside of the bounding box away. There are only two safe ways to ``restrict'' bounding boxes of external |.pdf| images: the first is the mentioned |trim left| / |trim right| feature and the second is to use negative |\hspace| or |\vspace| commands (or options to |\includegraphics|). Unfortunately, the |trim left| / |trim right| feature is currently unavailable, it needs a more recent \PGF\ version than the current stable release \PGF\ $2.00$ (I only mention the method here because many users downloaded a more recent \PGF\ from \url{http://www.texample.net/tikz/builds/}).
+
\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.
@@ -277,6 +451,36 @@ The following example places a legend somewhere without affecting the bounding b
More information about the |overlay| option can be found in the \PGF\ manual~\cite{tikz}.
\end{key}
+\begin{command}{\pgfresetboundingbox}
+ This command of \pgfname\ resets the bounding box of the current picture. The computation starts from scratch afterwards, allowing to compute a user--defined bounding box.
+
+\begin{codeexample}[]
+\setlength{\fboxsep}{0pt}%
+\fbox{%
+\begin{tikzpicture}%
+ \begin{axis}[
+ title=A title,
+ 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}
+
+ \pgfresetboundingbox
+ \path
+ (current axis.south west)
+ rectangle (current axis.north east);
+\end{tikzpicture}%
+}%
+\end{codeexample}%
+ The example draws a normal picture, containing an axis. Afterwards, it throws the bounding box away and creates a new one based on the |current axis| node and its anchors.
+\end{command}
\begin{environment}{{pgfinterruptboundingbox}}
\label{sec:bounding:box:example}%
@@ -284,14 +488,13 @@ The following example places a legend somewhere without affecting the bounding b
\index{Bounding Box Control!pgfinterruptboundingbox}
{%
\pgfmanualpdflabel{\textbackslash useasboundingbox}{}%
-An alternative to |overlay| is shown below: the figure has a truncated bounding box with is shown using |\fbox|.
+ Yet another approach with the same effect is shown below: the bounding box is interrupted manually, and resumed afterwards.
\begin{codeexample}[]
\setlength{\fboxsep}{0pt}%
\fbox{%
\begin{tikzpicture}%
\begin{pgfinterruptboundingbox}
\begin{axis}[
- name=my plot,
title=A title,
xlabel={$x$},
ylabel={$y$},
@@ -307,8 +510,8 @@ An alternative to |overlay| is shown below: the figure has a truncated bounding
\end{pgfinterruptboundingbox}
\useasboundingbox
- (my plot.below south west)
- rectangle (my plot.above north east);
+ (current axis.below south west)
+ rectangle (current axis.above north east);
\end{tikzpicture}%
}%
\end{codeexample}%
@@ -316,68 +519,30 @@ An alternative to |overlay| is shown below: the figure has a truncated bounding
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{environment}
-\end{pgfplotskey}
+\begin{keylist}{%
+ /tikz/trim left=\marg{$x$ coordinate or point} (default 0pt),
+ /tikz/trim right=\marg{$x$ coordinate or point}}
+ These two keys allow to reduce the size of the bounding box.
-\subsubsection{Alignment In Array Form (Subplots)}
-\index{Subplots}%
-\index{Alignment!Subplots}%
-\index{Alignment!Array}%
-\index{array!Array Alignment}%
-\pgfmanualpdflabel{\textbackslash matrix}{}%
-Sometimes alignment in array form is desired. One can use the following approach or use the library |groupplots| on page \ref{sec:group:plot} which does
-not utilize \Tikz\ matrices.
+ {\bfseries They are only available in the experimental version of \PGF, not in \PGF\ 2.00! You may need the \PGF\ version from |texexample.net|!}
-While it is possible to use (for example) |tabular| combined with the vertical and horizontal alignment methods discussed above, it might be better to use a \Tikz\ |matrix|.
+ The |trim left| key expects either a single $x$ coordinate like |1cm| or a point like |(current axis.west)|. If a point is provided, is uses only the $x$ coordinate of that point. Then, the left end of the bounding box is set to the resulting $x$ coordinate and everything left of it is outside of the bounding box.
-A \Tikz\ matrix is some sort of ``graphical'' table. It knows everything about picture alignment and it has more flexibility than |tabular|. The complete documentation of a \Tikz\ matrix is beyond the scope of this manual, please refer to \cite{tikz} for details. But we provide an example here:
-\pgfmanualpdflabel{/tikz/matrix}{}%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix {
- \begin{axis}
- \addplot {x};
- \end{axis}
- &
- % differently large labels are aligned automatically:
- \begin{axis}[ylabel={$f(x)=x^2$},ylabel style={font=\Huge}]
- \addplot {x^2};
- \end{axis}
- \\
- %
- \begin{axis}[xlabel=$x$,xlabel style={font=\Huge}]
- \addplot {x^3};
- \end{axis}
- &
- \begin{axis}
- \addplot {x^4};
- \end{axis}
- \\
- };
-\end{tikzpicture}
-\end{codeexample}
-\noindent So, a matrix is a picture element inside of |tikzpicture|. Its cells are separated by `|&|' as in tabular (or, if `|&|' causes problems, with |\pgfmatrixnextcell|). Its rows are separated by `|\\|'. Each cell is aligned using the cells' anchor. Since, by default, the anchor of an axis is placed at the lower left corner, the example above is completely aligned, without the need for any bounding box modifications -- even the labels are aligned correctly. If another anchor shall be used, simply place
-\begin{codeexample}[code only]
-\pgfplotsset{anchor=....}
-\matrix {
- ...
-};
-\end{codeexample}
-\noindent in front of the matrix. This will use the same configuration for every sub-plot.
-
-\paragraph{Attention:} Unfortunately, the array alignment with |\matrix| is \emph{incompatible} with legends. A legend is also a matrix and, unfortunately,
-\Tikz\ matrizes can't be nested. Of course, this does not affect the manually created legends by means of |\label| and |\ref|, see
-section~\ref{pgfplots:legend:labelref} for details.
+ The |trim right| key has the same effect, only for the right end of the bounding box.
-If one wishes to have an easier approach of aligning one should refer to the library |groupplots| on p. \ref{sec:group:plot}.
-\subsubsection{Miscellaneous for Alignment}
+ More detailed documentation can be found in the \Tikz\ manual.
+\end{keylist}
-\begin{predefinednode}{current axis}
- A node which refers to the current axis or the last typeset axis.
+\begin{stylekey}{/tikz/trim axis left}
+ A style with value |trim left=(current axis.south west)|.
- You can use this node in axis descriptions, for example to place axis labels or titles.
+ The style needs to be provided as argument to |\begin{tikzpicture}[trim axis left]|. It expects (at least) one \PGFPlots\ environment in the picture. The effect is to trim everything which is left of the last axis' anchor |south west| (i.e.\ everything left of the left axis boundary).
+\end{stylekey}
- \paragraph{Remark:} If you use |current axis| inside of axis descriptions, the ``current axis'' is not yet finished. That means you \emph{can't use any outer anchor} inside of axis descriptions.
+\begin{stylekey}{/tikz/trim axis right}
+ A style with value |trim right=(current axis.south east)|.
- It is also possible to use |current axis| in any drawing or plotting commands inside of an axis (but no outer anchor as these are not defined when drawing commands are processed). This usage is similar to the |axis description cs|.
-\end{predefinednode}
+ It works similarly to |trim axis left|: the effect is that everything right of the right axis line of the last axis environment is truncated from the bounding box.
+\end{stylekey}
+\end{pgfplotskey}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
index 4af602d4fd8..2f4884e4cff 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
@@ -361,30 +361,54 @@ one may want to plot `|dof|' versus `|L2|' or `|dof|' versus `|Lmax|'. This can
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
-or
+or, for the |Lmax| column, using
\begin{codeexample}[code only]
\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}
\end{codeexample}
-Alternatively, you can load the table \emph{once} and use it \emph{multiple} times:
+It is also possible to provide the data inline, i.e.\ directly as argument in curly braces:
\begin{codeexample}[code only]
-\pgfplotstableread{datafile.dat}\loadedtable
+\begin{tikzpicture}
+\begin{loglogaxis}[
+ xlabel=Dof,
+ ylabel=$L_\infty$ error]
+\addplot table[x=dof,y=Lmax] {
+ dof L2 Lmax maxlevel
+ 5 8.31160034e-02 1.80007647e-01 2
+ 17 2.54685628e-02 3.75580565e-02 3
+ 49 7.40715288e-03 1.49212716e-02 4
+ 129 2.10192154e-03 4.23330523e-03 5
+ 321 5.87352989e-04 1.30668515e-03 6
+ 769 1.62269942e-04 3.88658098e-04 7
+ 1793 4.44248889e-05 1.12651668e-04 8
+ 4097 1.20714122e-05 3.20339285e-05 9
+ 9217 3.26101452e-06 8.97617707e-06 10
+};
+\end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Inline table may be convenient together with `|\\|' and |row sep=\\|, see below for more information.
+
+Alternatively, you can load the table \emph{once} into an internal structure and use it \emph{multiple} times:
+\begin{codeexample}[code only]
+\pgfplotstableread{datafile.dat}\loadedtable % use any custom name in place of `\loadedtable'
...
-\addplot table[x=dof,y=L2] from \loadedtable;
+\addplot table[x=dof,y=L2] {\loadedtable};
...
-\addplot table[x=dof,y=Lmax] from \loadedtable;
+\addplot table[x=dof,y=Lmax] {\loadedtable};
...
\end{codeexample}
-I am not really sure how much time can be saved, but it works anyway. As a rule of thumb, decide as follows:
+I am not really sure how much time can be saved, but it works anyway. The |\pgfplotstableread| command is documented in all detail in the manual for \PGFPlotstable. As a rule of thumb, decide as follows:
\begin{enumerate}
- \item If tables contain few rows and many columns, the |from |\meta{\textbackslash macro} framework will be more efficient.
+ \item If tables contain few rows and many columns, the \meta{\textbackslash macro} framework will be more efficient.
\item If tables contain more than~$200$ data points (rows), you should always use file input (and reload if necessary).
\end{enumerate}
+Occasionally, it might be handy to load a table, apply manual preparation steps (for example |\pgfplotstabletranspose|) and plot the result tables afterwards.
If you do prefer to access columns by column indices instead of column names (or your tables do not have column names), you can also use
\begin{codeexample}[code only]
@@ -394,24 +418,29 @@ 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[||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 Use |\addplot table[||x||=|\marg{column name}|,||y||=|\marg{column name}|]| to access column names. Those names are case sensitive and need to exist.
+ \item Use |\addplot 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 |\addplot table[||x expr=\coordindex,y=|\marg{column name}|]| to plot the coordinate index versus some $y$ data.
+ \item Use |\addplot 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
+ \item Use |\addplot table[|\meta{source columns}|] |\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.
+ If you like, you can insert the optional keyword `|from|' before |\macroname|.
- \item The accepted input format of those tables is as follows:
+ \item The accepted input format of tables is as follows:
\begin{itemize}
+ \item Rows are separated by new line characters.
+
+ Alternatively, you can use |row sep=\\| which enables `|\\|' as row separator. This might become necessary for inline table data, more precisely: if newline characters have been converted to white spaces by \TeX's character processing before \PGFPlots\ had a chance to see them. This happens if inline tables are provided inside of macros. Use |row sep=\\| and separate the rows by `|\\|' if you experience such problems.
+
\item Columns are usually separated by white spaces (at least one tab or space).
If you need other column separation characters, you can use the
- \declare{col sep}\pgfmanualpdflabel{/pgfplots/table/col sep}{}|=|\mchoice{space,tab,comma,colon,semicolon,braces}
+ \declare{col sep}\pgfmanualpdflabel{/pgfplots/table/col sep}{}|=|\mchoice{space,tab,comma,colon,semicolon,braces,\&,ampersand}
option which is documented in all detail in the manual for \PGFPlotstable\ which is part of \PGFPlots.
\item Any line starting with `\#' or `\%' is ignored.
@@ -425,9 +454,18 @@ Summary and remarks:
\index{table@\textcolor {gray}{\texttt {plot}}\texttt { table}!Unbalanced Columns}%
\end{itemize}
\item It is also possible to use \textbf{mathematical expressions} together with `|plot table|'. This is documented in all detail in section~\ref{pgfplots:addplot:table:expr}, but the key idea is to use one of |x expr|, |y expr|, |z expr| or |meta expr| as in `|plot table[||x expr=\thisrow{maxlevel}+3,y=L2]|'.
- \item The enhanced column generation methods provided by \PGFPlotstable\ are also accessible for plots, see the \PGFPlotstable\ manual section ``Postprocessing Data in New Columns''.
+ \item The \PGFPlotstable\ package coming with \PGFPlots\ has a the feature ``Postprocessing Data in New Columns'' (see its manual).
+
+ This allows to compute new columns based on existing data. One of these features is |create col/linear regression| (described in Section~\ref{sec:linefitting}).
+
+ You can invoke all the |create col/|\meta{key name} features directly in |\addplot table| using
+
+ |\addplot table[x={create col/|\meta{key name}|=|\meta{arguments}|}]|.
+
+ In this case, a new column will be created using the functionality of \meta{key name}. This column generation is described in all detail in \PGFPlotstable. Finally, the resulting data is available as $x$ coordinate (the same holds for |y=| or |z=|).
+
+ One application (with several examples how to use this syntax) is line fitting with |create col/linear regression|, see Section~\ref{sec:linefitting} for details.
- 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}
@@ -469,17 +507,51 @@ The following list of keys allow different methods to select input data or diffe
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,tab,comma,semicolon,colon,braces} (initially space)}
+
+
+\begin{pgfplotskey}{table/row sep=\mchoice{newline,\string\\} (initially newline)}
+ Configures the character to separate rows.
+
+ The choice \declaretext{newline} uses the end of line as it appears in the table data (i.e.\ the input file or any inline table data).
+
+ The choice \declaretext{\string\\} uses `|\\|' to indicate the end of a row.
+
+ Note that \declaretext{newline} for inline table data is ``fragile'': you can't provide such data inside of \TeX\ macros (this does not apply to input files). Whenever you experience problems, proceed as follows:
+ \begin{enumerate}
+ \item First possibility: call |\pgfplotstableread|\marg{data}|\yourmacro| \emph{outside} of any macro declaration.
+ \item Use |row sep=\\|.
+ \end{enumerate}
+ The same applies if you experience problems with inline data and special |col sep| choices (like |col sep=tab|).
+
+ The reasons for such problems is that \TeX\ scans the macro bodies and replaces newlines by white spaces. It does other substitutions of this sort as well, and these substitutions can't be undone (maybe not even found).
+\end{pgfplotskey}
+
+\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces,\&,ampersand} (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)}
+\begin{key}{/pgfplots/table/read completely=\marg{auto,true,false} (initially auto)}
Allows to customize \verbpdfref{\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'').
+ The initial configuration |auto| checks whether one of the keys |table/x|, |table/y|, |table/z| or |table/meta| contains a |create on use| column. If so, it enables |read completely|, otherwise it prefers to load the file in the normal way.
+
\paragraph{Attention:} Usually, \verbpdfref{\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\footnote{This remark might be deprecated; many of the slow routines have been optimized in the meantime to have at least pseudo-linear runtime.}.
\end{key}
+\begin{key}{/pgfplots/table/ignore chars=\marg{comma-separated-list} (initially empty)}
+ Allows to silently remove a set of single characters from input files. The characters are separated by commas. The documentation for this command, including cases like `|\%,\#,\ |' or binary character codes like `|\^^ff|' can be found in the manual for \PGFPlotstable.
+
+ This setting applies to |\addplot file| as well.
+\end{key}
+
+\begin{key}{/pgfplots/table/white space chars=\marg{comma-separated-list} (initially empty)}
+ Allows to define a list of single characters which are actually treated like white spaces (in addition to tabs and spaces). Please refer to the manual of \PGFPlotstable\ for details.
+
+ This setting applies to |\addplot file| as well.
+\end{key}
+
+
\subsubsection{Computing Coordinates with Mathematical Expressions}
\begin{addplotoperation}[]{\marg{math expression}}{}
@@ -535,7 +607,7 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
\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 (color data).
+ \item Please note that plot expression does not allow separate per point meta data (color data). You can, of course, use |point meta=f(x)| or |point meta=x|.
\end{enumerate}
\paragraph{About the precision and number range:}
@@ -715,7 +787,7 @@ Since system calls are a potential danger, they need to be enabled explicitly us
\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.
+Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two hyphens -- that all depends on your \TeX\ distribution.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
@@ -743,7 +815,7 @@ Some remarks:
For |parametric| plots, the variable names need to be adjusted with |parametric/var 1d| and |parametric/var 2d| (since gnuplot uses |t| and |u,v| as initial values for |parametric| plots).
\item
-Please note that |plot gnuplot| does not allow per point meta data (color data for each coordinate).
+Please note that |plot gnuplot| does not allow separate per point meta data (color data for each coordinate). You can, however, use |point meta=f(x)| or |point meta=x|.
\item The generated output file name can be customized with |id|, see below.
\end{itemize}
@@ -943,6 +1015,25 @@ Using |gv|, I determined that the bounding box needs to be shifted |12| units to
The \meta{options} are any arguments provided to the |includegraphics| key (see below) and |width| and |height| determined such that the graphics fits exactly into the rectangle denoted by the |xmin|, |ymin| and |xmax|, |ymax| coordinates.
The scaling will thus ignore the aspect ratio of the external image and prefer the one used by \PGFPlots. You will need to provide |width| and |height| to the \PGFPlots\ axis to change its scaling. Use the |scale only axis| key in such a case.
+
+\paragraph{Legends in \texttt{plot graphics}:} A legend for |plot graphics| uses the current plot handler and the current plot |mark|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[axis on top,title=Graphics Import]
+ % provide options for the legend:
+ \addplot[red,only marks,mark=*,mark size=1pt]
+ graphics
+ [xmin=0,xmax=1,ymin=0,ymax=1,
+ % trim=left bottom right top
+ includegraphics={trim=12 9 12 8,clip}]
+ {external2};
+
+ \addplot coordinates {(0,0) (1,1)};
+
+ \legend{Scatter,Line}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
\end{addplotoperation}
\subsubsection*{Keys To Configure Plot Graphics}
@@ -957,6 +1048,9 @@ The following list of keys configure |\addplot graphics|. Note that the common p
\begin{pgfplotskey}{plot graphics/includegraphics=\marg{options}}
A list of options which will be passed as--is to |\includegraphics|. Interesting options include the \declareandlabel{trim}|=|\meta{left} \meta{bottom} \meta{right} \meta{top} key which reduces the bounding box and \pgfmanualpdflabel{/pgfplots/plot graphics/clip}{\declaretext{clip}} which discards everything outside of the bounding box. The scaling options won't have any effect, they will be overwritten by \PGFPlots.
\end{pgfplotskey}
+\begin{pgfplotskey}{plot graphics/includegraphics cmd=\marg{\textbackslash macro} (initially \textbackslash includegraphics)}
+ Allows to use a different graphics routine. A possible choice could be |\pgfimage|. The macro should accept the |width| and |height| arguments (in brackets) and the file name as first argument.
+\end{pgfplotskey}
\begin{stylekey}{/pgfplots/plot graphics/node}
A predefined style used for the \Tikz\ node containing the graphics. The predefined value is
\begin{codeexample}[code only]
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
index 746c007d1eb..f2b4ad810de 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
@@ -454,7 +454,7 @@ 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. The other method is to use the key |legend entries|.
-\begin{command}{\addlegendentry\marg{name}}
+\begin{command}{\addlegendentry\oarg{options}\marg{name}}
Adds a single legend entry to the legend list. This will also enable legend drawing.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -479,11 +479,12 @@ Adds a single legend entry to the legend list. This will also enable legend draw
\end{codeexample}
It does not matter where |\addlegendentry| commands are placed, only the sequence matters. You will need one |\addlegendentry| for every |\addplot| command (unless you prefer an empty legend).
+The optional \meta{options} affect how the text is drawn; they apply only for this particular description text. For example, |\addlegendentry[red]{Text}| would yield a red legend text. Behind the scenes, the text is placed with |\node|\oarg{options} \marg{name}|;|, so \meta{options} can be any \Tikz\ option which affects nodes.
Using |\addlegendentry| disables the key |legend entries|.
\end{command}
-\begin{command}{\addlegendentryexpanded\marg{\TeX\ text}}
+\begin{command}{\addlegendentryexpanded\oarg{options}\marg{\TeX\ text}}
A variant of |\addlegendentry| which provides a method to deal with macros inside of \meta{\TeX\ text}.
Suppose \meta{\TeX\ text} contains some sort of parameter which varies \emph{for every plot}. Moreover, you like to use a loop to generate the plots. Then, it is simpler to use |\addlegendentryexpanded|:
@@ -528,12 +529,17 @@ Two different delimiters are supported:
\begin{codeexample}[code only]
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{codeexample}
- These lists are processed using the \PGF\ |\foreach| command.
+ These lists are processed using the \PGF\ |\foreach| command and are quite powerful.
+
+ The |\foreach| command supports a dots--notation to denote ranges like |\legend{1,2,...,5}| or even |\legend{$x^1$,$x^...$,$x^d$}|.
+
+ \paragraph{Attention with periods:} to avoid confusion with the dots |...| notation, you may need to encapsulate a legend entry containing periods by curly braces: |\legend{{ML spcm.},{CW spcm.},{ML AC}}| (or use the |\\| delimiter, see below).
+
\item It is also possible to delimit the list by `|\\|'. In this case, the \emph{last element must be terminated} by |\\| as well:
\begin{codeexample}[code only]
\legend{$a=1, b=2$\\,$a=2, b=3$\\$a=3, b=5$\\}
\end{codeexample}
- This syntax simplifies the use of `|,|' inside of legend entries.
+ This syntax simplifies the use of `|,|' inside of legend entries, but it does not support the dots--notation.
\end{enumerate}
The short marker/line combination shown in legends is acquired from the \marg{style options} argument of |\addplot|.
@@ -563,20 +569,20 @@ Using |\legend| overwrites any other existing legend entries.
\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}
-
-
-\begin{command}{\addlegendimage\marg{options}}
- Adds a further ``plot style'' for legend creation.
- Each |\addplot| command appends its plot style options to a list, and |\addlegendimage| adds \meta{options} to the very same list.
-
- Thus, the effect is as if you had provided |\addplot|\oarg{options}, but |\addlegendimage| bypasses all the logic usually associated with a plot. In other words: except for the legend, the state of the axis remains as if the command would not have been drawn. Not even the current plot's index is advanced, making |\addlegendimage| compatible with any plot styles like |ybar|.
-
- Use |\addlegendimage| to provide custom styles into legends, for example to document custom |\draw| commands inside of an axis.
+ Just as for |\addlegendentry|, it is possible to provide \oarg{options} to single descriptions. To do so, place the options in square brackets right before the text:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[legend entries={$x$,[red]$x^2$,$x^3$}]
+ \addplot {x};
+ \addplot {x^2};
+ \addplot {x^3};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ If the square brackets contain a comma, you can enclose the complete entry in curly braces like |{[red,font=\Huge]Text}| (or you can use the `|\\|' delimiters).
+\end{pgfplotskey}
- You can call |\label| after |\addlegendimage| just as for a normal style.
-\end{command}
\subsubsection{Legend Appearance}
@@ -770,6 +776,46 @@ Whenever possible, consider using |/.append style| to keep the default styles ac
\end{codeexample}
\end{pgfplotskey}
+
+\begin{pgfplotskey}{legend cell align=\mchoice{left,right,center} (initially center)}
+ These keys provide horizontal alignment of legend cells.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[legend cell align=left,
+ legend pos=outer north east]
+\addplot coordinates {(0,0) (1,1)};
+\addplot coordinates {(0,1) (1,2)};
+\addplot coordinates {(0,2) (1,3)};
+\legend{a,fine,legend}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[legend cell align=center,
+ legend pos=outer north east]
+\addplot coordinates {(0,0) (1,1)};
+\addplot coordinates {(0,1) (1,2)};
+\addplot coordinates {(0,2) (1,3)};
+\legend{a,fine,legend}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[legend cell align=right,
+ legend pos=outer north east]
+\addplot coordinates {(0,0) (1,1)};
+\addplot coordinates {(0,1) (1,2)};
+\addplot coordinates {(0,2) (1,3)};
+\legend{a,fine,legend}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ They are actually just styles for commonly used alignment choices: the choice |left| is equivalent to |legend style={cells={anchor=west}}|, the choice |right| is equivalent to |legend style={cells={anchor=east}}| and |center| to |legend style={cells={anchor=center}}|. Using different values allows more control over cell alignment.
+\end{pgfplotskey}
}
\begin{pgfplotskey}{legend columns=\marg{number} (default 1)}
@@ -785,12 +831,28 @@ Configures where the small line specifications will be drawn: left of the descri
\begin{stylekey}{/pgfplots/every legend image post}
\label{key:legendimagepost}
A style which can be used to provide drawing options to every small legend image. These options apply after |current plot style| has been set, allowing users different line styles for legends than for plots.
+
+ For example, suppose you have a line plot and you plot selected markers on top of it (in the same color). Then, you may want to draw just a \emph{single} legend entry (which should contain both the line \emph{and} the markers). The following example shows a solution:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[legend image post style={mark=*}]
+ \addplot+[only marks,forget plot]
+ coordinates {(0.5,0.75) (1,1) (1.5,0.75)};
+ \addplot+[mark=none,smooth,domain=0:2]
+ {-x*(x-2)};
+ \addlegendentry{Parable}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ \noindent The example has two |\addplot| commands, one for the line and one for markers. Due to the |forget plot| option, the marker plot (the first one) doesn't advance the |cycle list|. The axis has only one legend entry, and since |legend image post style={mark=*}| has been used, the legend has a plot mark as well. Due to the |forget plot| option, the marker plot will not get a separate legend label.
\end{stylekey}
+\pgfplotsshortstylekey legend image post style=every legend image post\pgfeov
+
\begin{pgfplotscodekey}{legend image code}
\label{opt:legend:image:code}
Allows to replace the default images which are drawn inside of legends. When this key is evaluated, the current plot specification has already been activated (using |\begin{scope}[current plot style]|)%
-\footnote{This was different in versions before 1.3. The new scope features allows plot styles to change |legend image code|.}, so any drawing operations use the same styles as the |\addplot| command.
+\footnote{This was different in versions before 1.3. The new scope features allows plot styles to change \texttt{legend image code}.}, so any drawing operations use the same styles as the |\addplot| command.
The default is the style |line legend|.
@@ -818,6 +880,9 @@ The default is the style |line legend|.
The style |line legend| can also be used to use a different legend style for one particular plot (see the docs for |area legend| for an example).
\end{stylekey}
+\begin{stylekey}{/pgfplots/empty legend}
+ A style which clears |legend image code|, thereby omitting the legend image.
+\end{stylekey}
\begin{stylekey}{/pgfplots/area legend}
A style which sets |legend image code| to
@@ -917,7 +982,9 @@ The initial values for these styles might be interesting if someone wants to mod
\end{codeexample}
\end{pgfplotskey}
-\begin{pgfplotskey}{reverse legend=\mchoice{true,false} (initially false)}
+\begin{pgfplotskeylist}{%
+ reverse legend=\mchoice{true,false} (initially false),%
+ legend reversed=\mchoice{true,false} (initially false)}
Allows to reverse the order in which the pairs (legend entry, plot style) are drawn.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -931,7 +998,62 @@ The initial values for these styles might be interesting if someone wants to mod
\end{axis}
\end{tikzpicture}
\end{codeexample}
-\end{pgfplotskey}
+\end{pgfplotskeylist}
+
+\begin{pgfplotskeylist}{%
+ transpose legend=\mchoice{true,false} (initially false),%
+ legend transposed=\mchoice{true,false} (initially false)}
+ Allows to transpose the order in which the pairs (legend entry, plot style) are drawn.
+
+ Consider a set of $3$ experiments, each consisting of $2$ parameter. We might want to draw them together as in the following example:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ legend columns=2,
+ legend pos=outer north east,
+ cycle multi list={%
+ color list\nextlist
+ [2 of]mark list
+ }]
+ \addplot {-x}; \addlegendentry{A1}
+ \addplot {-x+1}; \addlegendentry{A2}
+
+ \addplot {-1.2*x + 4}; \addlegendentry{B1}
+ \addplot {-1.2*x + 5}; \addlegendentry{B2}
+
+ \addplot {-1.3*x + 9}; \addlegendentry{C1}
+ \addplot {-1.4*x + 10}; \addlegendentry{C2}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ An alternative might be to draw them horizontally -- then, we'd like to use |transpose legend| to get a flat legend:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ transpose legend,
+ legend columns=2,
+ legend style={at={(0.5,-0.1)},anchor=north},
+ cycle multi list={%
+ color list\nextlist
+ [2 of]mark list
+ }]
+ \addplot {-x}; \addlegendentry{A1}
+ \addplot {-x+1}; \addlegendentry{A2}
+
+ \addplot {-1.2*x + 4}; \addlegendentry{B1}
+ \addplot {-1.2*x + 5}; \addlegendentry{B2}
+
+ \addplot {-1.3*x + 9}; \addlegendentry{C1}
+ \addplot {-1.4*x + 10}; \addlegendentry{C2}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ Thus, |legend columns| defines the \emph{input} columns, before the transposition (in other words, |legend columns| indicates the \emph{rows} of the resulting legend).
+
+ Transposing legends has only an effect if |legend columns|$>1$. Note that |reverse legend| has higher precedence: it is applied first.
+\end{pgfplotskeylist}
\subsubsection{Legends with \texttt{\textbackslash label} and \texttt{\textbackslash ref}}
@@ -970,8 +1092,8 @@ Finally, \ref{pgfplots:label3} is only here to get three examples.
Label3 = \ref{pgfplots:label3};
Label2 = \ref{pgfplots:label2}
\end{codeexample}
- The label is assembled using |legend image code| and the plot style of the last plot. Any \PGFPlots\ option is expanded until only \Tikz\ (or \pgfname) options remain; these options are used to get an independent label\footnote{Please note that you can't use the label/ref mechanism in conjunction with image externalization as this will (naturally) lead to undefined references.}.
-
+ The label is assembled using |legend image code| and the plot style of the last plot. Any \PGFPlots\ option is expanded until only \Tikz\ (or \pgfname) options remain; these options are used to get an independent label.
+
More precisely, the small image generated by |\ref|\marg{label name} is
\begin{codeexample}[code only]
\tikz[/pgfplots/every crossref picture] {...}
@@ -979,6 +1101,9 @@ Label2 = \ref{pgfplots:label2}
\noindent where the contents is determined by |legend image code| and the plot style.
The second syntax, |\label|\oarg{reference}\marg{label name} allows to label particular pieces of an |\addplot| command. It is (currently) only interesting for |scatter/classes|: there, it allows to reference particular classes of the scatter plot. See page~\pageref{pgfplots:scatterclasses} for more details.
+
+
+ Note that |\label| information, even the small \Tikz\ pictures here, can be combined with the |external| library for image externalization, see section~\ref{sec:pgfplots:export} for details (in particular, the |external/mode| key). In other words, references remain valid even if the defining axis has been externalized.
\end{commandlist}
\begin{command}{\ref\marg{label name}}
@@ -1002,6 +1127,186 @@ Label2 = \ref{pgfplots:label2}
\end{codeexample}
\end{stylekey}
+\begin{pgfplotskeylist}{%
+ invoke before crossref tikzpicture=\marg{\TeX\ code},
+ invoke after crossref tikzpicture=\marg{\TeX\ code}}
+ Code which is invoked just before or just after every cross reference picture. This applies to legend images generated with |\ref|, |legend to name| and |colorbar to name| images.
+
+ The initial configuration checks if the |external| library is in effect. If so, it calls |\tikzappendtofigurename{_crossref}|.
+ \index{crossref file suffix}
+\end{pgfplotskeylist}
+
+\subsubsection{Legends Outside Of an Axis}
+Occasionally, one has multiple adjacent plots, each with the same legend -- and just \emph{one} legend suffices. But where shall it be placed? And how? One solution is to use the |overlay| key to exclude the legend from bounding box computations, and place it absolutely such that it fits. Another is the |legend to name| feature:
+
+\begin{pgfplotskey}{legend to name=\marg{name} (initially empty)}
+\label{key:legend:to:name}
+ Enables a legend export mode: instead of drawing the legend, a self--contained, independent set of drawing commands will be stored using the label \meta{name}. The definition is done using |\label|\marg{name}, just like any other \LaTeX\ label. The name can be referenced using
+
+ |\ref|\marg{name}.
+
+Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside of any picture, will cause the legend to be drawn.
+{
+\pgfplotsmanualdisablecolorforref
+\begin{codeexample}[vbox]
+\pgfplotsset{footnotesize,samples=10}
+\begin{center}% note that \centering uses less vspace...
+\begin{tikzpicture}
+ \begin{axis}[
+ legend columns=-1,
+ legend entries={$(x+0)^k$;,$(x+1)^k$;,$(x+2)^k$;,$(x+3)^k$},
+ legend to name=named,
+ title={$k=1$}]
+ \addplot {x};
+ \addplot {x+1};
+ \addplot {x+2};
+ \addplot {x+3};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}[title={$k=2$}]
+ \addplot {x^2};
+ \addplot {(x+1)^2};
+ \addplot {(x+2)^2};
+ \addplot {(x+3)^2};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}[title={$k=3$}]
+ \addplot {x^3};
+ \addplot {(x+1)^3};
+ \addplot {(x+2)^3};
+ \addplot {(x+3)^3};
+ \end{axis}
+\end{tikzpicture}
+\\
+
+\ref{named}
+\end{center}
+\end{codeexample}
+}
+
+ Note that only the \emph{first} plot has |legend entries|. Thus, its legend will be created as usual, and stored under the name `|named|', but it won't be drawn. The stored legend can then be drawn with |\ref{named}| below the three plots. Since there is no picture in this context, a |\tikz| picture is created and a |\matrix[/pgfplots/every axis legend]| path is drawn inside of it, resulting in the legend as if it had been placed inside of the axis.
+
+ The stored legend will contain the currently active values of legend- and plot style related options. This includes |legend image code|, |every axis legend|, and any plot style options (and some more). The algorithm works in the same way as for |\label| and |\ref|, i.e.\ it keeps any options with |/tikz/| prefix and expands those with |/pgfplots/| prefix.
+
+ Note that the legend is drawn with |every axis legend|, even though the placement options might be chosen to fit into an axis. You may want to adjust the style in the same axis in which the stored legend has been defined (the value will be copied and restored as well).
+
+ \paragraph{About \texttt{\string\ref}\marg{name}} The |\ref|\marg{name} command retrieves a stored legend (one defined by |legend to name|) and draws it.
+
+{
+\pgfplotsmanualdisablecolorforref
+ |\ref{named}: | \ref{named}
+}
+
+
+ If you want the legend to be exported \emph{and} drawn inside of the current axis, consider using |extra description/.append code={\ref|\marg{name}|}|.
+
+ Note that |\ref| can be combined with the |external| library for image externalization. In other words, the legend will work even if the defining axis has been externalized, see section~\ref{sec:pgfplots:export} for details (in particular the |external/mode| key).
+
+ Note furthermore that this |.aux| file related stuff is (currently) only supported for \LaTeX, sorry.
+ \begin{command}{\pgfplotslegendfromname\marg{name}}
+ This command poses an equivalent alternative for |\ref|\marg{name}: it has essentially the same effect, but it does not create links when used with the |hyperref| package\footnote{Since this manual uses colored links, the text in \texttt{\string\ref} would usually be blue. Using \texttt{\string\pgfplotslegendfromname} avoids link text colors in the legend (this has been applied to the manual styles here).}.
+ \end{command}
+
+ \begin{stylekey}{/pgfplots/every legend to name picture}
+ A style which is installed when |\ref| is used outside of a picture: a new picture will be created with |\tikz[/pgfplots/every legend to name picture]|.
+
+ Thus, you can re-define this style to set alignment options (such as |baseline|).
+ For example, the initialisation
+\begin{codeexample}[code only]
+\pgfplotsset{
+ legend style={matrix anchor=west,at={(0pt,0pt)}},
+ every legend to name picture/.style={baseline},
+}
+...
+\end{codeexample}
+ \noindent will cause the legend to be positioned such that its |west| anchor is at |y=0pt|. The |baseline| option will align this point of the legend with the text baseline (please refer to the documentation for |baseline| in section~\ref{pgfplots:sec:align} for details).
+ \end{stylekey}
+\end{pgfplotskey}
+
+\subsubsection{Legends with Customized Texts or Multiple Lines}
+
+\begin{command}{\addlegendimage\marg{options}}
+ Adds a further legend image for legend creation.
+
+ Each |\addplot| command appends its plot style options to a list, and |\addlegendimage| adds \meta{options} to the very same list.
+
+ Thus, the effect is as if you had provided |\addplot|\oarg{options}, but |\addlegendimage| bypasses all the logic usually associated with a plot. In other words: except for the legend, the state of the axis remains as if the command would not have been drawn. Not even the current plot's index is advanced.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{semilogyaxis}[
+ domain=0:4,
+]
+ \addplot {x}; \addlegendentry{$x$}
+ \addplot {x^2}; \addlegendentry{$x^2$}
+ \addplot {x^3}; \addlegendentry{$x^3$}
+ \addlegendimage{empty legend}
+ \addlegendentry{---}
+ \addplot {x^(-1)}; \addlegendentry{$x^{-1}$}
+ \addplot {x^(-2)}; \addlegendentry{$x^{-2}$}
+ \addplot {x^(-3)}; \addlegendentry{$x^{-3}$}
+\end{semilogyaxis}
+\end{tikzpicture}
+\end{codeexample}
+ The example above has six plots, each with its legend entry. Furthermore, it has an |\addlegendimage| command and its separate legend entry. We see that |\addlegendimage| needs its own legend entry, but it is detached from the processing of plots as such. In our case, we chose |empty legend| as style for the separator.
+
+ Use |\addlegendimage| to provide custom styles into legends, for example to document custom |\draw| commands inside of an axis.
+
+ You can call |\label| after |\addlegendimage| just as for a normal style.
+\end{command}
+
+Occasionally, one may want multiple lines for legend entries. That is possible as well using a fixed |text width|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{semilogyaxis}[
+ domain=0:4,
+]
+ \addplot {x}; \addlegendentry{$x$}
+ \addplot {x^2}; \addlegendentry{$x^2$}
+ \addplot {x^3}; \addlegendentry{$x^3$}
+ \addlegendimage{empty legend}
+ \addlegendentry[text width=25pt,text depth=]
+ {Neg Sign:}
+ \addplot {x^(-1)}; \addlegendentry{$x^{-1}$}
+ \addplot {x^(-2)}; \addlegendentry{$x^{-2}$}
+ \addplot {x^(-3)}; \addlegendentry{$x^{-3}$}
+\end{semilogyaxis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent The example provides options for the single multiline element. Note that the initial configuration of |legend style| employs |text depth=0.15em|, which needs to be reset manually to |text depth={}|\footnote{Perhaps I can reset \texttt{text depth} automatically in the future.}.
+
+\noindent There are two approaches with the same effect which are subject of the following example:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{semilogyaxis}[
+ domain=0:4,
+ legend entries={%
+ $x$,$x^2$,$x^3$,%
+ {[text width=25pt,text depth=]Neg. Sign:},%
+ $x^{-1}$,$x^{-2}$,$x^{-3}$},
+ % same effect:
+ % legend style={
+ % nodes={text width=25pt,text depth=}}
+]
+ \addplot {x};
+ \addplot {x^2};
+ \addplot {x^3};
+ \addlegendimage{empty legend}
+ \addplot {x^(-1)};
+ \addplot {x^(-2)};
+ \addplot {x^(-3)};
+\end{semilogyaxis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Here, the |legend entries| are provided using the single key syntax. Note that the special options are provided as part of the legend entry, using square brackets right before the text as such. The comments indicate that you could also add the |text width| stuff to |legend style|, in which case it would hold for every node.
+
+
+Note that legend texts are realized using |\node|\oarg{options} \marg{text}|;|, so anything which produces a valid \Tikz\ node is permitted (this includes |minipage| or |tabular| environments inside of \meta{text}).
+
\subsubsection{Axis Lines}
{\small \emph{An extension by Pascal Wolkotte}}
@@ -1242,17 +1547,17 @@ Note that three dimensional axes only support to use the same value for every ax
\noindent with similar values for the |y|-variant. Feel free to redefine this style to your needs / taste.
\end{pgfplotsxykey}
-\subsubsection[Two Ordinates]{Two Ordinates ($y$ axis)}
+\subsubsection[Two Ordinates]{Two Ordinates ($y$ axis) or Multiple Axes}
{%
\pgfplotsset{every axis/.append style={width=4.5cm}}%
-In some applications, more than one $y$ axis is used if the $x$ range is the same. This section demonstrates how to create them.
+In some applications, more than one $y$ axis is used if the $x$ range is the same. This section demonstrates how to create them. The idea in \PGFPlots\ is to draw two axes on top of each other, one with descriptions only on the left and the second with descriptions only on the right:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
scale only axis,
xmin=-5,xmax=5,
- axis y line=left,
+ axis y line*=left,% the '*' avoids arrow heads
xlabel=$x$,
ylabel=First ordinate]
\addplot {x^2};
@@ -1261,14 +1566,14 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam
\begin{axis}[
scale only axis,
xmin=-5,xmax=5,
- axis y line=right,
+ axis y line*=right,
axis x line=none,
ylabel=Second ordinate]
\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. Since \PGFPlots\ does not really know what it's doing here, user attention in the following possibly non-obvious aspects is required:
+\noindent Thus, the two axes are drawn ``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.
@@ -1282,7 +1587,7 @@ It is also possible to use only the axis, without any plots:
\begin{axis}[
scale only axis,
xmin=-5,xmax=5,
- axis y line=left,
+ axis y line*=left,%'*' avoids arrow heads
xlabel=$x$,
ylabel=Absolute]
\addplot {x^2};
@@ -1294,9 +1599,8 @@ It is also possible to use only the axis, without any plots:
ymin=0,ymax=1000,
yticklabel=
{$\pgfmathprintnumber{\tick}$\textperthousand},
- axis y line=right,
+ axis y line*=right,
axis x line=none,
- y label style={yshift=-10pt},
ylabel=per thousand]
\end{axis}
\end{tikzpicture}
@@ -1440,8 +1744,8 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{tikzpicture}
\end{codeexample}
- A color bar is only useful for plots which actually use color data -- that is, the special data which is called ``point meta'' in \PGFPlots\ (see section~\ref{pgfplots:point:meta}). Activating color bars for a plot without color map results in an empty color bar.
-
+ A color bar is only useful for plots with non--zero color data range, more precisely, for which minimum and maximum |point meta| data is available. Usually, this is the case for |scatter|, |mesh| or |surf| (or similar) plots, but you can also set |point meta min| and |point meta max| manually in order to draw a |colorbar|.
+
Color bars are just normal axes which are placed right besides their parent axes. The only difference is that they inherit several styles such as line width and fonts and they contain a bar shaded with the color map of the current axis.
Color bars are drawn internally with
@@ -1454,7 +1758,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\paragraph{Remarks for special cases:}
\begin{itemize}
- \item Since there is always only one color bar per plot, this color bar uses the axis wide configurations of color map and color data.
+ \item Since there is always only one color bar per plot, this color bar uses the axis wide configurations of color map and color data. Consider using |colorbar source| to select color data limits of a particular |\addplot| command instead.
\item If someone needs more than one color bar, the draw command above needs to be updated. See the key
|colorbar/draw/.code| for this special case.
\end{itemize}
@@ -1610,6 +1914,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{stylekey}
\begin{stylekey}{/pgfplots/every colorbar}
+ \label{key:every:colorbar}
This style governs the placement, alignment and appearance of color bars. Any desired detail changes for color bars can be put into this style. Additionally, there is a style |colorbar shift| which is set after |every colorbar|. The latter style is intended to contain only shift transformations like |xshift| or |yshift| (making it easier to overwrite or deactivate them).
While a color bar is drawn, the predefined node |parent axis| can be used to align at the parent axis.
@@ -1634,7 +1939,22 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
The values of these keys contain the lower and upper bound of the color map, i.e.\ the lower and upper limit for the color bar.
The value is |\pgfkeysvalueof{/pgfplots/point meta min}| inside of |every colorbar|.
+
+ The value is usually determined using the axis wide point meta limits, i.e.\ they are computed as minimum and maximum value over all plots (unless the user provided limits manually). Consider the |colorbar source| key if you'd like to select point meta limits of one specific |\addplot| command.
\end{pgfplotskeylist}
+\begin{pgfplotskey}{colorbar source=\marg{true,false} (initially false)}
+ Allows to select a specific |\addplot| command whose point meta limits are taken as upper and lower limit of a |colorbar|'s data range. This affects the tick descriptions of the |colorbar|. It needs to be provided as argument to |\addplot|, i.e.\ using
+\begin{codeexample}[code only]
+\addplot[...,colorbar source] ...
+% or
+\addplot+[colorbar source] ...
+\end{codeexample}
+ \noindent or as key inside of a |cycle list|.
+
+ Using |colorbar source| automatically implies |point meta rel=per plot| for that specific plot.
+
+ If there are more than one |\addplot| commands with |colorbar source|, the last one is preferred.
+\end{pgfplotskey}
\begin{pgfplotskeylist}{parent axis width,parent axis height}
The values of these keys contain the size of the parent axis. They can be used as |width| and/or |height| arguments for |every colorbar| with |\pgfkeysvalueof{/pgfplots/parent axis width}|.
@@ -1752,6 +2072,101 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
Please note that a color bar axis is nothing special as such -- it is just a normal axis with one |plot graphics| command and it is invoked with a special set of options. The only special thing is that a set of styles and some variables are inherited from its parent axis.
\end{pgfplotscodekey}
+\begin{stylekey}{/pgfplots/colorbar sampled=\marg{optional options} (default surf,mark=none,shader=flat)}
+ A style which installs a discretely sampled color bar.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[colorbar sampled]
+ \addplot[mesh,samples=40] {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The style uses |\addplot3|\oarg{options} to draw the |colorbar|, with |domain| set to the color range. In other words: it uses |plot expression| and a surface plot to visualize the |colorbar|. Use |colorbar style={samples=10}| to change the number of samples.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[colorbar sampled,colorbar style={samples=8}]
+ \addplot[mesh,samples=40] {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The \meta{options} can be used to change the |\addplot3| options used for the colorbar visualization. For example, |colorbar sampled={surf,shader=interp}| will use gouraud shading which has visually the same effect as the standard colorbar.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colorbar sampled line=\marg{optional options} (default scatter,only marks)}
+ A style which draws a discrete colorbar. In contrast to |colorbar sampled|, it visualizes the |colorbar| using a line plot, not a |surf| plot.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[colorbar sampled line]
+ \addplot+[scatter] {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The initial configuration uses a |scatter| plot to visualize the |colorbar|, it can be changed by specifying \meta{options}.
+
+ Furthermore, the axis appearance is changed using |axis y line*=|\mchoice{left,right}, depending on the position of the color bar or (or |axis x line*=bottom| for |colorbar horizontal|).
+
+ Consider the |tick align=outside| feature if you prefer tick lines outside of the colorbar instead of inside.
+
+ \begin{stylekey}{/pgfplots/every colorbar sampled line}
+ A style which is used by |colorbar sampled line| to change the color of the line without ticks.
+
+ It is initially set to |help lines|.
+ \end{stylekey}
+\end{stylekey}
+
+\subsubsection{Color Bars Outside Of an Axis}
+
+Occasionally, one has multiple adjacent plots, each with the same |colormap| and the same |point meta min| and |point meta max| values and we'd like to show a \emph{single} |colorbar|. \PGFPlots\ supports the |colorbar to name| feature which is similar to the related method for legends, |legend to name|:
+
+
+\begin{pgfplotskey}{colorbar to name=\marg{name} (initially empty)}
+ Enables to detach a |colorbar| from its parent axis: instead of drawing the |colorbar|, a self--contained, independent set of drawing commands will be stored using the label \meta{name}. The label is defined using |\label|\marg{name}, just as for any other \LaTeX\ label. The name can be referenced using
+
+ |\ref|\marg{name}.
+
+Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside of any picture, will cause the |colorbar| to be drawn.
+
+{
+\pgfplotsmanualdisablecolorforref
+\begin{codeexample}[vbox]
+\pgfplotsset{footnotesize,samples=10, domain=0:1,point meta min=0, point meta max=1}
+\begin{center}% note that \centering uses less vspace...
+\begin{tikzpicture}
+ \begin{axis}[colorbar,colorbar horizontal,colorbar to name={storedcolorbar}]
+ \addplot[scatter,only marks,mark=*] {rnd};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}
+ \addplot+[domain=0:1,mark=none,mesh] {x^2};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}[view={0}{90}]
+ \addplot3[surf] {x*y};
+ \end{axis}
+\end{tikzpicture}
+\\
+
+\ref{storedcolorbar}
+\end{center}
+\end{codeexample}
+}
+
+ The feature works in the same way as described for |legend to name|, please refer to its description on page~\pageref{key:legend:to:name} for the details. We only summarize the differences here.
+ \begin{command}{\pgfplotscolorbarfromname\marg{name}}
+ This command poses an equivalent alternative for |\ref|\marg{name}: it has essentially the same effect, but it does not create links when used with the |hyperref| package.
+ \end{command}
+
+ \begin{stylekey}{/pgfplots/every colorbar to name picture}
+ A style which is installed when |\ref| is used outside of a picture: a new picture will be created with |\tikz[/pgfplots/every colorbar to name picture]|.
+
+ See also the |every legend to name picture| style.
+ \end{stylekey}
+\end{pgfplotskey}
+
\subsubsection{Scaling Descriptions: Predefined Styles}
\label{sec:scaling:styles}
It is reasonable to change font sizes, marker sizes etc. together with the overall plot size: Large plots should also have larger fonts and small plots should have small fonts and a smaller distance between ticks.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
index b0377e3e004..baceab56f8e 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
@@ -75,13 +75,17 @@ There is also a style key which simplifies selection by index, see below.
\index{Downsampling}
\end{pgfplotskey}
-\begin{pgfplotsxykey}{restrict \x\space to domain=\meta{min}:\meta{max}}
+\begin{pgfplotsxykeylist}{
+ restrict \x\space to domain=\meta{min}:\meta{max},
+ restrict \x\space to domain*=\meta{min}:\meta{max}}
\label{key:restrict:x:to:domain}
- Appends $x$ (or $y$ or $z$) coordinate filters which set the respective coordinate to |-inf| if it is below \meta{min} and to |+inf| if it is above \meta{max}.
+ These keys append $x$ (or $y$ or $z$) coordinate filters to restrict the respective coordinate to a domain.
+
+ The versions without star (like |restrict x to domain|) will assign the value |-inf| if the coordinate is below \meta{min} and |+inf| if the coordinate is above \meta{max}. The starred versions (like |restrict x to domain*|) will truncate coordinates to $[\hbox{\meta{min}}, \hbox{\meta{max}}]$, i.e.\ they assign the value \meta{min} if the coordinate falls outside of the lower limit and \meta{max} if the value falls outside of the upper limit.
For logarithmic axes, \meta{min} and \meta{max} are \emph{logs} of the respective values. A variant which uses the non-logarithmic number might be to use |restrict expr to domain={\pgfmathrawx}|\marg{min}\marg{max}.
- Furthermore, it sets the |unbounded coords=jump| key which leads to interrupted plots.
+ The non-starred versions also set |unbounded coords=jump| which leads to interrupted plots.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
@@ -100,15 +104,20 @@ There is also a style key which simplifies selection by index, see below.
\end{axis}
\end{tikzpicture}
\end{codeexample}
-\end{pgfplotsxykey}
+\end{pgfplotsxykeylist}
-\begin{pgfplotskey}{restrict expr to domain=\marg{expression}\marg{\meta{min}:\meta{max}}}
+\begin{pgfplotskeylist}{%
+ restrict expr to domain=\marg{expression}\marg{\meta{min}:\meta{max}},%
+ restrict expr to domain*=\marg{expression}\marg{\meta{min}:\meta{max}}%
+ }
Appends an $x$ coordinate filter which sets the $x$ coordinate to |-inf| if the \meta{expression} evaluates to something less than \meta{min} and to |inf| if \meta{expression} evaluates to something larger than \meta{max}.
- Furthermore, it sets the |unbounded coords=jump| key which leads to interrupted plots.
+ The starred variant, |restrict to domain*| assigns \meta{min} if \meta{expression} is less then the lower limit and \meta{max} if it is larger than the upper limit.
+
+ The non-starred version also sets |unbounded coords=jump| which leads to interrupted plots.
In contrast to |restrict x to domain|, \meta{expression} can depend on anything which is valid during |\addplot|, in particular |\coordindex| or table columns (|\thisrow|\marg{column name} and friends). The expression doesn't need to depend on $x$ at all.
-\end{pgfplotskey}
+\end{pgfplotskeylist}
\begin{pgfplotskey}{filter discard warning=\mchoice{true,false} (initially true)}
Issues a notification in your logfile whenever coordinate filters discard coordinates.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex
new file mode 100644
index 00000000000..cd4cba421a5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex
@@ -0,0 +1,146 @@
+\subsection{Fitting Lines -- Regression}
+\label{sec:linefitting}
+{
+\pgfkeys{
+ /pgfmanual/gray key prefixes={/pgfplots/table},
+}
+
+This section documents the attempts of \PGFPlots\ to fit lines to input coordinates. \PGFPlots\ currently supports |create col/linear regression| applied to columns of input tables. The feature relies on \PGFPlotstable, it is actually implemented as a table postprocessing method.
+
+
+\begin{stylekey}{/pgfplots/table/create col/linear regression=\marg{key-value-config}}%
+\pgfkeys{
+ /pgfmanual/gray key prefixes={/pgfplots/table/create col/linear regression/},
+ /pdflinks/search key prefixes in/.add={/pgfplots/table/create col/linear regression/,}{},
+}
+ A style for use in |\addplot table| which computes a linear (least squares) regression $y(x) = a \cdot x + b$ using the sample data $(x_i,y_i)$ which has to be specified inside of \meta{key-value-config} (see below).
+
+ It creates a new column on-the-fly which contains the values $y(x_i) = a \cdot x_i + b$. The values $a$ and $b$ will be stored (globally) into \declareandlabel{\pgfplotstableregressiona} and \declareandlabel{\pgfplotstableregressionb}.
+
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[legend pos=outer north east]
+ \addplot table[row sep=\\] {% plot X versus Y. This is original data.
+ X Y\\
+ 1 1 \\
+ 2 4\\
+ 3 9\\
+ 4 16\\
+ 5 25\\
+ 6 36\\
+ };
+ \addplot table[row sep=\\,
+ y={create col/linear regression={y=Y}}] % compute a linear regression from the input table
+ {
+ X Y\\
+ 1 1 \\
+ 2 4\\
+ 3 9\\
+ 4 16\\
+ 5 25\\
+ 6 36\\
+ };
+ %\xdef\slope{\pgfplotstableregressiona} %<-- might be handy occasionally
+ \addlegendentry{$y(x)$}
+ \addlegendentry{%
+ $\pgfmathprintnumber{\pgfplotstableregressiona} \cdot x
+ \pgfmathprintnumber[print sign]{\pgfplotstableregressionb}$}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The example above has two plots: one showing the data and one containing the |linear regression| line. We use |y={create col/linear regression={}}| here, which means to create a new column\footnote{The \texttt{y=\{create col/} feature is available for any other \PGFPlotstable\ postprocessing style, see the \texttt{create on use} documentation in the \PGFPlotstable\ manual.} containing the regression values automatically.
+ As arguments, we need to provide the $y$ column name explicitly\footnote{In fact, \PGFPlots\ sees that there are only two columns and uses the second as default. But you need to provide it if there are at least 3 columns.}. The $x$ value is determined from context: |linear regression| is evaluated inside of |\addplot table|, so it uses the same $x$ as |\addplot table| (i.e.\ if you write |\addplot table[x=|\marg{col name}|]|, the regression will also use \marg{col name} as its |x| input). Furthermore, it shows the line parameters $a$ and $b$ in the legend.
+
+
+
+ The following \meta{key-value-config} keys are accepted as comma--separated list:
+
+ \begin{key}{%
+ /pgfplots/table/create col/linear regression/table=\marg{\textbackslash macro {\normalfont or} file name} (initially empty)}
+ Provides the table from where to load the |x| and |y| columns. It defaults to the currently processed one, i.e.\ to the value of |\pgfplotstablename|.
+ \end{key}
+ \begin{keylist}{%
+ /pgfplots/table/create col/linear regression/x=\marg{column} (initially empty),
+ /pgfplots/table/create col/linear regression/y=\marg{column} (initially empty)}
+ Provides the source of $x_i$ and $y_i$ data, respectively. The argument \meta{column} is usually a column name of the input table, yet it can also contains |[index]|\meta{integer} to designate column indizes (starting with $0$), |create on use| specifications or |alias|es (see the \PGFPlotstable\ manual for details on |create on use| and |alias|).
+
+ The initial configuration (an empty value) checks the context where the |linear regression| is evaluated. If it is evaluated inside of |\pgfplotstabletypeset|, it uses the first and second table columns. If it is evaluated inside of |\addplot table|, it uses the same $x$ input as the |\addplot table| statement. The |y| key needs to be provided explicitly (unless the table has only two columns).
+ \end{keylist}
+
+ \begin{keylist}{%
+ /pgfplots/table/create col/linear regression/xmode=\mchoice{auto,linear,log} (initially auto),
+ /pgfplots/table/create col/linear regression/ymode=\mchoice{auto,linear,log} (initially auto)}
+ Enables or disables processing of logarithmic coordinates. Logarithmic processing means to apply $\ln$ before computing the regression line and $\exp$ afterwards.
+
+ The choice |auto| checks if the column is evaluated inside of a \PGFPlots\ axis. If so, it uses the axis scaling of the embedding axis. Otherwise, it uses |linear|.
+
+ In case of logarithmic coordinates, the |log basis x| and |log basis y| keys determine the basis.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{loglogaxis}
+ \addplot table[x=dof,y=error2]
+ {pgfplotstable.example1.dat};
+ \addlegendentry{$y(x)$}
+
+ \addplot table[
+ x=dof,
+ y={create col/linear regression={y=error2}}]
+ {pgfplotstable.example1.dat};
+
+ % might be handy occasionally:
+ %\xdef\slope{\pgfplotstableregressiona}
+ \addlegendentry{slope
+ $\pgfmathprintnumber{\pgfplotstableregressiona}$}
+\end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+
+ The (commented) line containing |\slope| is explained above; it allows to remember different regression slopes in our example.
+ \end{keylist}
+
+ \begin{keylist}{%
+ /pgfplots/table/create col/linear regression/variance list=\marg{list} (initially empty),%
+ /pgfplots/table/create col/linear regression/variance=\marg{column name} (initially empty)%
+ }
+ Both keys allow to provide uncertainties (variances) to single data points.
+ A high (relative) variance indicates an unreliable data point, a value of $1$ is standard.
+
+ The |variance list| key allows to provide variances directly as comma--separated list, for example
+
+ |variance list={1000,1000,500,200,1,1}|.
+
+ The |variance| key allows to load values from a table \meta{column name}. Such a column name is (initially, see below) loaded from the same table where data points have been found. The \meta{column name} may also be a |create on use| name.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{loglogaxis}
+ \addplot table[x=dof,y=error2]
+ {pgfplotstable.example1.dat};
+ \addlegendentry{$y(x)$}
+
+ \addplot table[
+ x=dof,
+ y={create col/linear regression={
+ y=error2,
+ variance list={1000,800,600,500,400}}
+ }
+ ]
+ {pgfplotstable.example1.dat};
+
+ \addlegendentry{slope
+ $\pgfmathprintnumber{\pgfplotstableregressiona}$}
+\end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+
+ If both, |variance list| and |variance| are given, the first one will be preferred. Note that it is not necessary to provide variances for every data point.
+ \end{keylist}
+
+ \begin{key}{/pgfplots/table/create col/linear regression/variance src=\marg{\textbackslash table {\normalfont or} file name} (initially empty)}
+ Allows to load the |variance| from another table. The initial setting is empty. It is acceptable if the |variance| column in the external table has fewer entries than expected, in this case, only the first ones will be used.
+ \end{key}
+\end{stylekey}
+
+\paragraph{Limitations:} Currently, \PGFPlots\ supports only linear regression, and it only supports regression together with |\addplot table|. Furthermore, long input tables might need quite some time.
+}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
index 6fcce13a478..7bd15bf2a25 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
@@ -560,7 +560,7 @@ The usage of the result \meta{\textbackslash macro} is a little bit low--level.
\begin{pgfplotskeylist}{cycle list=\marg{list},cycle list name=\marg{\textbackslash macro}}
Allows to specify a list of plot specifications which will be used for each \hbox{|\addplot|}-command without explicit plot specification. Thus, the currently active |cycle list| will be used if you write either |\addplot+|\oarg{keys}| ...;| or if you \emph{don't} use square brackets as in |\addplot|\oarg{explicit plot specification}| ...;|.
-The list element with index~$i$ will be chosen where~$i$ is the index of the current |\addplot| command. This indexing does also include plot commands which don't use the |cycle list|.
+The list element with index~$i$ will be chosen where~$i$ is the index of the current |\addplot| command (see also the |cycle list shift| key which allows to use $i+n$ instead). This indexing does also include plot commands which don't use the |cycle list|.
There are several possibilities to change the currently active |cycle list|:
\begin{enumerate}
@@ -925,7 +925,7 @@ In this case, the \emph{last} entry also needs a terminating `|\\|', but one can
\begin{axis}[
title={Cycle 2 marks between successive plots, then colors},
cycle multi list={%
- blue,red\nextlist
+ color list\nextlist
[2 of]mark list
},
samples=3,
@@ -949,6 +949,20 @@ In this case, the \emph{last} entry also needs a terminating `|\\|', but one can
\end{codeexample}
\end{pgfplotskey}
+\begin{pgfplotskey}{cycle list shift=\marg{integer} (initially empty)}
+ Allows to \emph{shift} the index into the |cycle list|. If \meta{integer} is $n$, the list element $i+n$ will be taken instead of the $i$'th one. Remember that $i$ is the index of the current |\addplot| command (starting with~$0$).
+
+ Since a |cycle list| is queried \emph{immediately} when |\addplot| (or |\addplot+|) is called, you can adjust the |cycle list shift| for selected plots:
+\begin{codeexample}[code only]
+\pgfplotsset{cycle list shift=3}
+\addplot ....
+
+\pgfplotsset{cycle list shift=-1}
+\addplot ....
+\end{codeexample}
+ \paragraph{Special case:} If the result is negative, $i+n <0$, the list index $-(i+n)$ will be taken. For example, |cycle list shift=-10| and $i<10$ will result in list index $10-i$. Note that you can use |reverse legend| to reverse legends, so this feature is probably never needed.
+\end{pgfplotskey}
+
\subsubsection{Axis Background}
\begin{pgfplotskey}{axis background (initially empty)}
This is a style to configure the appearance of the axis as such. It can be defined and/or changed using the |axis background/.style=|\marg{options} method. A background path will be generated with \meta{options}, which may contain fill colors or shadings.
@@ -1086,18 +1100,22 @@ A further common idea is the use of color maps: if the point meta data is in the
Currently, this choice can only be used for scatter plots.
- \item[\declare{\meta{expression}}] This choice finally allows to compute point meta data using a mathematical expression. The \meta{expression} may depend on |x|, |y|, |z| which yield the current $x$, $y$ or $z$ coordinate, respectively. The coordinates are completely processed (transformations, logs) as mentioned above for the choice |x|. Furthermore, the \meta{expression} may depend on commands which are valid during |\addplot| like |\plotnum| or |\coordindex| (see section~\ref{pgfplots:misc} for details). Computations are performed using the floating point unit of \PGF, and all supported arithmetical operations can be used.
-
- In essence, the \meta{expression} may depend on everything which is known to all |\addplot| commands: the $x$, $y$ and (if any) $z$ coordinates. In addition, it may depend upon |rawx|, |rawy| or |rawz|. These three expressions yield the unprocessed $x$, $y$ or $z$ value as it has been found in the input stream (no logs, no user transformations). If used together with |plot table|, you may also access other table columns (for example with |\thisrow|\marg{colname}).
+ \item[\normalfont\declare{\meta{expression}}] This choice allows to compute point meta data using a mathematical expression. The \meta{expression} may depend on |x|, |y|, |z| which yield the current $x$, $y$ or $z$ coordinate, respectively. The coordinates are completely processed (transformations, logs) as mentioned above for the choice |x|. Furthermore, the \meta{expression} may depend on commands which are valid during |\addplot| like |\plotnum| or |\coordindex| (see section~\ref{pgfplots:misc} for details). Computations are performed using the floating point unit of \PGF, and all supported arithmetical operations can be used.
- The \meta{expression} is checked after the other possible choices have already been evaluated. In other words, the statement
+ In essence, the \meta{expression} may depend on everything which is known to all |\addplot| commands: the $x$, $y$ and (if any) $z$ coordinates. In addition, it may depend upon |rawx|, |rawy| or |rawz|. These three expressions yield the unprocessed $x$, $y$ or $z$ value as it has been found in the input stream (no logs, no user transformations)%
+ \footnote{%
+ In rare circumstances, it might be interesting to apply a math expression to another source of point meta (one of the other choices. To this end, the \meta{expression} is checked after the other possible choices have already been evaluated. In other words, the statement \texttt{point meta=explicit, point meta=meta*meta+3} will evaluate the expression with |meta| set to whatever data has been provided explicitly.}.
+ If used together with |plot table|, you may also access other table columns (for example with |\thisrow|\marg{colname}).
+
+ \item[\normalfont\declaretext{TeX code}\texttt{=}\meta{code}] A rather low level choice which allows to provide \TeX\ \meta{code} to compute a numerical value. The \meta{code} should define the macro |\pgfplotspointmeta|. It is evaluated in a locally scoped environment (it's local variables are freed afterwards). It may depend on the same values as described for \meta{expression} above, especially on |\thisrow|\marg{colname} for table input.
- |point meta=explicit, point meta=meta^2+3|
+ Note that the math parser will be configured to use the |fpu| at this time, so |\pgfmathparse| yields floats.
- will evaluate the expression with |meta| set to whatever data has been provided explicitly.
+ \item[\normalfont\declaretext{TeX code symbolic}\texttt{=}\meta{code}] Just as |TeX code|, you can provide \meta{code} which defines the macro |\pgfplotspointmeta|, but the result is not interpreted as a number. It is like the |explicit symbolic| choice.
+
\end{description}
- It has been mentioned several times that one application of point meta data is to determine (marker/face/edge) colors using a linear map into the range $[0,1000]$ (maybe for use in the current color map). This map works as follows: it is a function
+ As already mentioned, a main application of point meta data is to determine (marker/face/edge) colors using a linear map into the range $[0,1000]$ (maybe for use in the current color map). This map works as follows: it is a function
\[ \phi\colon [m_{\text{min}},m_{\text{max}}] \to [0,1000] \]
with
\[ \phi(m) = \frac{m - m_{\text{min}}} {1000} \]
@@ -1145,6 +1163,8 @@ A further common idea is the use of color maps: if the point meta data is in the
\end{axis}
\end{tikzpicture}
\end{codeexample}
+
+ Note that a |colorbar| will still use the |axis wide| point meta limits. Consider the |colorbar source| key if you want the color data limits of a \emph{particular} plot for your color bar. The |point meta rel| key configures how point meta maps to colors in the |colormap|.
\end{pgfplotskey}
\begin{pgfplotskeylist}{point meta min=\marg{number},point meta max=\marg{number}}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
index 6997afc53a1..fb074d59ca8 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
@@ -165,7 +165,16 @@ You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values of y
\end{pgfplotsxykeylist}
+
+\begin{pgfplotskey}{update limits=\mchoice{true,false} (initially true)}
+ Can be used to interrupt updates of the data limits (for example, for single |\addplot| commands).
+
+ This has the same effect as |\pgfplotsinterruptdatabb| ... |\endpgfplotsinterruptdatabb|.
+\end{pgfplotskey}
+
\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.
+
+ The same effect can be achieved with |update limits=false| inside curly braces.
\end{environment}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex
index 69fe108fac9..99dfc3a5137 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex
@@ -130,6 +130,17 @@ which can be reset if needed.
This key is also documented on page~\pageref{key:legendimagepost}.
\end{stylekey}
+\pgfplotsshortstylekey legend image post style=every legend image post\pgfeov
+
+\begin{stylekey}{/pgfplots/every legend to name picture}
+ A style for use with |legend to image|, see the documentation therein.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/every colorbar}
+ A style to change the |colorbar|. See page~\pageref{key:every:colorbar} for the reference documentation of |every colorbar|.
+\end{stylekey}
+
+\pgfplotsshortstylekey colorbar style=every colorbar\pgfeov
\subsubsection*{Styles for axis lines}
\begin{xystylekey}{/pgfplots/every outer \x\ axis line (initially empty)}
@@ -159,6 +170,10 @@ Please refer to section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots:
\pgfplotsshortstylekey 3d box foreground style=every 3d box foreground\pgfeov
+\begin{stylekey}{/pgfplots/every colorbar sampled line}
+ To be used in conjunction with |colorbar sampled line|, see the documentation therein.
+\end{stylekey}
+\pgfplotsshortstylekey colorbar sampled line style=every colorbar sampled line\pgfeov
\subsubsection*{Styles for ticks}
@@ -237,6 +252,16 @@ The initial setting is
\pgfplotsset{every extra x tick/.append style={grid=major}}
\pgfplotsset{every extra x tick/.append style={major tick length=0pt}}
\pgfplotsset{every extra x tick/.append style={/pgf/number format=sci subscript}}
+\pgfplotsset{extra x tick style={
+ color=red,
+ tickwidth=3mm,
+ % the initial 'every tick style' defines a 'line width'.
+ % this here redefines it:
+ tick style={
+ line width=2mm,
+ },
+ }
+}
\end{codeexample}
\end{xystylekey}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
index b2a92e7868d..b12dd75e90f 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
@@ -20,4 +20,5 @@
\input pgfplots.reference.closingplots.tex
\input pgfplots.reference.symbolic-transformations.tex
\input pgfplots.reference.coordfiltering.tex
+\input pgfplots.reference.linefitting.tex
\input pgfplots.reference.miscellaneous.tex
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex
index 0cb1556035f..228d9d8533a 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex
@@ -241,7 +241,9 @@ xticklabels={{0,5}, $e$}.
$-\frac 12$,
$0$,
$\frac 12$,
- $1$}
+ $1$},
+ % note: \frac can be done automatically:
+ % xticklabel style={/pgf/number format/frac},
]
\addplot[smooth,blue,mark=*]
coordinates {
@@ -321,7 +323,7 @@ That means you can configure the appearance of linear axis with the number forma
\end{tikzpicture}
\end{codeexample}
-The following example uses explicitly formatted $x$ tick labels and a small \TeX\ script to format $y$ tick labels in the form \meta{sign}\meta{number}|/10|.
+The following example uses explicitly formatted $x$ tick labels and a small \TeX\ script to format $y$ tick labels as fractions in the form \meta{sign}\meta{number}|/10| (note that the |/pgf/number format/frac| style can do similar things automatically, see \PGFPlotstable\ and the documentation therein).
% \usepackage{nicefrac}
\begin{codeexample}[width=4cm]
% \usepackage{nicefrace}% required
@@ -345,6 +347,9 @@ The following example uses explicitly formatted $x$ tick labels and a small \TeX
\fi
\fi
},
+ % NOTE: this here does the same:
+ % yticklabel style={/pgf/number format/.cd,frac,
+ % frac TeX=\nicefrac,frac whole=false,frac denom=10},
ymajorgrids,
title=A special Prewavelet,
axis x line=center,
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
index 87b7a54d236..54688463c10 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
@@ -34,6 +34,21 @@
\end{tikzpicture}
\end{codeexample}
+\pgfplotsexpensiveexample
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ title=$120 \times 120$ Smooth Surface,
+ xlabel=$x$,
+ ylabel=$y$]
+\addplot3[surf,samples=120,shader=interp,domain=0:1]
+ {sin(deg(8*pi*x))* exp(-20*(y-0.5)^2)
+ + exp(-(x-0.5)^2*30
+ - (y-0.25)^2 - (x-0.5)*(y-0.25))};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
\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.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
index 4d4364563b1..1e4ce7cbf4d 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
@@ -184,7 +184,7 @@ I apologize for any inconvenience caused by these changes.
If you are interested in writing something but don't know how, consider reading the auxiliary manual \href{file:TeX-programming-notes.pdf}{TeX-programming-notes.pdf} which comes with \PGFPlots. It is far from complete, but maybe it is a good starting point (at least for more literature).
\subsection{Acknowledgements}
-I thank God for all hours of enjoyed programming. I thank Pascal Wolkotte and Nick Papior Andersen for their programming efforts and contributions as part of the development team. I thank Stefan Tibus, who contributed the |plot shell| feature. I thank Tom Cashman for the contribution of the |reverse legend| feature. Furthermore, I thank Dr.~Schweitzer for many fruitful discussions and Dr.~Meine for his ideas and suggestions.
+I thank God for all hours of enjoyed programming. I thank Pascal Wolkotte and Nick Papior Andersen for their programming efforts and contributions as part of the development team. I thank Stefan Tibus, who contributed the |plot shell| feature. I thank Tom Cashman for the contribution of the |reverse legend| feature. Special thanks go to Stefan Pinnow whose tests of \PGFPlots\ lead to numerous quality improvements. Furthermore, I thank Dr.~Schweitzer for many fruitful discussions and Dr.~Meine for his ideas and suggestions. Thanks as well to the many international contributors who provided feature requests or identified bugs or simply manual improvements!
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.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.dat b/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.dat
new file mode 100644
index 00000000000..e69de29bb2d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.dat
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.script b/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.script
new file mode 100644
index 00000000000..093dcd3ba70
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.script
@@ -0,0 +1 @@
+unset surface; set cntrparam levels 5; set contour; set table "pgfplots_contourtmp0.table"; splot "pgfplots_contourtmp0.dat";
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.table b/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.table
new file mode 100644
index 00000000000..e69de29bb2d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots_contourtmp0.table
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
new file mode 100644
index 00000000000..b1b36a8f11b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example5.dat b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example5.dat
new file mode 100644
index 00000000000..f6e42d61ed6
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example5.dat
@@ -0,0 +1,4 @@
+first,second
+(1)(0),2 1#2)
+(3)(0),4 1#3)
+(5)(0),6 1#3)
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf
index 2876de353a3..c88e6098e8f 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 c4be25d48f4..1db93c31c52 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
@@ -26,6 +26,7 @@
\usepackage{colortbl}
\usepackage{booktabs}
\usepackage{eurosym}
+\usepackage{multirow}
\pgfqkeys{/codeexample}{%
every codeexample/.style={
@@ -143,10 +144,29 @@ 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}}
+\begin{command}{\pgfplotstabletypeset\oarg{optional arguments}\marg{file name {\normalfont or} \textbackslash macro {\normalfont or} inline table}}
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|).
+ In case the first argument is a file name, the table will be loaded from disk. If it is an already loaded table (see |\pgfplotstableread| or |\pgfplotstablenew|), it will be used. Otherwise, if it is inline table data, this data will be parsed just as if it would have been found in a file (see |\pgfplotstableread|).
+{
+ % allow to typeset the example. I couldn't get the \catcodes
+ % correctly...
+ \pgfplotstableset{
+ /codeexample/newline=\noexpand\\,
+ row sep=\\,
+ }%
+\begin{codeexample}[]
+\pgfplotstabletypeset[sci zerofill]{
+ a b
+ 5000 1.234e5
+ 6000 1.631e5
+ 7000 2.1013e5
+ 9000 1000000
+}
+\end{codeexample}
+}%
+
+
\begin{codeexample}[]
\pgfplotstabletypeset{pgfplotstable.example1.dat}
\end{codeexample}
@@ -190,6 +210,26 @@ There is future support for a second header line which must start with `|$flags
\end{codeexample}
\noindent All of these options are explained in all detail in the following sections.
+You may also use a similar input format as for tabular environment:
+\begin{codeexample}[width=8cm]
+\pgfplotstabletypeset
+ [col sep=&,row sep=\\,sci zerofill]
+{
+ level & dof & error \\
+ 1 & 4 & 2.50000000e-01 \\
+ 2 & 16 & 6.25000000e-02 \\
+ 3 & 64 & 1.56250000e-02 \\
+ 4 & 256 & 3.90625000e-03 \\
+ 5 & 1024 & 9.76562500e-04 \\
+ 6 & 4096 & 2.44140625e-04 \\
+ 7 & 16384 & 6.10351562e-05 \\
+ 8 & 65536 & 1.52587891e-05 \\
+ 9 & 262144 & 3.81469727e-06 \\
+ 10 & 1048576 &9.53674316e-07 \\
+}
+\end{codeexample}
+
+
Technical note: every opened file will be protocolled into your log file.
\end{command}
@@ -198,22 +238,51 @@ Technical note: every opened file will be protocolled into your log file.
\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 then be used several times.
+\begin{commandlist}{%
+ \pgfplotstableread\marg{file name}\marg{\textbackslash macro},
+ \pgfplotstableread\marg{inline table}\marg{\textbackslash macro}}
+ Loads a table into the \TeX-macro \meta{\textbackslash macro}. This macro will store the table as internal structure and can be used several times.
\begin{codeexample}[]
\pgfplotstableread{pgfplotstable.example1.dat}\loadedtable
\pgfplotstabletypeset[columns={dof,error1}]\loadedtable
\hspace{2cm}
\pgfplotstabletypeset[columns={dof,error2}]\loadedtable
\end{codeexample}
- There are variants of this command which do not really built up a struct but which report every line to a ``listener''. There is also a struct which avoids protection by \TeX\ scopes. In case you need such things, consider reading the source code comments.
+ The first argument can be either a \meta{file name} as in the example here. It is also possible to provide the table data directly:
+\begin{codeexample}[code only]
+% Alternative: inline table data:
+\pgfplotstableread{
+level dof error1 error2 info grad(log(dof),log(error2)) quot(error1)
+1 4 2.50000000e-01 7.57858283e-01 48 0 0
+2 16 6.25000000e-02 5.00000000e-01 25 -3.00000000e-01 4
+3 64 1.56250000e-02 2.87174589e-01 41 -3.99999999e-01 4
+4 256 3.90625000e-03 1.43587294e-01 8 -5.00000003e-01 4
+5 1024 9.76562500e-04 4.41941738e-02 22 -8.49999999e-01 4
+6 4096 2.44140625e-04 1.69802322e-02 46 -6.90000001e-01 4
+7 16384 6.10351562e-05 8.20091159e-03 40 -5.24999999e-01 4
+8 65536 1.52587891e-05 3.90625000e-03 48 -5.35000000e-01 3.99999999e+00
+9 262144 3.81469727e-06 1.95312500e-03 33 -5.00000000e-01 4.00000001e+00
+10 1048576 9.53674316e-07 9.76562500e-04 2 -5.00000000e-01 4.00000001e+00
+}\loadedtable
+% can be used as above:
+\pgfplotstabletypeset[columns={dof,error1}]\loadedtable
+\hspace{2cm}
+\pgfplotstabletypeset[columns={dof,error2}]\loadedtable
+\end{codeexample}
+ It is checked automatically whether the first argument contains inline data or a file name.
-Technical note: every opened file will be protocolled into your log file.
+ The check whether the first argument is inline data or a file name works as follows: if |format=auto|, the first argument is considered to be a file name unless it contains the |row sep| character (see |row sep|). If |format=inline|, it is always considered to be inline data. If |format=file|, it is a file name.
- Note: avoid using `|\table|' as name, it conflicts with |\begin{table}| of \LaTeX.
-\end{command}
+ \paragraph{Special cases and more details:}
+ \begin{itemize}
+ \item The inline data format is ``fragile''. If you experience problems, terminate your tables with `|\\|' combined with |row sep=\\| (the docs for |row sep| contain alternative ways and more explanation).
+ \item There are variants of this command which do not really built up a struct but which report every line to a ``listener''. There is also a struct which avoids protection by \TeX\ scopes. In case you need such things, consider reading the source code comments.
+ \item Technical note: every opened file will be protocolled into your log file.
+ \item Note: avoid using `|\table|' as name, it conflicts with |\begin{table}| of \LaTeX.
+ \end{itemize}
+\end{commandlist}
-\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces} (initially space)}
+\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces,\&,ampersand} (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).
For example, the file |pgfplotstable.example1.csv| uses commas as separation characters.
@@ -247,6 +316,14 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
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.
A further speciality of |col sep=braces| is that it has support for \emph{multi-line} cells: everything within balanced braces is considered to be part of a cell. This includes newlines\footnote{This treatment of newlines within balanced braces actually applies to every other column separator as well (it is a \TeX\ readline feature). In other words: you \emph{can} have multi line cells for every column separator if you enclose them in balanced curly braces. However, \texttt{col sep=braces} has the special treatment that end-of-line counts as white space character; for every other \texttt{col sep} value, this white space is suppressed to remove spurious spaces.}.
+
+ The |col sep=&| case (probably together with |row sep=\\|) allows to read tables as you'd usually type them in \LaTeX. This will automatically enable |trim cells|.
+\end{key}
+
+\begin{key}{/pgfplots/table/trim cells=\mchoice{true,false} (initially false)}
+ If enabled, leading and trailing white spaces will be removed while tables are read.
+
+ This might be necessary if you have |col sep|$\neq$|space| but your cells contain spaces. It will be activated automatically for |col sep=&|.
\end{key}
\begin{key}{/pgfplots/table/header=\mchoice{true,false,has colnames} (initially true)}
@@ -261,7 +338,67 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
Finally, the choice \declaretext{has colnames} is the opposite of |false|: it assumes that the first non--comment line \emph{contains} column names. In other words: even if only numbers are contained in the first line, they are considered to be column \emph{names}.
\end{key}
-\subsection{Selecting Columns}
+\begin{pgfplotskey}{table/format=\mchoice{auto,inline,file} (initially auto)}
+ Configures the format expected as first argument for |\pgfplotstableread|\marg{input}.
+
+ The choice \declaretext{inline} expects the table data directly as argument where rows are separated by |row sep|. Inline data is ``fragile'', because \TeX\ may consume end--of--line characters (or |col sep| characters). See |row sep| for details.
+
+ The choice \declaretext{file} expects a file name.
+
+ The choice \declaretext{auto} searches for a |row sep| in the first argument supplied to |\pgfplotstableread|. If a |row sep| has been found, it is inline data, otherwise it is a file name.
+\end{pgfplotskey}
+\begin{pgfplotskey}{table/row sep=\mchoice{newline,\string\\} (initially newline)}
+ Configures the character to separate rows of the inline table data format (see |format=inline|).
+
+ The choice \declaretext{newline} uses the end of line as it appears in the table data (i.e.\ the input file or any inline table data).
+
+ The choice \declaretext{\string\\} uses `|\\|' to indicate the end of a row.
+
+ Note that \declaretext{newline} for inline table data is ``fragile'': you can't provide such data inside of \TeX\ macros (this does not apply to input files). Whenever you experience problems, proceed as follows:
+ \begin{enumerate}
+ \item First possibility: call |\pgfplotstableread|\marg{data}|\yourmacro| \emph{outside} of any macro declaration.
+ \item Use |row sep=\\|.
+ \end{enumerate}
+ The same applies if you experience problems with inline data and special |col sep| choices (like |col sep=tab|).
+
+ The reasons for such problems is that \TeX\ scans the macro bodies and replaces newlines by white spaces. It does other substitutions of this sort as well, and these substitutions can't be undone (maybe not even found).
+\end{pgfplotskey}
+
+\begin{key}{/pgfplots/table/ignore chars=\marg{comma-separated-list} (initially empty)}
+ Allows to define an ``ignore list'' for single characters. Any characters found in an input file which occur also in \meta{comma-separated-list} will silently by thrown away. The processing is exactly the same as if you did not write them at all in the first place.
+
+ For example, suppose we are given |pgfplotstable.example5.dat| with
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{pgfplotstable.example5.dat}
+
+ \noindent then, we can ignore several of the characters by writing
+\begin{codeexample}[]
+\pgfplotstabletypeset
+ [col sep=comma,ignore chars={(,),\ ,\#}]
+ {pgfplotstable.example5.dat}
+\end{codeexample}
+
+ The \meta{comma-separated-list} should contain exactly one character in each list element, and the single characters should be separated by commas. Some special characters like commas, white spaces, hashes, percents or backslashes need to be escaped by prefixing them with a backslash.
+
+ Besides normal characters, it is also supported to eliminate any binary code from your input files. For example, suppose you have binary characters of code |0x01| (hex notation) in your files. Then, use
+\begin{codeexample}[code only]
+\pgfplotstableset{ignore chars={\^^01}}
+\end{codeexample}
+ \noindent to eliminate them silently. The |^^|\meta{digit}\meta{digit} notation is a \TeX\ feature to provide characters in hexadecimal encoding where \meta{digit} is one of |0123456789abcdef|. I don't know if the backslash in |\^^01| is always necessary, try it out. There is also a character based syntax, in which |\^^M| is \meta{newline} and |\^^I| is \meta{tab}. Refer to~\cite{texbook} for more details.
+
+ Note that after stripping all these characters, the input table must be valid -- it should still contain column separators and balanced columns.
+
+ This setting applies to |\addplot table| and |\addplot file| for \PGFPlots\ as well.
+
+ Note that |ignore chars| is ``fragile'' when it is applied to |format=inline| or |format=auto|. Consider |format=file| if you experience problems\footnote{See also |row\ sep| for more information about dealing with fragile inline tables formats.}.
+\end{key}
+
+\begin{key}{/pgfplots/table/white space chars=\marg{comma-separated-list} (initially empty)}
+ Allows to define a list of single characters which are actually treated like white spaces (in addition to tabs and spaces). It might be useful in order to get more than one column separator character.
+
+ The |white space chars| list is used in exactly the same way as |ignore chars|, and the same remarks as above apply as well.
+\end{key}
+
+\subsection{Selecting Columns and their Appearance Styles}
\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.
@@ -275,7 +412,23 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
\begin{pgfplotstablealiaskey}
Assigns the new name \meta{col name} for the column denoted by \meta{real col name}. Afterwards, accessing \meta{col name} will use the data associated with column \meta{real col name}.
-
+\begin{codeexample}[]
+% in preamble:
+\pgfplotstableset{
+ alias/newname/.initial=b,
+}%
+%
+% in document:
+\pgfplotstabletypeset[
+ row sep=\\,
+ columns={a,newname},% access to `newname' is the same as to `b'
+]{
+ a b\\
+ 1 2\\
+ 3 4\\
+ 5 6\\
+}%
+\end{codeexample}
You can use |columns/|\meta{col name}|/.style| to assign styles for the alias, not for the original column name.
If there exists both an alias and a column of the same name, the column name will be preferred. Furthermore, if there exists a |create on use| statement with the same name, this one will also be preferred.
@@ -482,6 +635,27 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
A style which can be used together with the |dcolumn| package of David Carlisle. It also enables alignment at the decimal separator. However, the decimal separator needs to be exactly one character which is incompatible with `|{,}|' (the default setting for |use comma|).
\end{stylekey}
+\begin{pgfplotskey}{table/sort=\marg{true,false} (initially false)}
+ If set to |true|, |\pgfplotstabletypeset| will sort the table before applying its operation.
+
+ See the description of |\pgfplotstablesort| for how to configure |sort key| and |sort cmp|.
+
+\begin{codeexample}[]
+\pgfplotstabletypeset[
+ sort,sort key=error2,
+ columns={dof,error1,error2},
+ columns/error1/.style={sci,sci subscript,sci zerofill,dec sep align},
+ columns/error2/.style={sci,sci subscript,sci zerofill,dec sep align},
+]
+ {pgfplotstable.example1.dat}
+\end{codeexample}
+
+ The |sort| mechanism is applied before the actual typesetting routine starts, i.e.\ it has the same effect as if you'd call |\pgfplotstablesort| manually before typesetting the table (however, the |sort| key has the advantage of respective the |include outfiles| caching mechanism). Any |create on use| specifications are resolved before calling the |sort key|.
+
+
+ %The |sort| key applies also to |\addplot table[sort,read completely]|.
+\end{pgfplotskey}
+
\begin{stylekey}{/pgfplots/table/every first column}
A style which is installed for every first column only.
\begin{codeexample}[narrow]
@@ -579,7 +753,7 @@ A style which is installed for every column with odd column index (starting with
\end{command}
-\subsection{Configuring Row Appearance}
+\subsection{Configuring Row Appearance: Styles}
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}}
@@ -671,8 +845,9 @@ The following styles allow to configure the final table code \emph{after any cel
\end{stylekey}
\subsection{Customizing and Getting the Tabular Code}
+The following keys allow changes of alignment (|begin table|) and |font| and they allow to write the generated code to |outfile|s (see also |write to macro|). Furthermore, the generated code can be fine--tuned to provide other sorts of table output, beyond \LaTeX.
\begin{stylekey}{/pgfplots/table/every table=\marg{file name}}
- A style which is installed at the beginning of every |\pgfplotstabletypeset| command.
+ A style which is installed at the beginning of every |\pgfplotstabletypeset| command\footnote{The \texttt{every table} style is installed \emph{after} options provided to \texttt{\textbackslash pgfplotstabletypeset}; it has higher precedence.}.
The table file name is given as first argument.
\end{stylekey}
@@ -776,7 +951,7 @@ The command |\pgfutilensuremath| checks whether math mode is active and switches
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):
+\noindent As last example, we use \PGFPlotstable\ to write an |.html| file (including number formatting and rounding!):
% \usepackage{listings}
\begin{codeexample}[width=8cm]
\pgfplotstabletypeset[
@@ -785,9 +960,10 @@ The command |\pgfutilensuremath| checks whether math mode is active and switches
/pgfplots/table/@cell content={<td>#1</td>}
},
before row=<tr>,after row=</tr>,
- skip coltypes, typeset=false, string type,
+ skip coltypes, typeset=false,
+ verbatim,% configures number printer
TeX comment=,
- columns={level,dof},
+ columns={level,dof,error1},
outfile=pgfplotstable.example1.out.html,
]{pgfplotstable.example1.dat}
\lstinputlisting
@@ -907,7 +1083,7 @@ See section~\ref{sec:number:styles} for how to change the appearance.
\end{key}
\begin{key}{/pgf/number format/sci}
-Configures |\pgfmathprintnumber| to display numbers in scientific format, that means sign, mantisse and exponent (basis~$10$). The mantisse is rounded to the desired precision.
+Configures |\pgfmathprintnumber| to display numbers in scientific format, that means sign, mantisse and exponent (basis~$10$). The mantisse is rounded to the desired |precision| (or |sci precision|, see below).
\begin{codeexample}[]
\pgfkeys{/pgf/number format/.cd,sci,precision=2}
@@ -996,6 +1172,62 @@ Truncates every number to integers (discards any digit after the period).
\end{codeexample}
\end{key}
+\begin{key}{/pgf/number format/frac}
+Displays numbers as fractionals.
+
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/frac}
+\pgfmathprintnumber{0.333333333333333}\hspace{1em}
+\pgfmathprintnumber{0.5}\hspace{1em}
+\pgfmathprintnumber{2.133333333333325e-01}\hspace{1em}
+\pgfmathprintnumber{0.12}\hspace{1em}
+\pgfmathprintnumber{2.666666666666646e-02}\hspace{1em}
+\pgfmathprintnumber{-1.333333333333334e-02}\hspace{1em}
+\pgfmathprintnumber{7.200000000000000e-01}\hspace{1em}
+\pgfmathprintnumber{6.666666666666667e-02}\hspace{1em}
+\pgfmathprintnumber{1.333333333333333e-01}\hspace{1em}
+\pgfmathprintnumber{-1.333333333333333e-02}\hspace{1em}
+\pgfmathprintnumber{3.3333333}\hspace{1em}
+\pgfmathprintnumber{1.2345}\hspace{1em}
+\pgfmathprintnumber{1}\hspace{1em}
+\pgfmathprintnumber{-6}
+\end{codeexample}
+
+\begin{key}{/pgf/number format/frac TeX=\marg{\textbackslash macro} (initially \texttt{\textbackslash frac})}
+ Allows to use a different implementation for |\frac| inside of the |frac| display type.
+\end{key}
+\begin{key}{/pgf/number format/frac denom=\meta{int} (initially empty)}
+ Allows to provide a custom denominator for |frac|.
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/.cd,frac, frac denom=10}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{0.5}\hspace{1em}
+\pgfmathprintnumber{1.2}\hspace{1em}
+\pgfmathprintnumber{-0.6}\hspace{1em}
+\pgfmathprintnumber{-1.4}\hspace{1em}
+\end{codeexample}
+\end{key}
+\begin{key}{/pgf/number format/frac whole=\mchoice{true,false} (initially true)}
+ Configures whether complete integer parts shall be placed in front of the fractional part. In this case, the fractional part will be less then $1$. Use |frac whole=false| to avoid whole number parts.
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/.cd,frac, frac whole=false}
+\pgfmathprintnumber{20.1}\hspace{1em}
+\pgfmathprintnumber{5.5}\hspace{1em}
+\pgfmathprintnumber{1.2}\hspace{1em}
+\pgfmathprintnumber{-5.6}\hspace{1em}
+\pgfmathprintnumber{-1.4}\hspace{1em}
+\end{codeexample}
+\end{key}
+\begin{key}{/pgf/number format/frac shift=\marg{integer} (initially 4)}
+ In case you experience problems because of stability problems, try experimenting with a different |frac shift|.
+ Higher shift values $k$ yield higher sensitivity to inaccurate data or inaccurate arithmetics.
+
+ Technically, the following happens. If $r < 1$ is the fractional part of the mantissa, then a scale $i = 1/r \cdot 10^k$ is computed where $k$ is the shift; fractional parts of $i$ are neglected. The value $1/r$ is computed internally, its error is amplified.
+
+ If you still experience stability problems, use |\usepackage{fp}| in your preamble. The |frac| style will then automatically employ the higher absolute precision of |fp| for the computation of $1/r$.
+\end{key}
+\end{key}
+
\begin{key}{/pgf/number format/precision=\marg{number}}
Sets the desired rounding precision for any display operation. For scientific format, this affects the mantisse.
\end{key}
@@ -1273,7 +1505,7 @@ Allows to define an own number style for the scientific format. Here, \meta{keys
-\section{Fine Tuning of Loaded Data}
+\section{From Input Data To Output Tables: Data Processing}
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,
@@ -1293,6 +1525,38 @@ Typesetting cells means to take their value and ``do something''. In many cases,
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|.
+% \usepackage{booktabs}
+% \usepackage{multirow}
+\begin{codeexample}[]
+% An example how to use
+% \usepackage{multirow} and
+% \usepackage{booktabs}:
+\pgfplotstabletypeset[
+ columns/Z/.style={
+ column name={},
+ assign cell content/.code={% use \multirow for Z column:
+ \ifnum\pgfplotstablerow=0
+ \pgfkeyssetvalue{/pgfplots/table/@cell content}
+ {\multirow{4}{*}{##1}}%
+ \else
+ \pgfkeyssetvalue{/pgfplots/table/@cell content}{}%
+ \fi
+ },
+ },
+ % use \booktabs as well (compare examples above):
+ every head row/.style={before row=\toprule,after row=\midrule},
+ every last row/.style={after row=\bottomrule},
+ row sep=\\,col sep=&,
+]{% here: inline data in tabular format:
+ Z & a & b \\
+ data & 1 & 2 \\
+ & 3 & 4 \\
+ & 5 & 6 \\
+ & 7 & 8 \\
+}
+\end{codeexample}
+\index{multirow}%
+\noindent The example above uses |\usepackage{multirow}| to format column |Z|. More precisely, it uses |\multirow{4}{*}{data}| for row \#0 of column |Z| and the empty string for any other row in column |Z|.
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.
@@ -1301,16 +1565,26 @@ Typesetting cells means to take their value and ``do something''. In many cases,
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 content|.
-
+\begin{stylekey}{/pgfplots/table/numeric type}
+ A style which (re)-defines |assign cell content| back to its original value which assumes numerical data.
+
It invokes |\pgfmathprintnumberto| and writes the result into |@cell content|.
-\end{key}
+\end{stylekey}
\begin{stylekey}{/pgfplots/table/string type}
A style which redefines |assign cell content| 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/verb string type}
+ A style which redefines |assign cell content| to return the ``raw'' as--is. Thus, it is quite similar to |string type| -- but it will return control sequences and (many, not all) special characters without expanding them.
+
+ You may need to combine |verb string type| with |special chars|.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/table/numeric as string type}
+ A style which redefines |assign cell content| such that it assumes numerical input data. It returns a string literal describing the input number either as integer or in scientific (exponential) notation. In contrast to |numeric type|, it does not apply number formatting.
+\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.
% \usepackage{pgfcalendar}
@@ -1343,7 +1617,6 @@ Typesetting cells means to take their value and ``do something''. In many cases,
\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|).
@@ -1373,8 +1646,10 @@ Typesetting cells means to take their value and ``do something''. In many cases,
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.
+\end{stylekey}
\subsection{Preprocessing Cell Content}
\label{sec:pgfplotstable:preproc}
@@ -1796,6 +2071,7 @@ 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 \declareandlabel{\pgfmathaccuma} and \declareandlabel{\pgfmathaccumb} can be used to transport intermediate results.
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 \declareandlabel{\pgfplotstablename} a macro containing the name of the currently processed table (i.e.\ it contains the second argument of |\pgfplotstablecreatecol|).
\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).
@@ -2080,6 +2356,37 @@ The example creates two columns: the |new| column is just the sum of each value
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}
+\begin{stylekey}{/pgfplots/table/create col/linear regression=\marg{key-value-config}}%
+ Computes a linear (least squares) regression $y(x) = a \cdot x + b$ using the sample data $(x_i,y_i)$ which has to be specified inside of \meta{key-value-config}.
+
+\begin{codeexample}[pre={\vbox\bgroup\hsize=3cm},post=\egroup]
+% load table from somewhere:
+\pgfplotstableread[row sep=\\]{
+ x y\\
+ 1 1 \\
+ 2 4\\
+ 3 9\\
+ 4 16\\
+ 5 25\\
+ 6 36\\
+}\loadedtbl
+
+% create the `regression' column:
+\pgfplotstablecreatecol[linear regression]
+ {regression}
+ {\loadedtbl}
+% store slope
+\xdef\slope{\pgfplotstableregressiona}
+
+\pgfplotstabletypeset\loadedtbl\\
+
+The slope is `\slope'.
+\end{codeexample}
+ \noindent The example above loads a table from inline data, appends a column named `|regression|' and typesets it. Since no \meta{key-value-config} has been provided, |x=[index]0| and |y=[index]1| will be used. The |\xdef\slope{...}| command stores the `$a$' value of the regression line into a newly defined macro `|\slope|'\footnote{The \texttt{\textbackslash xdef} means ``global expanded definition'': it expands the argument until it can't be expanded any further and assigns a (global) name to the result. See any \TeX\ book for details.}.
+
+ The complete documentation for this feature has been moved to \PGFPlots\ due to its close relation to plotting. Please refer to the \PGFPlots\ manual coming with this package.
+\end{stylekey}
+
\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.
@@ -2089,10 +2396,10 @@ The example creates two columns: the |new| column is just the sum of each value
\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}}
+ {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}
@@ -2166,7 +2473,9 @@ The example creates two columns: the |new| column is just the sum of each value
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.
+ |\pgfplotstablesave| uses the keys |reset styles| and |disable rowcol styles| to clear any typesetting related options.
+
+ Furthermore, it sets |string type| to allow verbatim output. You may want to use |numeric as string type| instead in case you only have numerical data -- this will display integers resulting from arithmetics not in scientific notation\footnote{Note however, that |string type| doesn't round or truncate integers as well, even though they are displayed as floats.}.
\begin{codeexample}[]
\pgfplotstablesave[
create on use/postproc1/.style={create col/dyadic refinement rate=error1},
@@ -2227,6 +2536,10 @@ This section summarizes features of |pgfkeys|. The complete documentation can be
Use |\pgfplotstableset{|\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/table|.
\end{handler}
+\begin{handler}{{.initial}=\marg{value}}
+ Defines a new \meta{key} and assigns \meta{value}.
+\end{handler}
+
\begin{handler}{{.add}=\marg{before}\marg{after}}
Changes \meta{key} by prepending \meta{before} and appending \meta{after}.
\begin{codeexample}[]
@@ -2334,9 +2647,11 @@ The value (2,0) is `\pgfplotsretval'.
\paragraph{Attention:} If possible, avoid using this command inside of loops. It is quite slow.
\end{command}
-\begin{command}{\pgfplotstablegetrowsof\marg{file name or \textbackslash loadedtable}}
+\begin{commandlist}{%
+ \pgfplotstablegetrowsof\marg{file name or \textbackslash loadedtable},
+ \pgfplotstablegetcolsof\marg{file name or \textbackslash loadedtable}}
Defines |\pgfplotsretval| to be the number of rows in a table\footnote{It will also assign \texttt{\textbackslash pgfmathresult} to the same value.}. The argument may be either a file name or an already loaded table (the \meta{\textbackslash macro} of |\pgfplotstableread|).
-\end{command}
+\end{commandlist}
\begin{command}{\pgfplotstablevertcat\marg{\textbackslash table1}\marg{\textbackslash table2 or filename}}
@@ -2383,7 +2698,7 @@ The value (2,0) is `\pgfplotsretval'.
\begin{pgfplotskey}{table/input colnames to=\marg{name} (initially colnames)}
Inside of |\pgfplotstabletranspose|, this key handles what to do with \emph{input} column names.
- Will create a further column named \meta{name} which will be filled with the input column names (as string type).
+ This key will create a further column named \meta{name} which will be filled with the input column names (as string type).
\begin{codeexample}[]
\pgfplotstabletranspose[input colnames to=Input]\loadedtable{pgfplotstable.example3.dat}
\pgfplotstabletypeset[string type]\loadedtable
@@ -2400,7 +2715,7 @@ The value (2,0) is `\pgfplotsretval'.
If \meta{list} is empty, all columns of the input table will be used (which is the initial configuration).
- If \meta{list} is not empty, it is expected to be a list of column names. Only these columns will be used as input for the transposition, just as if the remaining one weren't there. It is acceptable to provide column aliases or |create on use| arguments inside of \meta{list}.
+ If \meta{list} is not empty, it is expected to be a list of column names. Only these columns will be used as input for the transposition, just as if the remaining ones weren't there. It is acceptable to provide column aliases or |create on use| arguments inside of \meta{list}.
\begin{codeexample}[]
\pgfplotstabletranspose[columns={a,b}]\loadedtable{pgfplotstable.example3.dat}
\pgfplotstabletypeset[string type]\loadedtable
@@ -2410,6 +2725,75 @@ The value (2,0) is `\pgfplotsretval'.
\end{pgfplotskey}
\end{commandlist}
+\begin{command}{\pgfplotstablesort\oarg{options}\meta{\textbackslash resulttable}\meta{\textbackslash table or filename}}
+ Sorts \meta{\textbackslash table or filename} according to \meta{options} and writes the sorted table to \meta{\textbackslash resulttable}.
+
+ Use the high level |sort| key to enable sorting automatically during |\pgfplotstabletypeset|.
+
+\begin{codeexample}[]
+\pgfplotstablesort[row sep=\\]\result{%
+ a b c \\
+ 19 2 [a]\\
+ -6 -14 [b]\\
+ 4 -14 [c]\\
+ -11 -9 [d]\\
+ 11 14 [e]\\
+ -9 -9 [f]\\
+ 1 13 [g]\\
+ 8 -10 [h]\\
+ 16 18 [i]\\
+ 19 -6 [j]\\
+}
+\pgfplotstabletypeset[columns/c/.style={string type}]{\result}%
+\end{codeexample}
+
+ The sort key and comparison function can be customized using the following keys:
+ \begin{key}{/pgfplots/table/sort key=\marg{column} (initially [index]0)}
+ Specifies the column which contains the sort key. The argument \meta{column} can be any of the columns of the input table, including |create on use|, |alias| or |[index]|\meta{integer} specifications. The initial setting uses the first available column.
+ \end{key}
+ \begin{key}{/pgfplots/table/sort key from=\marg{table} (initially empty)}
+ Allows to load the |sort key| from a different \meta{table}, which can be either a \meta{\textbackslash macro} or a \meta{file name}.
+ \end{key}
+
+ \begin{key}{/pgfplots/table/sort cmp=\marg{less than routine} (initially float <)}
+ Allows to use a different comparison function.
+ \begin{pgfplotskeylist}{%
+ fixed <,
+ fixed >,
+ int <,
+ int >,
+ float <,
+ float >,
+ date <,
+ date >,
+ string <,
+ string >}
+ These styles constitute the predefined comparison functions. The |fixed <|, |int <| and |float <| routines operate on numerical data where |int <| expects positive or negative integers and the other two expect real numbers. The |fixed <| has considerably smaller number range but is slightly faster than |float <|.
+
+ The |date <| compares dates of the form |YYYY-MM-DD|. The |string <| uses lexicographical string comparison based on the ASCII character codes of the sort keys. The |string <| routine also evaluates ASCII codes of control sequences or active characters\footnote{As long as they haven't been consumed by \TeX's preprocessing.}.
+\begin{codeexample}[]
+\pgfplotstablesort[row sep=\\,sort cmp=string <]\result{%
+ Header:\\% the column name
+ the\\
+ quick\\
+ brown\\
+ fox\\
+ jumps\\
+ over\\
+ the\\
+ lazy\\
+ dog\\
+}
+\pgfplotstabletypeset[string type]{\result}%
+\end{codeexample}
+ \end{pgfplotskeylist}
+ \begin{codeargskey}{/pgfplots/iflessthan}{#1#2#3#4}
+ Allows to define custom comparison functions (a strict ordering). It compares |#1 < #2| and invokes |#3| in case the comparison is true and |#4| if not.
+ The comparison will be evaluated in local scopes (local variables are freed afterwise).
+ \end{codeargskey}
+ \end{key}
+\end{command}
+
\subsection{Repeating Things: Loops}
\begin{command}{\foreach \meta{variables} |in| \meta{list} \marg{commands}}
A powerful loop command provided by \Tikz, see~\cite[Section Utilities]{tikz}.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/texmf.cnf b/Master/texmf-dist/doc/latex/pgfplots/texmf.cnf
index 9a104eb686c..0d1f1d5198f 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/texmf.cnf
+++ b/Master/texmf-dist/doc/latex/pgfplots/texmf.cnf
@@ -21,7 +21,7 @@
% For some xy-pic samples, you may need as much as 700000 words of memory.
% For the vast majority of documents, 60000 or less will do.
%
-main_memory = 230000000 % words of inimemory available; also applies to inimf&mp
+main_memory = 30000000 % words of inimemory available; also applies to inimf&mp
extra_mem_top = 10000000 % extra high memory for chars, tokens, etc.
extra_mem_bot = 10000000 % extra low memory for boxes, glue, breakpoints, etc.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/todo.txt b/Master/texmf-dist/doc/latex/pgfplots/todo.txt
index baca906ec89..a64bbb6353b 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/todo.txt
+++ b/Master/texmf-dist/doc/latex/pgfplots/todo.txt
@@ -10,13 +10,13 @@ Testing
last test verifications:
pgf CVS pgf 2.00 pgf 2.00+compat=default
-pgfplotstests for 1.3.1 for 1.3.1 2009-12-30
-manual for 1.3.1 for 1.3.1
-pgfplotstable.pdf for 1.3.1 for 1.3.1
-example latex for 1.3 2009-12-30
-example context for 1.3 2009-12-30
-example plain tex for 1.3 2009-12-30
-tests context 2009-12-30
+pgfplotstests for 1.4 for 1.4 2009-12-30
+manual for 1.4 for 1.4
+pgfplotstable.pdf for 1.4 for 1.4
+example latex for 1.4 2009-12-30
+example context for 1.4 2009-12-30
+example plain tex for 1.4 2009-12-30
+tests context for 1.4
I NEED MORE TESTS!
The test suite needs to be developed!
@@ -34,6 +34,27 @@ The test suite needs to be developed!
+ test those tickpos num keys! especially in combination with axis line
variations. Also test ticklabel pos
+
+
+---------------
+pgfplots 1.4 todo:
+---------------
++ improve docs on alignment things
++ document how to make multi-line legends
++ document how to add custom things into a legend (add examples)
++ fix the \ref thing for legends/colorbar. It introduces a further stroke color
+ somehow.
++ check if the \ref thing for legends can suppress the hyperref link color.
++ incorporate the bugfix for 'point meta=f(x)'
++ should fix the "\numplots per plot handler" feature, i.e. should allow bar
+ plots / line plots in the same axis with 'ybar'.
++ document new regression feature in pgfplots.pdf (is currently in
+ pgfplotstable.pdf)
++ document new table input in pgfplots.pdf
++ fix bugs
++ update docs for external lib
+
+
---------------
pgfplots 1.3.1:
---------------
@@ -44,15 +65,15 @@ pgfplots 1.3.1:
+ critical: external lib and its backw. compat layer
perhaps I should disable them completely for the stable version?
There are no branches, either fully CVS or not at all.
-- import docs for recent number printing styles
++ import docs for recent number printing styles
+ set version number
+ set release dates for pgfplots.sty and pgfplotstable.sty
+ update ChangeLog to reflect the release and tag git
- update ubuntu PPA
-- upload sourceforge images
-- release makefile
-- CTAN: communicate sourceforge link
-- make short, summarized changelog:
+x upload sourceforge images
++ release makefile
++ CTAN: communicate sourceforge link
++ make short, summarized changelog:
- improved parametric plots with gnuplot
- improved normalsize, small and footnotesize scale styles and added tiny
- fixed a lot of bugs
@@ -72,9 +93,34 @@ MISC
+ disable pgfplots CVS?
- documentation todo:
- - pgfplots.sty: try to insert the SHA hash of the commit (for non-stable
+ - document the new 'getcolumnbyname={create col/....}' feature
+ + document linear regression
+ - document how to identify the source of "dimension too large" errors:
+ tracingstuff.
+ - external lib + dvi/ps + windows: it seems the ';' doesn't work; use '&' to
+ separate commands
+ - external lib: improve docs for how to deal with \label/\ref things and how
+ it works
+ - document how to fix dimension too large problems: restrict to domain for
+ example
+ + document \pgfresetboundingbox
+ + document how to plot against the column index
+ + colorbar sampled
+ + colorbar sampled line
+ - colorbar styles are not consistent between docs and code
+ - It seems as if the AMS command $\text{\ref{ref:to:a:plot}}$ instantiates the
+ \ref at least four times. Document somehow that it is better to use '\hbox'
+ instead
+ + pgfplots.sty: try to insert the SHA hash of the commit (for non-stable
versions)
- - pgfplotstable: the '[b]' option is mysterious in output listings. Hide it
+ -> echo '\def\pgfplotsrevision{'`git rev-parse HEAD`'}' >
+ tex/generic/pgfplots/pgfplots.revision.tex
+ -> this file shouldn't be part of the repo
+ -> load it from pgfplots.sty
+ -> should be updated during checkout and, probably, as post-commit
+ -> if it doesn't work: ok, then leave it blank.
+ try on windows.
+ + pgfplotstable: the '[b]' option is mysterious in output listings. Hide it
there!
- pgfplotstable: show how to use '\begin{longtable}'
+ gnuplot + parametric is not documented.
@@ -199,7 +245,12 @@ MISC
-------------------------------------------------------------
PGF / TikZ Development:
-------------------------------------------------------------
- - provide '\times' or more general formatting rules to number printer
+ - consider a matrix style which applies only to the outer matrix node style
+ (see feature request
+ https://sourceforge.net/tracker/?func=detail&atid=1060657&aid=3019259&group_id=224188
+ )
+ - code 2 args doesn't work correctly with spaces between the arguments!?
+ + provide '\times' or more general formatting rules to number printer
+ external lib: implement \tikzpicturedependsonfile#1
+ in pgfplots: invoke \tikzpicturedependsonfile.
perhaps the plot-from-table-struct should also use it.
@@ -216,8 +267,10 @@ PGF / TikZ Development:
+ in the manual, the first two arguments of
pgfqkeysactivatesinglefamilyandfilteroptions were inverted.
+ some predefined filters do not process unknown options correctly
- - external lib in pgf: think whether 'empty image extension' is a bug or a
+ + external lib in pgf: think whether 'empty image extension' is a bug or a
feature.
+ -> feature of \pgfimage! Otherwise it wouldn't be possible to provide an extension!
+ -> bug for external lib which never uses extensions!
- fix landscape bug (pdflscape) in external lib (PGF)
+ the pgf math parser has wrong precedence for '-' prefix op:
exp(-x^2) is wrong.
@@ -233,6 +286,216 @@ PGF / TikZ Development:
BUGS / FIXES
-------------------------------------------------------------
+- groupplots + extra braces or \foreach are incompatible.
+
+- clickable and Windows Acrobat Reader 9 has been reported to fail
+
+- /pgfplots/samples at and /tikz/samples at work on the same axe. Tantau says that this key support \foreach statement and thus the dotes notation. Howerver, when I want to use two or more different dots notation within pgfplots, latex crashes !
+Here is an example which clarify this issue :
+\addplot+[mark=none,variable={\t}, samples at = {\foreach \x in {0,10,...,180,200,...340} {\x, }360}] ({sin(t*2)}, {cos(t)});
+
+- potential incompatibility: clickable and external. The clickable lib writes
+ into pgfplots.djs which might cause multithreaded problems.
+
+- groupplots: mixing 2d/3d in one groupplot doesn't reset 'zmin,zmax' ?
+
+
+- 'clip=false' does not disable marker clipping!
+
+- mark position clipping may fail: see
+ \begin{tikzpicture}
+ \begin{axis}
+ \addplot3[surf,shader=faceted,
+ scatter,mark=*,
+ samples=10,domain=0:1]
+ {x^2*y};
+ \end{axis}
+\end{tikzpicture}
+ in the manual (shader docs)
+
+- multiple ordinates: grid lines are drawn on top of function plots; that's bad.
+Check:
+ I think you have to change the process line previousely invoked, and make the axes generation at the end :
+1. generating adequate grid --> 2. plotting functions --> 3. creating axes, tick nodes...
+You can take a minute look at figure 1 @ "The \addplot Command: Coordinate Input" section 4.2 p 19.
+and you can remark that colour filling overlaps x- and y-axis ! So I suggest that you use "excute at end picture=<axis generation code>" tikz option or similar to avoid this issue.
+
+- patch plots: type rectangle & shader=interp & mesh input=patches doesn't work
+ correctly as it seems.
+
+- 3D axes: it is difficult to get an 1:1 correspondence to tikz.
+
+- 3D axes: providing three unit vectors is not sufficient, one also needs to set
+ 'view={}{}'. That should be done automatically.
+
+- 3D axes: Providing three unit vectors manually yields incorrect axis
+ initialisation.
+
+- 3D axis: provide support for manual axis configuration,
+ - depth (n vector),
+ - foreground/background,
+ - tick label axes,
+ - ...
+
+- Patch plots: directly transform cdata. Should simplify interpolation during
+ refine/triangulation etc. and shouldn't make a difference otherwise.
+
+manual errors of given pgfplots_unstable version:
+ 94 2.5.12 \addplot+[patch] --> \addplot3+[patch]
+162 "xmode, ymode, zmode" and "x dir, ..."
+ come again on page 177
+
+- don't loose \ref's when externalizing
+ I'll provide a minimal later
+
+
+- incompatibility pdfpages (most recent version), MikTeX and tikz external lib
+ (something with shipout routine)
+
+- plot graphics: \ref legend doesn't work properly
+
+- french babel and colorbars are not fully compatible. The problem is that
+ colorbars use '\addplot graphics {};' with a fixed catcode for the ';' --
+ which might lead to problems.
+
+- \ref{} legends for 'surf' in unstable version do not work properly
+
++ plot graphics braucht
+ every legend image post/.append style={sharp plot}
+
+- markers should not be drawn on top of everything else. Always restore the
+ clipping region for each plot.
+
++ extra ticks need a scope to enable drawing options:
+ \begin{axis}[
+ extra x ticks={0.7},
+ extra x tick style={
+ line width=3mm,
+ color=red,
+ tickwidth=3mm, % <-- only thing applied
+ },
+ ]
+ \addplot coordinates { (0,0) (1,1) };
+ \end{axis}
+
+
++ new coordmath framework is broken for log basis.
+ TODO: 1. the functions must be parameterized with A) the coordmath class *and*
+ B) the coordmathid.
+ For example 'pgfmath,x' and 'pgfmath,y'. Everything else doesn't work...
+
+- \ref and detached legends/colorbars do NOT work with external library and
+ convert with system call.
+ -> provide special handling!
+
++ providing 'thick' to linespecifications causes problems during the survey
+ phase: \pgfmathsetlength{} will use the FPU.
+
+- shader=interp,z buffer=sort ---> should use 'shader=faceted interp,faceted
+ color=none,z buffer=sort' instead!
+
+- mesh/patch plots:
+ - jump thing + z buffer=sort probably doesn't work
+
+- ternary axes: the 'marker clipping' doesn't work (naturally)
+
++ shader=interp: I stumbled over a data set for which gv,xpdf,kpdf and acrobat
+ bail out with an error. (data file in feuersaenger's thesis)
+ ---> That's y varies! For x varies, it works!
+
+- polar axes:
+ + is wrong since 'near ticklabel' anchor uses pointunitx which is not correctly initialised for polar axes.
+ - axis equal
+ + data scaling needs to be disabled for X axis.
+ + auto tick labels work only for the case of disabledatascaling
+
+- contour:
+ the table/meta=2 default is wrong.
+
+- OK : 'every node near coord/.append style={scale=0.7}'
+ NOT OK: 'every node near coord/.append style={scale=0.7},ybar'
+ --> sequence of shift and scale matters ...
+
+- french babel and colorbars are not fully compatible. The problem is that
+ colorbars use '\addplot graphics {};' with a fixed catcode for the ';' --
+ which might lead to problems.
+
+- OK : 'every node near coord/.append style={scale=0.7}'
+ NOT OK: 'every node near coord/.append style={scale=0.7},ybar'
+ --> sequence of shift and scale matters ...
+
++ shader=interp: I stumbled over a data set for which gv,xpdf,kpdf and acrobat
+ bail out with an error. (data file in feuersaenger's thesis)
+ ---> That's y varies! For x varies, it works!
+
+- dimension too large sanity checking: TeX uses the maximum value instead.
+ Perhaps that can be checked?
+
+- provide remark at end document "Package pgfplots: consider using the preamble
+ command \pgfplotsset{compat=1.3} to improve label placement"
+
+- there are a lot of .code 2 args styles which do not support spaces between
+ their arguments. Fix this.
+
+- colormap serialization has N^2 runtime.
+
+- `1.23456e4;' in a log plot resulted in hard-to-read error messages. Improve
+ sanity checking here.
+
+- stack plots + log scale is wrong: it stacks visually, but that's more or less
+ meaningless. Try
+ \begin{tikzpicture}
+ \begin{semilogyaxis}[
+ ybar stacked,
+ ymin=1e1, ymax=1e6,
+ ]
+ \addplot coordinates { (1,100) (2,100) };
+ \addplot coordinates { (1,100) (2,1000) };
+ \end{semilogyaxis}
+ \end{tikzpicture}
+
+- the title style for 'footnotesize' is not as I want it to: it doesn't respect
+ the depth below the baseline. Or does it need a \strut?
+
++ the 'enlarge x limits={abs=3}' key doesn't work: it increases the lower
+ limits, but it doesn't draw any tick labels (neither major nor minor)
+
+
++ portability of externalized \label commands: define \tikzifinpicture which
+ should be part of the external separate package (in which case it is always
+ false).
+
+- avoid dimension too large errors which occur due to a data range restrictions.
+ Example:
+ data range = 0:6000
+ view range = 0:1
+ -> results in error.
+ But that's easy to detect! Just compute the point coordinate in float (after
+ the scaling is complete). Then, install a filter somewhere. perhaps an "a
+ posteriori" filter in the pointxyz command?
+
+- the 'colorbar sampled line' and 'colorbar left' styles are incompatible:
+ there are no tick lines.
+
+X bug in linux printer drivers: colorbar shadings are not interpolated
+ correctly, the interp shadings work (also the colormap sampled style).
+ Version:
+ Linux 2.6.24-26-generic #1 SMP Tue Dec 1 17:55:03 UTC 2009 x86_64 GNU/Linux
+
+
++ the colorbar with surf mode is too short; the 3D colorbar axis won't be scaled correctly
+
+- the 'at' key appears to be broken. It happens if
+ - pgf 2.00 is used,
+ - at=(anode) is used where (anode) was originally in a different axis
+
+- the autodetection of the '\\' list format is buggy: it should return true if
+ and only if the last element is '\\', not if '\\' occurs inside of the
+ argument.
+
++ gnuplot compatibility is broken since gnuplot 4.4 changed its table format for
+ logscale. Excellent.
+
+ the \pgfplots@ifgridlines@onorientedsurf@should@be@drawn#1#2 is WRONG.
It works ONLY for boxed axes. All others need special handling...
@@ -266,13 +529,15 @@ BUGS / FIXES
- unbounded inputs: improve warning messages: they should not contain low level
FPU args.
-- in tick label reference: the example with \nicefrac has ymajorgrids, but
++ in tick label reference: the example with \nicefrac has ymajorgrids, but
doesn't display them! Check!
->>>>>>> origin/stable:doc/latex/pgfplots/todo.txt
- parametric gnuplot plots do not work correctly (see mail of Gabriel Lera)
+ -> require user interface method to set 'variable' and 'variable y' for this case.
+ Default should be 't' and 'u,v' !
- the user interface to set 'tickwidth=0' for a SINGLE axis is not very good: it seems one needs 'xtick style={/pgfplots/tickwidth=0}' to do so...
+ -> can be solved if tickwidth has a family, I guess. Something like 'draw' which will not be pulled by pgfplots. But then remains a problem of key paths.
+ the tick pos stuff works (puh!)
@@ -287,7 +552,7 @@ BUGS / FIXES
probably should (tests in pgfplotstest.axislines.tex).
-> check also display styles for labels!
-- manual: 'label style' and 'xticklabel style' are not auto-crossrefed
++ manual: 'label style' and 'xticklabel style' are not auto-crossrefed
+ extra ticks do not work with '3d box=complete'
@@ -310,9 +575,6 @@ BUGS / FIXES
-> I improved them for 2d and 3d
-> needs some further checks, I guess
-- the every colorbar style is more or less unusable because it is redefined by
- the 'color horizontal' styles etc. Is there something more intelligent?
-
+ reversed axes:
+ color bars can't be reversed; the shading disappears
+ reversed axes and centered axis lines:
@@ -326,7 +588,7 @@ BUGS / FIXES
FIXME
- tickpos is wrong
-- coordinate filters for log axis are not as documented: the 'unbounded coords' key won't be processed correctly.
++ coordinate filters for log axis are not as documented: the 'unbounded coords' key won't be processed correctly.
- providing zmin/xmax to an axis activates 3D mode, ok -- but lower dimensional input routines appear to fail.
@@ -346,9 +608,7 @@ prints without complaint). 27.11.2009 reported by J. Goebel
Is that still up-to-date? NO
Perhaps it should be replaced with something better? YES
-- |xlabel near ticks| links to |xlabel| in manual
-
-- recently, I used \pgfplots@command@to@string. But: for arguments like `\table' this yields `\table ' including a space. Check if that poses harm.
++ recently, I used \pgfplots@command@to@string. But: for arguments like `\table' this yields `\table ' including a space. Check if that poses harm.
+ the pretty printer appends '{}' to known csnames.
+ the pretty printer appends ')' to |(|
@@ -454,9 +714,6 @@ X change UI of ticklabel cs: provide an option 'ticklabel cs:[<interpreter>]<coo
- the ybar style won't be set inside of \label{}
-- fix the bug-related FIXMEs in src
- -> collect them:
- -
+ providing 'ybar stacked' to the axis and 'ybar' to each plot seems to cause
problems (see test case per Mail)
@@ -540,12 +797,12 @@ X change UI of ticklabel cs: provide an option 'ticklabel cs:[<interpreter>]<coo
Idea: implement all that stuff when 'every axis' is used. But that has
'/tikz/' has default search path...
-- I fear plot gnuplot may not reflect the latest changes - at least not for 3D!
- - log basis
- - plots R^1 -> R^3 (parametric)
++ I fear plot gnuplot may not reflect the latest changes - at least not for 3D!
+ + log basis
+ + plots R^1 -> R^3 (parametric)
+ plots R^2 -> R^3 (parametric)
-> may require 'u' and 'v'
- - using other variable names (see 'set dummy')
+ + using other variable names (see 'set dummy')
+ ydomain is not set
+ the \x, \y, \z etc. macros in the table expression plotter should be
@@ -1173,11 +1430,225 @@ X verschiebung des ylabels ist komisch, wegen der rotate option
FEATURES
-------------------------------------------------------------
-- external lib + makefile support: provide data files automatically as prereqs
+- nested axes would be a nice feature.
+ TODO:
+ - update the list of global state variables
+ - "interrupt" these variables somehow.
+ - make sure local redefinitions of TikZ commands (like point commands)
+ work; the \let...@orig= assignments should be handled somehow.
+ - What about keys? They will be inherited from the outer axis...
+ perhaps the best would be an
+ \endgroup
+ <nested axis>
+ \begingroup
+ <restore state>
+ which includes the keys of the outer axis!?
+
+- support for "spy"glass into particular parts of an axis
+
+- groupplots: group-wide axis labels
+
+- It would be really great to have the possibility to attach a style to every nth row of a data table. For example, I would like to have a \midrule not after every line or after odd/even lines but after every fifth (or whatever) line.
+
+
+
+- new \plotnumofactualtype thing: if you set /tikz/ plot handlers in
+ \begin{axis}, they won't be set before the visualization phase. consequently,
+ I can't con't them!
+ Idea: add a 'family' to each of them. Or wright a coord filter which checks
+ for \tikz@plot@handler . Or write pgfplots styles which set them.
+
+- improve access to `create on use' things in \addplot table.
+ Ideas:
+ - check if a `create on use' statement for table/[xyz] exists, if so: load the complete
+ table.
+ - allow a simplified syntax like 'y=create col/linear regression{<args>}'.
+ This should be possible; just introduce a temporary name (or column
+ index).
+
+- Mail by Hubertus Bromberger:
+ + Period in legend, without the need of using the math environment?
+ \legend{ML spcm$.$, CW spcm$.$, ML AC};
+ - Maybe a more straight forward way for legend to implement something like
+ shown in the graph. (see his mail .tex)
+ -> plot marks only at specific points.
+ thus, the legend image should contain both lines and marks, but there
+ are effectively two \addplot commands.
+ - As a physicist, I often have the problem to fit curves. A job gnuplot can do
+ very well. It should be possible using "raw gnuplot" but maybe you can either
+ provide an example or even implement a more straight forward way for this
+ purpose.
+ - The color scheme is not really my taste.
+ In CONTEXT:
+ cycle list={%
+ {Col1,mark=*},
+ {Col2,mark=square*},
+ {Col3,mark=diamond*},
+ {Col4,mark=star},
+ {Col5,mark=pentagon*},
+ {Col6,mark=square*},
+ {Col7,mark=diamond*},
+ {Col8,mark=triangle*} }}
+
+ \definecolor[Col1][r=0.24106,g=0.05490,b=0.90588] % blau
+ \definecolor[Col2][r=1,g=0.05490,b=0.06667] % rot
+ \definecolor[Col3][r=0.65490,g=0.73333,b=0.01176] % grün
+ \definecolor[Col4][r=0.08627,g=0.92549,b=0.91373] % tyrkis
+ \definecolor[Col5][r=1,g=0.5,b=0] % orange
+ \definecolor[Col6][r=0.54118,g=0.51765,b=0.51765] % grau
+ \definecolor[Col7][r=0.80784,g=0.49804,b=0.06275] % okker
+ \definecolor[Col8][r=0.74902,g=0.07451,b=0.91765] % lila
+ - Sometimes it would be good to have a bit more of a programming language, but
+ still that's not what tex is made for. The python-script looks promising, it's
+ just, that I think it doesn't work with context.
+
+- add something like
+ \pgfplotstabletypeset[
+ cell { 1 }{ 2 }={\multirow{*}{3}{text}}
+ ]
+
+- I got several feature requests for non-cartesian axes.
+ Perhaps there is a way to generalize the complete procedure... as far as I
+ remember, I use the pointxyz routines anyway to place tick marks and so on.
+ Perhaps it can be reconfigured to do something "advanced".
+ Idea: nonlinear transformation into the axis combined with special drawing
+ rotuines for the axis?
+ ternary diagrams
+ http://staff.aist.go.jp/a.noda/programs/ternary/ternary-en.html.
+ smith charts
+ http://www.mathworks.com/access/helpdesk/help/toolbox/rf/f2-999699.html
+ http://www.siart.de/lehre/smithdgr.pdf
+
+- idea: 'mesh/ordering=auto'. Just check for 'x varies' and 'y varies'! The two
+ first points inside of a scanline are enough.
+
+- it is possible to output contour data into files with gnuplot (and with
+ matlab):
+ unset surface
+ set contour
+ # set cntrparam ...
+ set table 'P.dat'
+ splot [x=0:1] [y=0:1] x*y;
+ unset table
+ # contour info now in filename
+- contourf: I guess filled contour plots could be possible if always two
+ adjacent color levels are combined into a single path which is then filled
+ with the simplified even/odd rule (not the winding fill rule). With the
+ underlying smoothness assumption C^0, there can't be any level between two
+ adjacent ones, and there can't be self-intersections.
+- it would be very interesting to allow more flexible handling of empty lines in
+ input data, especially files.
+ For example 'empty lines=auto|scanline|nan|jump' -> allows to use "interrupted
+ line plots" -> contour!
+ Implementation ideas:
+ - in table: check the mode. If "nan|jump" and "previous coord was no jump":
+ insert a "nan nan nan.... nan" line into the table.
+ - in plot coords: same, but it is simpler.
+ - perhaps I can implement the stuff like \pgfplotsscanlinecomplete: it
+ should stream a coordinate if it fails. The coordinate will use
+ x=inf,y=inf,z=inf and all remaining fields are kept from the last valid
+ coordinate. Should not hurt...
+ - the choice "auto" could be used as follows:
+ 3d plot ---> use "scanline"
+ 2d plot ---> use "nan"
+
+- interesting: add "path after line segment". Idea: allow nodes on the path
+ \tikz \draw (0,0) -- (3,1)
+ node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
+ -> perhaps such a feature can be the low level implementation for contour
+ labels.
+ Problems: how should the positions be determined automatically? Overlap should
+ be reduced somehow.
+ furthermore, a contour uses more than one path...
+
+
+
++ colorbar styles:
+ - colorbar flat
+ - colorbar faceted
+ -> use \addplot3[surf] to draw a colorbar
+ - colorbar scatter
+ -> use \addplot3[scatter] to draw a colorbar
+ -> requires to set samples, and to use plot expression. Should be enough...
+
+- implement simplified constructions to access DIFFERENCE coordinates.
+ For example, \draw ellipse needs x radius and y radius.
+
+
++ allow to anchor an axis at any labeled node inside of it (like for a matrix)
+
+- it might be interesting to fill the area between two paths. Perhaps there is
+ such a feature in pgf; or perhaps I can generalize the \closedcycle
+ implementation written for stacked plots.
+
+- provide a \numplotsperplothandler or something like that. This would improve
+ things for bar plots!
+
+- the 'table/y index' should be changed. It should be min(numcols,1) instead of 1.
+
+- table package & axes should improve their communication.
+ Namely:
+ - communicate table names.
+ - communicate xmode/ymode
+ - communicate log basis [xy]
+
++ provide col sep=&
+
+- provide and document access to (sanitized?) mesh/rows and mesh/cols fields
+ during the survey phase. This might allow 2d key filters
+
+- Praktisch fände ich, wenn man folgende Dinge spezifizieren kann:
+
+1. Welche Zeilen aus der Datei ausgelesen sollen (häufig gibt es nicht
+nur 1, sondern mehrere Header-Zeilen, oder auch am Ende noch sonstige
+Zeilen)
+
+2. Welche Zeichen in der Datei schlicht ignoriert werden.
+
+Damit würde ich es mir sparen, mein Ausgabeformat anzupassen.
+Derzeit ist dies jedoch für mich die einfachste Lösung.
+
+- the coordindex shouldn't be changed by z buffer=sort
+
+- table package: provide abstract layer for low level storage interface.
+ Idea: the interface should allow the container interface
+ - push_back()
+ - get(i)
+ - set(i)
+ - foreach()
+ - pop_front()
+ - newempty()
+ - clone()
+ - unscope()
+ - startPushBackSequence()
+ - stopPushBackSequence()
+ -> this could allow to use arrays for fast algorithms. At least it would make
+ things easier to read.
+ Problem as always: the 'unscope()' operation.
+ Currently, I have two different structures: the applists which have fast
+ construction properties and the standard lists which implement the rest.
+ Can I combine both? Yes, by means of the incremental construction pattern:
+ \startPushBackSequence
+ \push_back
+ \push_back
+ \push_back
+ \stopPushBackSequence
+ -> inside of the construction, only \push_back is allowed and the structure is
+ in "locked state" (low level: applist repr)
+ -> Idea: the creation is fast, afterwards, it has flexibility.
+
++ external lib + makefile support: provide data files automatically as prereqs
+
+- support \multicolumn for legends
+
+- it appears line breaks in legend descriptions are a problem (?)
+ -> bug in pgf: \\ is overwritten and won't be restored.
+
++ external lib + makefile support: provide data files automatically as prereqs
- pgfplotstable file open protocol: provide public listener interface
-- allow to advance cycle list(s) manually
++ allow to advance cycle list(s) manually
- \addplot coordinates {\macro};
@@ -1224,7 +1695,7 @@ FEATURES
Perhaps its better to check if the argument is a macro (at creation time, thus only once) and call \edef#1{\string#1} to assign some sort of name to it.
This will invoke \string only once. Is this faster?
-- implement 'point meta=symbolic command:<cmd>' and 'point meta=command:<cmd>'
++ implement 'point meta=symbolic command:<cmd>' and 'point meta=command:<cmd>'
the command should assign '\pgfplotsretval'
+ It would be a valueable addition if the external lib would be available for the next stable release.
@@ -1458,7 +1929,7 @@ style={at={(0.05,0.05)},anchor=south west}' or something similar.
+ provide a simpler method to replace the '\cdot' in tick scale labels with a
different sign, for example '\times'.
-- provide a feature for bar plots which add the bar value as node on top of the
++ provide a feature for bar plots which add the bar value as node on top of the
bar.
Idea: provide some sort of "every coordinate path" - an optional feature which
has access to both, the logical coordinates and the low level path coordinates
@@ -1634,9 +2105,9 @@ dictionary)
-- provide a public basic level API to pgfplotstable:
- - access, iterate and read table elements
- - manipulate elements
++ provide a public basic level API to pgfplotstable:
+ + access, iterate and read table elements
+ + manipulate elements
+ binary input subroutines:
use a simply scaling for dimen registers. The scaling should be such it maps
@@ -1805,29 +2276,7 @@ dictionary)
The \prevrow and \nextrow features won't be possible (?)
- improve support for multiple ordinates
-- improve support for negative (reversed) axes
- - 'x dir =-1' -> scale automatically
- - x=-5.5cm, yticklabel pos=right, yticklabel style=left
- could be a style (combined with x dir)
- - the anchor names are now strange - they are mirrored :-(
- \begin{tikzpicture}
-
- \begin{axis}[
- title={Test},
- xlabel={Time [s]},
- ylabel={Segment},
- x=0.9cm, y=-0.9mm,
- %xlabel style={at={(0.5,1)}},
- %ylabel style={yshift=-6pt},
- %title style={at={(0.5,0)}},
- %xticklabel style={yshift=-6mm},
- %xticklabel pos=top,
- ]
-
- \addplot plot coordinates {(0,30) (3,0) };
- \end{axis}
- \end{tikzpicture}
- - furthermore tick scale labels should be shifted
++ improve support for negative (reversed) axes
@@ -1857,13 +2306,9 @@ dictionary)
- 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
++ 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 provide 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.
@@ -1915,29 +2360,8 @@ X the coordinate preparation routines should assign global registers. This would
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
++ provide 'only each nth coordinate' or so as style on top of 'x filter'.
+
+ implement simply style 'scatter classes'.
+ sanity checking feature: try if 'pgfmathfloattofixed' results in a known
@@ -1959,21 +2383,12 @@ X the coordinate preparation routines should assign global registers. This would
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
@@ -2023,8 +2438,6 @@ X perhaps I can use pdf line annotations to improve clickable lib?
+ 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.
@@ -2160,18 +2573,6 @@ X re-implement 'dec sep align' of table package natively, not as high-level
allows something like 'columns={A,B,A,B,A,B}' and distributes entries of input
columns A and B equally to output columns.
-+ TDS directory structure is not completely correct. Should be everything under
- directory 'pgfplots':
- $package = "pgfplots";
- &SYSTEM ("$MV README ext_scripts test doc/generic/$package/");
- &SYSTEM ("$MV generic tex/generic/$package/");
- &SYSTEM ("$MV context latex plain tex/");
- and context files should be in
- tex/context/third/pgfplots/...
- doc/context/third/pgfplots/...
- (reference: mail conversation with Karl Berry)
-
-
+ automatic disabling of enlargelimits when axis lines are not drawn as a box
+ copy my personal' homepages short images to pgfplots website
@@ -2179,7 +2580,7 @@ X re-implement 'dec sep align' of table package natively, not as high-level
+ interrupt single plots at discontinuities (for example tan(x))
-> don't draw from +infty to -infty
-- optimize plot expression
++ optimize plot expression
+ optimize tick generation code for speed